db:rollback

Roll back migrations for a specific feature, respecting UVL dependencies.

Usage

splent db:rollback <feature_name> [--steps N] [--cascade]

Examples

Roll back the last migration:

splent db:rollback splent_feature_notes

Roll back with cascade (also rolls back dependent features):

splent db:rollback splent_feature_auth --cascade

Options

Option	Default	Description
`--steps N`	`1`	Number of migrations to roll back
`--cascade`	off	Also rollback dependent features without asking

Dependency awareness

Before rolling back, the command checks the UVL constraints for features that depend on the target feature and have applied migrations:

$ splent db:rollback splent_feature_auth

  ⚠️  These features depend on splent_feature_auth and have applied migrations:
     • splent_feature_notes
     • splent_feature_profile

  Roll back dependents first, then this feature? [y/N]:

If you confirm, it rolls back the dependents in reverse UVL order first, then the target feature. This prevents FK constraint violations (e.g., dropping user table while note table still has a FK to it).

Orphan cleanup

If the feature is no longer declared in pyproject.toml but still has an entry in splent_migrations (shown as ⚠ orphan in db:status), the command detects this and offers to remove the stale database entry:

$ splent db:rollback splent_feature_notes

  ⚠️  Feature 'splent_feature_notes' is not declared but has a DB entry (orphan).
  Remove the orphan entry from splent_migrations? [y/N]: y
  ✅ Removed 'splent_feature_notes' from splent_migrations.

This only removes the tracking entry – it does not drop tables. To remove the actual tables, use splent db:console and run DROP TABLE manually.

Migration file cleanup

When a rollback reaches base (all migrations undone), the command asks whether to delete the migration files:

  splent_feature_notes_tags -> base
  Delete 1 migration file(s)? [y/N]: y
  deleted: 1 file(s)

This is useful when you want to regenerate migrations from scratch with db:migrate. If you decline, the files stay and can be re-applied with db:upgrade.

Safety checks

Feature not declared (no DB entry): If the feature is not in pyproject.toml and has no DB entry, the command exits with a clear error.
Feature not declared (orphan): If the feature has a DB entry but is not declared, the command offers to clean up the orphan entry.
No migrations: If the feature has no migrations/ directory, the command shows a warning and exits cleanly (no crash).
Lifecycle state: After rollback, the feature state regresses to installed (if fully rolled back) or stays at migrated (if partial).

Requirements

SPLENT_APP must be set.
The database must be reachable.