Command-line interface¶

Model's CLI keeps database tables in sync with model definitions and can create starter models from an existing database.

model --help
model sync --help
model generate --help

You can also run it as python -m model.

model sync check¶

Checks the discovered models against their database tables without applying any changes.

model sync check

Compares each model with its table, and prints pending hooks and generated SQL. It does not run hook bodies or schema-changing SQL, so it cannot account for changes a pre_sync hook will make. It does evaluate hook run_if predicates, so keep those predicates read-only.

Check uses these exit statuses:

For a more accurate preview, use model sync apply --dry-run --print, described below.

model sync apply¶

Synchronizes each model with its database table.

model sync apply

For each model, apply runs active pre_sync hooks, recalculates and executes the schema diff, then runs active post_sync hooks.

Apply exits with 0 when every operation succeeds or there is nothing to do, 1 when one or more models fail, and 2 for invalid arguments.

Dry run¶

Runs the full sync process against a temporary, disposable database instead of the real database.

model sync apply --dry-run --print

Unlike model sync check, a dry run actually executes pre_sync and post_sync hooks and applies the generated SQL. This makes it a more accurate preview when hooks can affect the resulting schema.

The temporary dry-run environment contains a copy of the schema but no row data. MySQL dry runs also require permission to create and drop a database.

model generate¶

Generate models from existing tables.

# SQLite
model generate ./app.db ./models

# MySQL or MariaDB
model generate "mysql://app_user:password@127.0.0.1:3306/app_db" ./models

To generate one table, append --table=TABLE_NAME:

model generate ./app.db ./models --table=user

Generated files are starting points. Assign your database object and review the column types, defaults, indexes, and class names before importing them.

Each table becomes <table_name>_model.py; use --table=TABLE_NAME to select one table.

Generation exits with 0 when all selected files are written, 1 on a reflection or generation failure, and 2 for invalid arguments.