Ushka

API reference

ushka.cli.commands.db

This module provides the Command Line Interface (CLI) commands for database migration management using Alembic.

It integrates Ushka's configuration for database URL and model discovery, and customizes the Alembic env.py template to provide auto-batch mode for SQLite and automatic model discovery.

Commands

_get_alembic_config: Configures Alembic based on Ushka settings. init: Initializes the Alembic migration environment. make: Generates a new migration script. migrate: Applies pending migrations to the database. revert: Reverts database migrations. status: Shows the current database revision. history: Shows the full migration history.

def init()

Initializes the Alembic migration environment and injects Ushka's custom env.py.

This command creates the migrations directory and an initial alembic.ini file if they don't exist. It then overwrites the default env.py with Ushka's optimized template, which provides:

  • Automatic loading of Ushka's database configuration.
  • Auto-discovery of user models for alembic autogenerate.
  • Automatic enabling of "batch mode" for SQLite migrations.

See Also

USHKA_ENV_TEMPLATE : The custom template injected into env.py.

def make(message: Optional[str] = None)

Generates a new migration script based on model changes.

If no message is provided, an auto-generated timestamped message is used. This command leverages Alembic's autogenerate feature to detect differences between the current database state (or db.metadata) and the defined SQLAlchemy models.

Parameters

messagestr

A short description of the migration. If None, a message like "auto_YYYYMMDD_HHMMSS" will be generated.

def migrate()

Applies all pending migrations to the database.

This command upgrades the database schema to the latest revision, applying any migration scripts that have not yet been run.

def revert(revision: str = '-1')

Reverts database migrations to a specified revision.

Defaults to undoing the last step (downgrading by one revision).

Parameters

revisionstr

The target revision to downgrade to. Common values include:

  • "-1": Downgrade one step (default).
  • "base": Downgrade all migrations to the initial state.
  • A specific revision ID (e.g., "abcdef123456").

def status()

Shows the current database revision.

This command reports the revision identifier of the latest migration applied to the database.

def history()

Shows the full migration history.

This command lists all available migration scripts, including their revision identifiers, timestamps, and messages.