CLI Command Workflows#
Once your config is connected, day-to-day schema changes follow the same commands whether you run alchemy ..., litestar database ..., or flask database ....
Everyday Migration Flow#
Set up migrations once in a new project, generate a migration script from your models, and apply it:
alchemy init migrations alchemy make-migrations -m "create blog tables" alchemy upgrade head
Undo the last migration or preview raw SQL without touching the database:
alchemy downgrade -1 alchemy upgrade head --sql
Note
PostgreSQL enum changes
Alembic’s autogenerate does not detect changes to PostgreSQL native ENUM types on its own (such as adding a value to an existing StrEnum). Advanced Alchemy automatically enables this detection for PostgreSQL connections when alembic-postgresql-enum is installed (included automatically with the asyncpg, psycopg, and psycopg2 extras):
uv add "advanced-alchemy[asyncpg]"
pip install "advanced-alchemy[asyncpg]"
pdm add "advanced-alchemy[asyncpg]"
poetry add "advanced-alchemy[asyncpg]"
Both AlembicCommandConfig and the generated env.py load alembic_postgresql_enum inside contextlib.suppress(ModuleNotFoundError) when the target dialect is PostgreSQL, so no manual configuration is required.
Checking Configs and Schema Drift in CI#
Run show-config to confirm which databases were found, and run check in CI to catch model changes that are missing a migration file:
alchemy show-config
alchemy check
alchemy history --indicate-current
Handling Parallel Git Branches#
When two teammates create migrations on separate branches, merge both heads into one linear revision before deploying:
alchemy heads --verbose
alchemy merge heads -m "merge feature migrations"
Adopting an Existing Database or Exporting Data#
alchemy ensure-version
alchemy stamp head
alchemy dump-data --table "*" --dir ./fixtures
alchemy drop-all --no-prompt
Warning
drop-all permanently deletes every mapped table in the target database. Only run it against disposable local or test databases.
Exporting Large Tables as Sharded Fixtures#
dump-data writes one <table>.json file per table by default. Four options change the output:
Option |
Effect |
|---|---|
|
File format. Defaults to |
|
Compression. Defaults to |
|
Starts a new shard before a file would grow past this size on disk. Accepts bytes or a number with a |
|
Starts a new shard after this many rows. Must be at least 1. |
Rows are streamed from the database in batches, so a large table never has to fit in memory. This command writes every table as gzip-compressed JSON Lines shards of at most 50 MiB each, named <table>.001.jsonl.gz, <table>.002.jsonl.gz, and so on:
alchemy dump-data --table "*" --dir ./fixtures --format jsonl --compression gzip --max-file-size 50M
Running the command again replaces every existing file for each exported table, including leftover shards from an earlier run. Load the files back with the helpers in Database Seeding.
See Command-Line Interface for every command flag.