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.6.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.6.0
File	Size	Uploaded
csrd_migration-0.6.0.tar.gz	6.7 kB	Aug 16, 2026	Details

Built distribution (wheel)

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

Total release size: 11.6 kB

Release files / csrd_migration-0.6.0.tar.gz

Download URL	csrd_migration-0.6.0.tar.gz
Size	6.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`48d57c6d4c2805cea1e8d5047277b8216f2151964c62c6035b5fd1533ccb19a5`
BLAKE2b-256 checksum How to use checksums	`39d4670af2c206f7dfe6be3d0684e7c98de6bf1c2083e8f67e2beb04c4fd39b6`
Upload date	Aug 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/1d0a8b4c008388159aee43eebd783c9c6d8c8da8

Workflow

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

Artifact

Subject: csrd_migration-0.6.0.tar.gz
SHA-256 checksum: 48d57c6d4c2805cea1e8d5047277b8216f2151964c62c6035b5fd1533ccb19a5 Verifying attestations

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

Download URL	csrd_migration-0.6.0-py3-none-any.whl
Size	4.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`26dbf68019731eb5d31a6c39405bd4b3a006004b7dfaf6d6c9103e455ac4cb0b`
BLAKE2b-256 checksum How to use checksums	`c28fb2da62a2eea8899e9017c2f3a054f2a537d0a7f649c2f2dc340dba027bc3`
Upload date	Aug 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/1d0a8b4c008388159aee43eebd783c9c6d8c8da8

Workflow

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

Artifact

Subject: csrd_migration-0.6.0-py3-none-any.whl
SHA-256 checksum: 26dbf68019731eb5d31a6c39405bd4b3a006004b7dfaf6d6c9103e455ac4cb0b Verifying attestations