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.7.0

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.7.0
File	Size	Uploaded
csrd_migration-0.7.0.tar.gz	6.7 kB	Oct 16, 2026	Details

Built distribution (wheel)

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

Total release size: 11.7 kB

Release files / csrd_migration-0.7.0.tar.gz

Download URL	csrd_migration-0.7.0.tar.gz
Size	6.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`85ef9c11aa72978bbe4cd243fc61224de3d394964d9a2c9c2efa13510df03d18`
BLAKE2b-256 checksum How to use checksums	`a759b1c858163ee40cfe52afb277a20d16070a41d16e39123204bea192c7ba6f`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/d6d759c818d70dd038c8905a88a297258ec1b5ac

Workflow

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

Artifact

Subject: csrd_migration-0.7.0.tar.gz
SHA-256 checksum: 85ef9c11aa72978bbe4cd243fc61224de3d394964d9a2c9c2efa13510df03d18 Verifying attestations

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

Download URL	csrd_migration-0.7.0-py3-none-any.whl
Size	4.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`40c0909885bbccc1ee888ce91283f1b19467ed714e577533d0a5814b040ab28a`
BLAKE2b-256 checksum How to use checksums	`9e2efc6da5a81eee98893ee15303ac844c05b23224e8fb59c6735307fe1d7da6`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/d6d759c818d70dd038c8905a88a297258ec1b5ac

Workflow

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

Artifact

Subject: csrd_migration-0.7.0-py3-none-any.whl
SHA-256 checksum: 40c0909885bbccc1ee888ce91283f1b19467ed714e577533d0a5814b040ab28a Verifying attestations