Skip to content

CLI Commands

Saffier ships with a CLI for migrations, shell usage, and schema inspection.

This page summarizes the command surface and typical flows.

Before Running Commands

Most commands need an application context.

Provide it via:

  • --app path.to.module
  • SAFFIER_DEFAULT_APP=path.to.module
  • preloads in Settings

The legacy path.to.module:app form still works for older projects, but current Saffier prefers module-based discovery where the module sets saffier.monkay.instance.

See Discovery for details.

If you want centralized command behavior such as preload imports, migration directory defaults, custom Alembic context arguments, or shell defaults, configure them in Settings.

Command Families

Goal Typical Commands
Setup migration repository list-templates, init
Generate revision files revision, makemigrations, merge, edit
Apply or revert revisions migrate, downgrade, stamp
Inspect migration state current, heads, branches, history, show, check
Runtime utilities shell, inspectdb, admin_serve

Migration Bootstrap

saffier list-templates

Show available migration templates.

$ saffier list-templates

Built-in templates:

  • default
  • plain
  • url
  • sequencial

saffier init

Create migration repository files.

$ saffier init
$ saffier init -d db/migrations
$ saffier init -t plain
$ saffier init -t url
$ saffier init -t sequencial

init does not require an application object. When -d/--directory is not passed, it uses settings.migration_directory.

Migration Generation

saffier revision

Create a new revision script.

$ saffier revision -m "Add status column"
$ saffier revision --autogenerate -m "Sync models"

saffier makemigrations

Alias for saffier revision --autogenerate.

$ saffier makemigrations
$ saffier makemigrations -m "Initial schema"

saffier merge

Merge multiple heads.

$ saffier merge -m "Merge heads" <rev_a> <rev_b>

saffier edit

Edit a revision from the CLI.

$ saffier edit head

Migration Execution

saffier migrate

Upgrade to head (or a specific revision).

$ saffier migrate
$ saffier migrate <revision>

saffier downgrade

Rollback to an older revision.

$ saffier downgrade -1
$ saffier downgrade <revision>

saffier stamp

Set the revision marker without applying migrations.

$ saffier stamp head

Migration Introspection

$ saffier current
$ saffier heads
$ saffier branches
$ saffier history
$ saffier show head
$ saffier check

Runtime Utilities

saffier shell

Start an interactive shell.

$ saffier shell
$ saffier shell --kernel ptpython

saffier inspectdb

Reflect an existing database into models.

$ saffier inspectdb --database "postgres+asyncpg://user:pass@localhost:5432/my_db"

saffier admin_serve

Run the Saffier admin ASGI app.

$ saffier admin_serve --admin-path /admin
$ saffier admin_serve --host 0.0.0.0 --port 9000 --create-all

To enable the optional admin dependencies:

$ pip install "saffier[admin]"
  1. saffier init (once)
  2. saffier makemigrations
  3. saffier migrate
  4. Repeat 2-3 as models evolve

Real-World Workflow

With preload-based discovery in settings:

myproject/configs/settings.py
from saffier.conf.global_settings import SaffierSettings


class Settings(SaffierSettings):
    preloads = ("myproject.main",)
    migration_directory = "db/migrations"

Typical commands become:

$ saffier init
$ saffier makemigrations -m "Add invoices table"
$ saffier migrate
$ saffier shell

See Also