csrd-migration 0.3.89__py3-none-any.whl

csrd/migration/__init__.py

@@ -0,0 +1,11 @@
+"""Versioned schema migrations for csrd database adapters.
+
+Public API::
+
+    from csrd.migration import Migration, MigrationRunner
+"""
+
+from ._migration import Migration
+from ._runner import MigrationRunner
+
+__all__ = ("Migration", "MigrationRunner")

csrd/migration/_migration.py

@@ -0,0 +1,29 @@
+"""Frozen dataclass representing a single versioned schema change."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Migration:
+    """A single versioned database schema change.
+
+    Migrations are applied in list order by :class:`MigrationRunner`.
+    Each migration must have a unique ``version`` string.
+
+    Parameters
+    ----------
+    version
+        Unique version identifier (e.g. ``"001"``, ``"002"``).
+        Compared lexicographically — use zero-padded numbers.
+    description
+        Human-readable description of the change.
+    up
+        SQL statement(s) to apply the migration.
+    down
+        SQL statement(s) to revert the migration.
+    """
+
+    version: str
+    description: str
+    up: str
+    down: str

csrd/migration/_runner.py

@@ -0,0 +1,98 @@
+"""Migration runner — applies and tracks schema migrations."""
+
+from csrd.repository import ABCDatabaseAdapter
+
+from ._migration import Migration
+
+_MIGRATIONS_TABLE = "_csrd_migrations"
+
+_CREATE_TABLE_SQL = f"""
+CREATE TABLE IF NOT EXISTS {_MIGRATIONS_TABLE} (
+    version  TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+)
+"""
+
+# Postgres/MariaDB variant — uses CURRENT_TIMESTAMP instead of datetime('now')
+_CREATE_TABLE_SQL_STANDARD = f"""
+CREATE TABLE IF NOT EXISTS {_MIGRATIONS_TABLE} (
+    version  VARCHAR(255) PRIMARY KEY,
+    description VARCHAR(1024) NOT NULL,
+    applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+
+class MigrationRunner:
+    """Apply and track versioned schema migrations.
+
+    The runner creates a ``_csrd_migrations`` tracking table automatically.
+    Already-applied migrations are skipped (idempotent).
+
+    Usage::
+
+        runner = MigrationRunner()
+        await runner.apply_all(adapter, migrations)
+    """
+
+    async def _ensure_table(self, adapter: ABCDatabaseAdapter) -> None:
+        """Create the migrations tracking table if it doesn't exist."""
+        # Try SQLite-style first; fall back to standard SQL on failure
+        try:
+            await adapter.execute(_CREATE_TABLE_SQL)
+        except Exception:
+            await adapter.execute(_CREATE_TABLE_SQL_STANDARD)
+
+    async def _applied_versions(self, adapter: ABCDatabaseAdapter) -> set[str]:
+        """Return the set of already-applied migration versions."""
+        rows = await adapter.fetch_all(f"SELECT version FROM {_MIGRATIONS_TABLE}")
+        return {row["version"] for row in rows}
+
+    async def apply_all(
+        self,
+        adapter: ABCDatabaseAdapter,
+        migrations: list[Migration],
+    ) -> list[Migration]:
+        """Apply all pending migrations in list order.
+
+        Returns the list of migrations that were actually applied
+        (empty if everything was already up-to-date).
+        """
+        await self._ensure_table(adapter)
+        applied = await self._applied_versions(adapter)
+
+        newly_applied: list[Migration] = []
+        for migration in migrations:
+            if migration.version in applied:
+                continue
+            await adapter.execute(migration.up)
+            await adapter.execute(
+                f"INSERT INTO {_MIGRATIONS_TABLE} (version, description) "
+                "VALUES (:version, :description)",
+                {"version": migration.version, "description": migration.description},
+            )
+            newly_applied.append(migration)
+
+        return newly_applied
+
+    async def current_version(
+        self,
+        adapter: ABCDatabaseAdapter,
+    ) -> str | None:
+        """Return the latest applied migration version, or ``None``."""
+        await self._ensure_table(adapter)
+        row = await adapter.fetch_one(
+            f"SELECT version FROM {_MIGRATIONS_TABLE} ORDER BY version DESC LIMIT 1"
+        )
+        return row["version"] if row else None
+
+    async def pending(
+        self,
+        adapter: ABCDatabaseAdapter,
+        migrations: list[Migration],
+    ) -> list[Migration]:
+        """Return migrations not yet applied, preserving list order."""
+        await self._ensure_table(adapter)
+        applied = await self._applied_versions(adapter)
+        return [m for m in migrations if m.version not in applied]

csrd_migration-0.3.89.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: csrd-migration
+Version: 0.3.89
+Summary: Versioned schema migrations for csrd database adapters
+Project-URL: Repository, https://github.com/csrd-api/fastapi-common
+Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/migration
+Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: csrd-repository
+Description-Content-Type: text/markdown
+
+# csrd-migration
+
+Versioned, idempotent schema migrations for `csrd.repository` database adapters.
+
+## Quick start
+
+```python
+from csrd.migration import Migration, MigrationRunner
+from csrd.repository import SQLiteAdapter
+
+MIGRATIONS = [
+    Migration(
+        version="001",
+        description="create users table",
+        up="CREATE TABLE users (id INTEGER PRIMARY KEY, username TEXT NOT NULL)",
+        down="DROP TABLE users",
+    ),
+]
+
+async def setup_db():
+    adapter = SQLiteAdapter("app.db")
+    await adapter.connect()
+    runner = MigrationRunner()
+    await runner.apply_all(adapter, MIGRATIONS)
+```
+
+## API
+
+### `Migration`
+
+Frozen dataclass representing a single schema change.
+
+| Field | Type | Description |
+|---|---|---|
+| `version` | `str` | Unique version identifier (e.g. `"001"`, `"002"`) |
+| `description` | `str` | Human-readable description |
+| `up` | `str` | SQL to apply the migration |
+| `down` | `str` | SQL to revert the migration |
+
+### `MigrationRunner`
+
+Applies and tracks migrations against any `ABCDatabaseAdapter`.
+
+| Method | Description |
+|---|---|
+| `apply_all(adapter, migrations)` | Apply all pending migrations in order |
+| `current_version(adapter)` | Return the latest applied version, or `None` |
+| `pending(adapter, migrations)` | Return migrations not yet applied |
+
+The runner creates a `_csrd_migrations` table automatically to track
+applied versions. Re-running is idempotent — already-applied migrations
+are skipped.
+
+## Design
+
+- **Adapter-agnostic** — works with `SQLiteAdapter`, `PGAdapter`, `MariaAdapter`
+- **Idempotent** — safe to call on every startup
+- **Ordered** — migrations are applied in list order
+- **Future-ready** — the `Migration` dataclass is the stable interface for
+  a future model→SQL translation layer (see `docs/AUGMENT_PLAN.md`)

csrd_migration-0.3.89.dist-info/RECORD

@@ -0,0 +1,7 @@
+csrd/migration/__init__.py,sha256=vVcEZPkwOf8DLCC-aCrZ61r3hKTg54F4anCasqhHR1A,252
+csrd/migration/_migration.py,sha256=eW6XTH0qY25KaBD0od5NtaIJDpEWVCWmwqBSaUzktt8,751
+csrd/migration/_runner.py,sha256=nEQKntr7yhbRVAWhLWDQrXMPYrH4vVM3nkpy_m0ni6I,3401
+csrd/migration/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+csrd_migration-0.3.89.dist-info/METADATA,sha256=skttyCbqPxHwEhgkb2JW9ekxT2CT0fSweeIlQ5aL8rM,2309
+csrd_migration-0.3.89.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+csrd_migration-0.3.89.dist-info/RECORD,,

csrd_migration-0.3.89.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any