db:status

Introduction

db:status shows, for each feature, the revision applied in the database next to the latest revision of its migration files. Run it to see what db:upgrade would apply.

splent db:status

📊 Migration Status

  Feature                      Applied         Latest          Status
  ---------------------------  --------------  --------------  ------------
  splent_feature_landing       —               —               — none
  splent_feature_notes         990210b54b52    990210b54b52    ✔ synced
  splent_feature_reports       126da35a357f    126da35a357f    ✔ synced
  splent_feature_memos         2dbb28857263    —               ⚠ orphan

  1 orphan(s) in DB no longer declared: splent_feature_memos
  Run 'splent db:rollback <feature>' to clean up, or ignore if tables should be kept.

It lists every feature with a migrations/ folder and every feature the database still tracks in splent_migrations.

Reading the status

Status	Meaning	What to do
synced	The applied revision is the latest file’s	Nothing
pending	Some files are not applied yet	`splent db:upgrade`
not applied	The feature has migration files and none is applied	`splent db:upgrade`
no files	Declared and applied, with no migration files on disk	Bring the scripts back, since `db:upgrade` and `db:rollback` need them
orphan	Applied, but the feature left `pyproject.toml`	`db:rollback <feature>` offers to remove its entry
none	No migrations, applied or on disk	Nothing

Pending, not applied and no files are counted in the closing N feature(s) out of sync line. Orphans are not, since db:upgrade cannot fix them.

Failing when the schema is behind

splent db:status --check

With --check it exits 1 when a feature is out of sync. The product’s start runs it when SPLENT_MIGRATE_ON_START=check, so a web container never serves on a schema older than its code. See Migrating when the product starts.

Advanced

The latest revision comes from the revision and down_revision lines of each script, typed (revision: str = ...) and merge (down_revision = ('a', 'b')) forms included. A feature with two heads is synced when the database is at either of them.

Reference

Option	Description
`--check`	Exit 1 when a feature is pending, not applied or with no files

Message	What to do
`❌ Could not read splent_migrations: ...`	The app creates that table when it starts. Check the database is reachable and run it again
`Error: Cannot read the features of <product>/pyproject.toml: <reason>`	Fix the TOML, or the feature list it names

Requirements

A selected product (SPLENT_APP), and a reachable database.