sqlpush 0.1.0__tar.gz

sqlpush-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: sqlpush
+Version: 0.1.0
+Summary: Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models
+Keywords: sqlalchemy,alembic,postgresql,timescaledb,prisma,schema,migrations,database,drift,cli
+Author: Juan Miguel Contreras
+Author-email: Juan Miguel Contreras <19253629+juanmicl@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Dist: alembic>=1.18,<2
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.12
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/juanmicl/sqlpush
+Project-URL: Repository, https://github.com/juanmicl/sqlpush
+Project-URL: Issues, https://github.com/juanmicl/sqlpush/issues
+Project-URL: Changelog, https://github.com/juanmicl/sqlpush/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# sqlpush
+
+[![CI](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml/badge.svg?style=for-the-badge)](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
+[![Python](https://img.shields.io/pypi/pyversions/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)
+
+**Prisma `db push` for SQLAlchemy.** Apply your models (SQLAlchemy,
+SQLModel, anything built on `MetaData`) to a live PostgreSQL / TimescaleDB
+database directly, no migration files. sqlpush
+diffs your models against the real schema, classifies every operation by
+risk (safe / risky / destructive), and applies the plan atomically. Drift
+checks exit with codes your CI can gate on.
+
+```console
+sqlpush diff "myapp.models:metadata"      # see the SQL, ordered by risk
+sqlpush check "myapp.models:metadata"     # CI gate: exit 0/2/3
+sqlpush push "myapp.models:metadata"      # apply (destructive gated)
+```
+
+If you've ever run `Base.metadata.create_all()` in production and known it
+was wrong, then sighed at the migration-script treadmill when you reached
+for alembic: sqlpush is for you.
+
+## Why
+
+Declarative models are already the source of truth. Migration files
+re-encode what the models say, drift from them, and pile up forever.
+sqlpush closes the loop the way Prisma's `db push` does for its schema
+language, but for the SQLAlchemy ecosystem (SQLModel included):
+
+- **No migration files, ever.** The diff *is* the migration: computed fresh
+  from models vs. live database on every run, via alembic's autogenerate
+  engine used as a library.
+- **Risk-aware by default.** Every operation is classified `safe` /
+  `risky` / `destructive`. Destructive ops (drops) are **blocked until
+  `--allow-destructive`**: nothing executes at all while any is present.
+- **Drift detection built for CI.** `check` plans once and exits `0` clean /
+  `2` drift / `3` destructive drift, scriptable without parsing output.
+  `--json` emits a stable versioned contract.
+- **Safe under concurrency.** An advisory lock (keyed to the database, not
+  the DSN) coordinates workers: one pusher at a time, losers wait bounded
+  and re-verify, so deploy pipelines can race without corrupting anything.
+- **Hypertables without hand-written SQL.** Decorate a model with
+  `@hypertable` and the `create_hypertable` directive is planned
+  state-aware: idempotent pushes, clean checks, no false drift.
+
+PostgreSQL only, by design.
+
+## Install
+
+```console
+pip install sqlpush
+```
+
+Or from source:
+
+```console
+git clone https://github.com/juanmicl/sqlpush && cd sqlpush && uv sync
+```
+
+## The 30-second tour
+
+Point sqlpush at your metadata (`module:attribute`) and a database
+(`--dsn` or `$DATABASE_URL`):
+
+```console
+$ export DATABASE_URL="postgresql+psycopg://user:pass@host:5432/db"
+
+$ sqlpush diff "myapp.models:metadata"
+-- safe
+
+CREATE TABLE hero (
+    id SERIAL NOT NULL PRIMARY KEY,
+    name VARCHAR(50) NOT NULL
+);
+
+-- risky
+
+CREATE INDEX ix_hero_name ON hero (name);
+```
+
+Push it (the destructive gate is on by default):
+
+```console
+$ sqlpush push "myapp.models:metadata"
+1 destructive operation(s) blocked; re-run with --allow-destructive
+$ echo $?
+1
+
+$ sqlpush push "myapp.models:metadata" --allow-destructive
+$ echo $?
+0
+```
+
+In CI, check drift and fail loudly (see exit codes below). Limit scope with
+repeated `--schema` / `--exclude` options.
+
+## Exit codes
+
+| verb | 0 | 1 | 2 | 3 |
+| --- | --- | --- | --- | --- |
+| `diff` | always | | | |
+| `check` | clean | | drift | destructive drift |
+| `push` | applied | destructive blocked | error (incl. partial failure) | |
+
+`push --safe-only` runs only safe operations and skips the rest
+informationally (exit `0`). A failed `CREATE INDEX CONCURRENTLY` marks the
+run as partial failure (exit `2`) instead of silently half-applying.
+
+## FastAPI / SQLModel: replace `create_all`
+
+```python
+from contextlib import asynccontextmanager
+from sqlpush import aensure_schema
+
+
+@asynccontextmanager
+async def lifespan(app):
+    await aensure_schema(SQLModel.metadata, engine, mode="check")
+    yield
+```
+
+Push in the deploy pipeline, check at startup.
+
+## How it works
+
+```mermaid
+flowchart LR
+    models["SQLAlchemy MetaData"] --> diff["diff<br>alembic autogenerate, scoped"]
+    db[("live PostgreSQL")] --> diff
+    diff --> risk["risk classification<br>safe / risky / destructive"]
+    risk --> plan["plan"]
+    plan --> render["render"]
+    render --> apply["apply<br>atomic txn · CONCURRENTLY split · advisory lock"]
+    apply --> report["report"]
+```
+
+- **Diff engine** scopes reflection to your target schemas (default: the
+  session's real `search_path`) and prunes system catalogs (TimescaleDB
+  internals included) before reflection even starts.
+- **Classifier** maps each operation to a risk class; unknown operations
+  are `risky`, never silently safe.
+- **Executor** splits the plan: `CONCURRENTLY` statements run one-per-
+  transaction on autocommit, everything else applies in a single atomic
+  transaction with a bounded `lock_timeout`.
+- **Typed errors**: only `SqlpushError` / `ConnectFailed` /
+  `MetadataImportError` escape the API, never raw driver exceptions.
+
+## Comparison
+
+An honest view of the neighborhood (stars as of 2026-08):
+
+| | migration files | source of truth | risk gate | CI drift exit codes | TimescaleDB |
+| --- | --- | --- | --- | --- | --- |
+| **sqlpush** | none (the diff is the migration) | SQLAlchemy `MetaData` | classified safe/risky/destructive, destructive blocked by default | `check` 0/2/3 | `@hypertable` directives |
+| [alembic](https://github.com/sqlalchemy/alembic) (4.4k★) | yes | migration scripts (autogenerate assists) | no | no | no |
+| [atlas](https://github.com/ariga/atlas) (8.7k★) | optional (HCL) | HCL / SQL (ORMs via providers) | lint policies | yes | no |
+| [prisma `db push`](https://www.prisma.io/docs/orm/reference/prisma-cli-reference) (47k★) | none | Prisma schema (Node/TS) | no | no | no |
+| [migra](https://github.com/djrobstep/migra) (3.1k★) | diff only | SQL | n/a | partial | no (*deprecated*) |
+
+sqlpush is narrower than atlas and younger than alembic, deliberately.
+It is one tool for one job: keep a PostgreSQL schema in lockstep with
+SQLAlchemy models, safely enough to run from CI.
+
+Coming from [migra](https://github.com/djrobstep/migra) (now
+deprecated)? There is a [migration guide](docs/migrating-from-migra.md).
+
+## Design notes
+
+- `import sqlpush` stays light: the public API loads lazily, so the
+  annotations module carries none of alembic/typer/psycopg.
+- The advisory-lock key derives from the database OID: two DSN spellings
+  of the same database contend for the same lock.
+- `--json` output is a versioned contract (`"version": 1`) meant for
+  tooling; additive changes only within a version.
+
+## Roadmap (0.1.x)
+
+- `CREATE INDEX CONCURRENTLY` by default for indexes on existing tables
+- asyncpg DSN translation in `ensure_schema(AsyncEngine)`
+- jsonschema-validated `--json` output
+
+## License
+
+[MIT](LICENSE) · © 2026 Juan Miguel Contreras

sqlpush-0.1.0/README.md

@@ -0,0 +1,186 @@
+# sqlpush
+
+[![CI](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml/badge.svg?style=for-the-badge)](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
+[![Python](https://img.shields.io/pypi/pyversions/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)
+
+**Prisma `db push` for SQLAlchemy.** Apply your models (SQLAlchemy,
+SQLModel, anything built on `MetaData`) to a live PostgreSQL / TimescaleDB
+database directly, no migration files. sqlpush
+diffs your models against the real schema, classifies every operation by
+risk (safe / risky / destructive), and applies the plan atomically. Drift
+checks exit with codes your CI can gate on.
+
+```console
+sqlpush diff "myapp.models:metadata"      # see the SQL, ordered by risk
+sqlpush check "myapp.models:metadata"     # CI gate: exit 0/2/3
+sqlpush push "myapp.models:metadata"      # apply (destructive gated)
+```
+
+If you've ever run `Base.metadata.create_all()` in production and known it
+was wrong, then sighed at the migration-script treadmill when you reached
+for alembic: sqlpush is for you.
+
+## Why
+
+Declarative models are already the source of truth. Migration files
+re-encode what the models say, drift from them, and pile up forever.
+sqlpush closes the loop the way Prisma's `db push` does for its schema
+language, but for the SQLAlchemy ecosystem (SQLModel included):
+
+- **No migration files, ever.** The diff *is* the migration: computed fresh
+  from models vs. live database on every run, via alembic's autogenerate
+  engine used as a library.
+- **Risk-aware by default.** Every operation is classified `safe` /
+  `risky` / `destructive`. Destructive ops (drops) are **blocked until
+  `--allow-destructive`**: nothing executes at all while any is present.
+- **Drift detection built for CI.** `check` plans once and exits `0` clean /
+  `2` drift / `3` destructive drift, scriptable without parsing output.
+  `--json` emits a stable versioned contract.
+- **Safe under concurrency.** An advisory lock (keyed to the database, not
+  the DSN) coordinates workers: one pusher at a time, losers wait bounded
+  and re-verify, so deploy pipelines can race without corrupting anything.
+- **Hypertables without hand-written SQL.** Decorate a model with
+  `@hypertable` and the `create_hypertable` directive is planned
+  state-aware: idempotent pushes, clean checks, no false drift.
+
+PostgreSQL only, by design.
+
+## Install
+
+```console
+pip install sqlpush
+```
+
+Or from source:
+
+```console
+git clone https://github.com/juanmicl/sqlpush && cd sqlpush && uv sync
+```
+
+## The 30-second tour
+
+Point sqlpush at your metadata (`module:attribute`) and a database
+(`--dsn` or `$DATABASE_URL`):
+
+```console
+$ export DATABASE_URL="postgresql+psycopg://user:pass@host:5432/db"
+
+$ sqlpush diff "myapp.models:metadata"
+-- safe
+
+CREATE TABLE hero (
+    id SERIAL NOT NULL PRIMARY KEY,
+    name VARCHAR(50) NOT NULL
+);
+
+-- risky
+
+CREATE INDEX ix_hero_name ON hero (name);
+```
+
+Push it (the destructive gate is on by default):
+
+```console
+$ sqlpush push "myapp.models:metadata"
+1 destructive operation(s) blocked; re-run with --allow-destructive
+$ echo $?
+1
+
+$ sqlpush push "myapp.models:metadata" --allow-destructive
+$ echo $?
+0
+```
+
+In CI, check drift and fail loudly (see exit codes below). Limit scope with
+repeated `--schema` / `--exclude` options.
+
+## Exit codes
+
+| verb | 0 | 1 | 2 | 3 |
+| --- | --- | --- | --- | --- |
+| `diff` | always | | | |
+| `check` | clean | | drift | destructive drift |
+| `push` | applied | destructive blocked | error (incl. partial failure) | |
+
+`push --safe-only` runs only safe operations and skips the rest
+informationally (exit `0`). A failed `CREATE INDEX CONCURRENTLY` marks the
+run as partial failure (exit `2`) instead of silently half-applying.
+
+## FastAPI / SQLModel: replace `create_all`
+
+```python
+from contextlib import asynccontextmanager
+from sqlpush import aensure_schema
+
+
+@asynccontextmanager
+async def lifespan(app):
+    await aensure_schema(SQLModel.metadata, engine, mode="check")
+    yield
+```
+
+Push in the deploy pipeline, check at startup.
+
+## How it works
+
+```mermaid
+flowchart LR
+    models["SQLAlchemy MetaData"] --> diff["diff<br>alembic autogenerate, scoped"]
+    db[("live PostgreSQL")] --> diff
+    diff --> risk["risk classification<br>safe / risky / destructive"]
+    risk --> plan["plan"]
+    plan --> render["render"]
+    render --> apply["apply<br>atomic txn · CONCURRENTLY split · advisory lock"]
+    apply --> report["report"]
+```
+
+- **Diff engine** scopes reflection to your target schemas (default: the
+  session's real `search_path`) and prunes system catalogs (TimescaleDB
+  internals included) before reflection even starts.
+- **Classifier** maps each operation to a risk class; unknown operations
+  are `risky`, never silently safe.
+- **Executor** splits the plan: `CONCURRENTLY` statements run one-per-
+  transaction on autocommit, everything else applies in a single atomic
+  transaction with a bounded `lock_timeout`.
+- **Typed errors**: only `SqlpushError` / `ConnectFailed` /
+  `MetadataImportError` escape the API, never raw driver exceptions.
+
+## Comparison
+
+An honest view of the neighborhood (stars as of 2026-08):
+
+| | migration files | source of truth | risk gate | CI drift exit codes | TimescaleDB |
+| --- | --- | --- | --- | --- | --- |
+| **sqlpush** | none (the diff is the migration) | SQLAlchemy `MetaData` | classified safe/risky/destructive, destructive blocked by default | `check` 0/2/3 | `@hypertable` directives |
+| [alembic](https://github.com/sqlalchemy/alembic) (4.4k★) | yes | migration scripts (autogenerate assists) | no | no | no |
+| [atlas](https://github.com/ariga/atlas) (8.7k★) | optional (HCL) | HCL / SQL (ORMs via providers) | lint policies | yes | no |
+| [prisma `db push`](https://www.prisma.io/docs/orm/reference/prisma-cli-reference) (47k★) | none | Prisma schema (Node/TS) | no | no | no |
+| [migra](https://github.com/djrobstep/migra) (3.1k★) | diff only | SQL | n/a | partial | no (*deprecated*) |
+
+sqlpush is narrower than atlas and younger than alembic, deliberately.
+It is one tool for one job: keep a PostgreSQL schema in lockstep with
+SQLAlchemy models, safely enough to run from CI.
+
+Coming from [migra](https://github.com/djrobstep/migra) (now
+deprecated)? There is a [migration guide](docs/migrating-from-migra.md).
+
+## Design notes
+
+- `import sqlpush` stays light: the public API loads lazily, so the
+  annotations module carries none of alembic/typer/psycopg.
+- The advisory-lock key derives from the database OID: two DSN spellings
+  of the same database contend for the same lock.
+- `--json` output is a versioned contract (`"version": 1`) meant for
+  tooling; additive changes only within a version.
+
+## Roadmap (0.1.x)
+
+- `CREATE INDEX CONCURRENTLY` by default for indexes on existing tables
+- asyncpg DSN translation in `ensure_schema(AsyncEngine)`
+- jsonschema-validated `--json` output
+
+## License
+
+[MIT](LICENSE) · © 2026 Juan Miguel Contreras

sqlpush-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "sqlpush"
+version = "0.1.0"
+description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = [
+    "sqlalchemy",
+    "alembic",
+    "postgresql",
+    "timescaledb",
+    "prisma",
+    "schema",
+    "migrations",
+    "database",
+    "drift",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "alembic>=1.18,<2",
+    "psycopg[binary]>=3.2",
+    "sqlalchemy>=2.0",
+    "typer>=0.12",
+]
+
+[[project.authors]]
+name = "Juan Miguel Contreras"
+email = "19253629+juanmicl@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/juanmicl/sqlpush"
+Repository = "https://github.com/juanmicl/sqlpush"
+Issues = "https://github.com/juanmicl/sqlpush/issues"
+Changelog = "https://github.com/juanmicl/sqlpush/blob/main/CHANGELOG.md"
+
+[project.scripts]
+sqlpush = "sqlpush.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.5",
+    "ty==0.0.42",
+]
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

sqlpush-0.1.0/pyproject.toml.orig

@@ -0,0 +1,78 @@
+[project]
+name = "sqlpush"
+version = "0.1.0"
+description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
+readme = "README.md"
+authors = [
+    { name = "Juan Miguel Contreras", email = "19253629+juanmicl@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+license = "MIT"
+keywords = [
+    "sqlalchemy",
+    "alembic",
+    "postgresql",
+    "timescaledb",
+    "prisma",
+    "schema",
+    "migrations",
+    "database",
+    "drift",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "alembic>=1.18,<2",
+    "psycopg[binary]>=3.2",
+    "sqlalchemy>=2.0",
+    "typer>=0.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/juanmicl/sqlpush"
+Repository = "https://github.com/juanmicl/sqlpush"
+Issues = "https://github.com/juanmicl/sqlpush/issues"
+Changelog = "https://github.com/juanmicl/sqlpush/blob/main/CHANGELOG.md"
+
+[project.scripts]
+sqlpush = "sqlpush.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.5",
+    "ty==0.0.42",
+]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.environment]
+# match requires-python floor: the checker must never accept syntax
+# or stdlib APIs the oldest supported interpreter lacks
+python-version = "3.10"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

sqlpush-0.1.0/src/sqlpush/__init__.py

@@ -0,0 +1,78 @@
+from typing import TYPE_CHECKING, Any
+
+from sqlpush.types import (
+    AppliedOperation,
+    CheckResult,
+    ConnectFailed,
+    DestructiveBlocked,
+    MetadataImportError,
+    Plan,
+    PlannedOperation,
+    Report,
+    RiskClass,
+    SqlpushError,
+)
+
+# Static-checker visibility for the PEP 562 lazy exports below: this
+# block never executes at runtime, so the light-import guarantee is
+# untouched (tests/test_annotations.py still guards it).
+if TYPE_CHECKING:
+    from sqlpush.api import (
+        acheck,
+        aensure_schema,
+        aplan,
+        apush,
+        check,
+        ensure_schema,
+        plan,
+        push,
+    )
+
+__version__ = "0.1.0"
+
+# Public API (plan/push/check/ensure_schema + async facade) is exported
+# lazily via PEP 562: an eager import would pull alembic (through
+# sqlpush.core.diff) into every `import sqlpush.*`, breaking the
+# light-import guarantee of the annotations module (see
+# tests/test_annotations.py::test_annotations_module_has_no_heavy_imports).
+_LAZY_API = (
+    "plan",
+    "push",
+    "check",
+    "ensure_schema",
+    "aplan",
+    "apush",
+    "acheck",
+    "aensure_schema",
+)
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_API:
+        from sqlpush import api
+
+        return getattr(api, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "AppliedOperation",
+    "CheckResult",
+    "ConnectFailed",
+    "DestructiveBlocked",
+    "MetadataImportError",
+    "Plan",
+    "PlannedOperation",
+    "Report",
+    "RiskClass",
+    "SqlpushError",
+    "__version__",
+    "acheck",
+    "aensure_schema",
+    "aplan",
+    "apush",
+    "check",
+    "ensure_schema",
+    "plan",
+    "push",
+]

sqlpush-0.1.0/src/sqlpush/annotations.py

@@ -0,0 +1,37 @@
+# src/sqlpush/annotations.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+HYPERTABLE_KEY = "sqlpush_hypertable"
+
+
+@dataclass(frozen=True)
+class HypertableInfo:
+    time_column: str
+    chunk_time_interval: str | None = None
+
+
+def hypertable(*, time_column: str, chunk_time_interval: str | None = None):
+    """Record hypertable intent on the model's Table (MetaData level).
+
+    Works with SQLModel, Flask-SQLAlchemy and plain declarative, anything
+    whose class already carries a built ``__table__`` when decorated.
+
+    The generated ``create_hypertable`` runs with
+    ``create_default_indexes => false``: timescale's implicit time-column
+    index is invisible to metadata and would drift forever. Declare it
+    yourself (``Index(..., "<time_column>")`` on the model) if you rely
+    on it for time-range scans.
+    """
+
+    def decorator(cls):
+        table = getattr(cls, "__table__", None)
+        if table is None:
+            raise TypeError(f"{cls.__name__} has no __table__; decorate a mapped class")
+        table.info[HYPERTABLE_KEY] = HypertableInfo(
+            time_column=time_column, chunk_time_interval=chunk_time_interval
+        )
+        return cls
+
+    return decorator