csrd-migration

Versioned, idempotent schema migrations for csrd.repository database adapters.

Quick start

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
`rollback(adapter, migrations, *, to_version=None)`	Roll back applied migrations in reverse order. Pass `to_version` to stop at a specific version, or `None` to roll back all
`reapply_all(adapter, migrations)`	Roll back all then re-apply — clean schema reset without dropping the database
`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)

Metadata

Release files for csrd-migration 0.5.29

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for csrd-migration 0.5.29
File	Size	Uploaded
csrd_migration-0.5.29.tar.gz	6.7 kB	Jul 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for csrd-migration 0.5.29
File	Interpreter	ABI	Platform	Reset
csrd_migration-0.5.29-py3-none-any.whl 4.9 kB Jul 26, 2026	Python 3	none	any	Details

Total release size: 11.7 kB

Release files / csrd_migration-0.5.29.tar.gz

Download URL	csrd_migration-0.5.29.tar.gz
Size	6.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`b6378f9b5aeaf5cbda47b92c15b127a65378200b5e1e5f15e7d73f844832e636`
BLAKE2b-256 checksum How to use checksums	`60d108220748430ebbc2a829056aa13182df62dfb429f7c49c669f1ccadb9626`
Upload date	Jul 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/csrd-api/fastapi-common
Publishing commit: github.com/csrd-api/fastapi-common/tree/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322

Workflow

Publishing configuration: github.com/csrd-api/fastapi-common/blob/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322/.github/workflows/release.yml
Publishing logs: github.com/csrd-api/fastapi-common/actions/runs/30204600049/attempts/1

Artifact

Subject: csrd_migration-0.5.29.tar.gz
SHA-256 checksum: b6378f9b5aeaf5cbda47b92c15b127a65378200b5e1e5f15e7d73f844832e636 Verifying attestations

Release files / csrd_migration-0.5.29-py3-none-any.whl

Download URL	csrd_migration-0.5.29-py3-none-any.whl
Size	4.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`56c59bd9ca571886d6c6d38d322ff21ef0ce94d737ab5094d5cd8955c1892ee9`
BLAKE2b-256 checksum How to use checksums	`3af46d59810cfdad4b2b7505c5a3e655c4ab4d456f736133a6e6845ab31ea2ce`
Upload date	Jul 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/csrd-api/fastapi-common
Publishing commit: github.com/csrd-api/fastapi-common/tree/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322

Workflow

Publishing configuration: github.com/csrd-api/fastapi-common/blob/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322/.github/workflows/release.yml
Publishing logs: github.com/csrd-api/fastapi-common/actions/runs/30204600049/attempts/1

Artifact

Subject: csrd_migration-0.5.29-py3-none-any.whl
SHA-256 checksum: 56c59bd9ca571886d6c6d38d322ff21ef0ce94d737ab5094d5cd8955c1892ee9 Verifying attestations