csrd-migration 0.3.89__tar.gz

csrd_migration-0.3.89/.gitignore

@@ -0,0 +1,217 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+/env/
+/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+*.db
+
+
+# Import linter cache
+.import_linter_cache/
+
+# IDE
+.idea/
+.idea/*

csrd_migration-0.3.89/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,60 @@
+# 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/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "csrd-migration"
+version = "0.3.89"
+description = "Versioned schema migrations for csrd database adapters"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "csrd-repository",
+]
+readme = "README.md"
+
+[tool.uv.sources]
+csrd-repository = { workspace = true }
+
+[project.urls]
+Repository = "https://github.com/csrd-api/fastapi-common"
+Documentation = "https://github.com/csrd-api/fastapi-common/tree/main/packages/migration"
+Changelog = "https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/csrd"]

csrd_migration-0.3.89/src/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-0.3.89/src/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-0.3.89/src/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/tests/test_migration.py

@@ -0,0 +1,156 @@
+"""Tests for csrd.migration — Migration dataclass and MigrationRunner."""
+
+import pytest
+
+from csrd.migration import Migration, MigrationRunner
+from csrd.repository import SQLiteAdapter
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+async def adapter(tmp_path):
+    """Provide a connected SQLiteAdapter backed by a temp file."""
+    db_path = str(tmp_path / "test.db")
+    adapter = SQLiteAdapter(db_path)
+    await adapter.connect()
+    yield adapter
+    await adapter.close()
+
+
+MIGRATIONS = [
+    Migration(
+        version="001",
+        description="create users table",
+        up="CREATE TABLE users (id INTEGER PRIMARY KEY, username TEXT NOT NULL)",
+        down="DROP TABLE users",
+    ),
+    Migration(
+        version="002",
+        description="add email column",
+        up="ALTER TABLE users ADD COLUMN email TEXT",
+        down=(
+            "CREATE TABLE users_backup (id INTEGER PRIMARY KEY, username TEXT NOT NULL);"
+            "INSERT INTO users_backup SELECT id, username FROM users;"
+            "DROP TABLE users;"
+            "ALTER TABLE users_backup RENAME TO users;"
+        ),
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Migration dataclass
+# ---------------------------------------------------------------------------
+
+
+class TestMigration:
+    def test_frozen(self):
+        m = Migration(version="001", description="test", up="SELECT 1", down="SELECT 1")
+        with pytest.raises(AttributeError):
+            m.version = "002"  # type: ignore[misc]
+
+    def test_fields(self):
+        m = Migration(version="001", description="test", up="UP", down="DOWN")
+        assert m.version == "001"
+        assert m.description == "test"
+        assert m.up == "UP"
+        assert m.down == "DOWN"
+
+
+# ---------------------------------------------------------------------------
+# MigrationRunner
+# ---------------------------------------------------------------------------
+
+
+class TestMigrationRunner:
+    async def test_apply_all_creates_table_and_applies(self, adapter):
+        runner = MigrationRunner()
+        applied = await runner.apply_all(adapter, MIGRATIONS)
+
+        assert len(applied) == 2
+        assert applied[0].version == "001"
+        assert applied[1].version == "002"
+
+        # Verify the users table was actually created with both columns
+        row = await adapter.fetch_one(
+            "SELECT sql FROM sqlite_master WHERE type='table' AND name='users'"
+        )
+        assert row is not None
+        assert "email" in row["sql"]
+
+    async def test_apply_all_is_idempotent(self, adapter):
+        runner = MigrationRunner()
+        first = await runner.apply_all(adapter, MIGRATIONS)
+        second = await runner.apply_all(adapter, MIGRATIONS)
+
+        assert len(first) == 2
+        assert len(second) == 0  # nothing new to apply
+
+    async def test_apply_all_incremental(self, adapter):
+        runner = MigrationRunner()
+
+        # Apply only first migration
+        applied1 = await runner.apply_all(adapter, MIGRATIONS[:1])
+        assert len(applied1) == 1
+
+        # Now apply both — only second should be new
+        applied2 = await runner.apply_all(adapter, MIGRATIONS)
+        assert len(applied2) == 1
+        assert applied2[0].version == "002"
+
+    async def test_current_version_empty(self, adapter):
+        runner = MigrationRunner()
+        version = await runner.current_version(adapter)
+        assert version is None
+
+    async def test_current_version_after_apply(self, adapter):
+        runner = MigrationRunner()
+        await runner.apply_all(adapter, MIGRATIONS)
+        version = await runner.current_version(adapter)
+        assert version == "002"
+
+    async def test_current_version_partial(self, adapter):
+        runner = MigrationRunner()
+        await runner.apply_all(adapter, MIGRATIONS[:1])
+        version = await runner.current_version(adapter)
+        assert version == "001"
+
+    async def test_pending_all(self, adapter):
+        runner = MigrationRunner()
+        pending = await runner.pending(adapter, MIGRATIONS)
+        assert len(pending) == 2
+
+    async def test_pending_after_apply(self, adapter):
+        runner = MigrationRunner()
+        await runner.apply_all(adapter, MIGRATIONS[:1])
+        pending = await runner.pending(adapter, MIGRATIONS)
+        assert len(pending) == 1
+        assert pending[0].version == "002"
+
+    async def test_pending_none(self, adapter):
+        runner = MigrationRunner()
+        await runner.apply_all(adapter, MIGRATIONS)
+        pending = await runner.pending(adapter, MIGRATIONS)
+        assert len(pending) == 0
+
+    async def test_tracking_table_records(self, adapter):
+        runner = MigrationRunner()
+        await runner.apply_all(adapter, MIGRATIONS)
+
+        rows = await adapter.fetch_all(
+            "SELECT version, description FROM _csrd_migrations ORDER BY version"
+        )
+        assert len(rows) == 2
+        assert rows[0]["version"] == "001"
+        assert rows[0]["description"] == "create users table"
+        assert rows[1]["version"] == "002"
+        assert rows[1]["description"] == "add email column"
+
+    async def test_empty_migration_list(self, adapter):
+        runner = MigrationRunner()
+        applied = await runner.apply_all(adapter, [])
+        assert applied == []
+        assert await runner.current_version(adapter) is None