chancy.migrate module

Utilities for performing database migrations in a PostgreSQL database.

The functionality in this module is standalone and can be used with any PostgreSQL database without any dependencies on the rest of the Chancy project.

class chancy.migrate.Migration

Bases: ABC

A migration is a single unit of work that is applied to the database to bring it from one schema version to another.

abstract async down(migrator: Migrator, cursor: AsyncCursor)

abstract async up(migrator: Migrator, cursor: AsyncCursor)

exception chancy.migrate.MigrationError

Bases: Exception

An error occurred while migrating the database schema.

class chancy.migrate.Migrator(key: str, migrations_package: str, *, prefix: str = '')

Bases: object

A migrator is responsible for managing the database schema version and applying migrations to the database.

Parameters:

• key – A unique identifier for the application.

• migrations_package – The package where migrations are stored.

• prefix – A prefix to apply to all tables.

discover_all_migrations() → list[Migration]

Discovers all available migrations in the migrations package.

Migrations are discovered by looking for classes that inherit from the Migration class.

Migrations are sorted by their version number, which is the number at the beginning of the migration filename, ignoring the v prefix.

For example, a migration file named v1.py would have a version number of 1.

async get_current_version(cursor: AsyncCursor) → int

Get the current schema version from the database.

async is_migration_required(cursor: AsyncCursor) → bool

Check if a newer schema version is available.

async migrate(conn: AsyncConnection, to_version: int | None = None) → bool

Migrate the database schema to the given version.

This will migrate the database schema up or down as necessary to reach the given version. If to_version is less than the current schema version, the database will be migrated down. If to_version is greater than the current schema version, the database will be migrated up.

If to_version is not provided, the database will be migrated to the highest available version.

async set_current_version(cursor: AsyncCursor, version: int)

Set the current schema version in the database.

Note

This does not perform any sanity checks nor does it run any migrations. It simply sets the version in the database.

async upsert_version_table(cursor: AsyncCursor)

Create the schema_version table if it doesn’t exist.