db:rollback

Table of contents

1. Introduction
2. Rolling back more than one step
3. Rolling back the dependents without asking
4. Starting a feature’s migrations over
5. Cleaning up an orphan
6. Advanced
7. Reference
   1. Options
   2. Errors
8. Requirements

---

Introduction

db:rollback undoes a feature’s migrations, the last one by default. The features that depend on it roll back first, so no foreign key is left pointing at a dropped table.

splent db:rollback splent_feature_notes

  ⚠️  These features depend on splent_feature_notes and have applied migrations:
     • splent_feature_reports
     • splent_feature_notes_tags

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

A feature can be named notes, splent_feature_notes, splent_feature_notes@v1.2.0 or splent-io/splent_feature_notes@v1.2.0.

---

Rolling back more than one step

splent db:rollback splent_feature_notes --steps 3
splent db:rollback splent_feature_notes --to-base

--steps and --to-base apply to the feature and to each dependent rolled back with it. --to-base undoes every migration. Giving both is an error.

---

Rolling back the dependents without asking

splent db:rollback splent_feature_notes --cascade

A dependent is a feature whose UVL constraint names the target (reports => notes), or a refiner of the target. A dependent of a dependent does not count. Only those with applied migrations are rolled back, the refiners first, then the UVL dependents in reverse constraint order, then the target.

---

Starting a feature’s migrations over

When a feature reaches base it moves back to installed, and the command offers to delete its migration files. Then db:migrate can write them again from scratch.

  ⬇️  Rolling back splent_feature_notes_tags to base...
  ✅ splent_feature_notes_tags → base
  ⚠️  Deleting migration files is IRREVERSIBLE — the files cannot be recovered and the feature will need new migrations to be re-applied.
  Permanently delete 1 migration file(s)? (irreversible) [y/N]: y
  deleted: 1 file(s)

Say no and the files stay, so db:upgrade applies them again. A pinned feature’s files belong to the shared cache, so they are never offered. Run feature:unlock to edit them.

---

Cleaning up an orphan

splent db:rollback splent_feature_memos

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

An orphan is a feature that left pyproject.toml and still has a splent_migrations row, shown as orphan in db:status. Its tables stay, so drop them by hand from db:console.

---

Advanced

There is no transaction across features. If a dependent fails, the target is left alone and the output lists the dependents already rolled back, with the splent db:upgrade lines that restore them. If the target fails after its dependents, the product is in a mixed state. Fix the error and run db:rollback again, or restore the dependents.

---

Reference

Options

Option	Default	Description
FEATURE		The feature to roll back
--steps N	1	How many migrations to roll back
--to-base	off	Roll back every migration. Use instead of --steps
--cascade	off	Roll back the dependents without asking

Errors

Message	What to do
❌ Feature '<feature>' is not declared in this product.	Check the name. It must match a declared feature exactly
ℹ️ Feature '<feature>' has no migrations ...	Nothing to roll back. It exits 0
Error: Use either --steps or --to-base, not both.	Pick one
❎ Cancelled.	You declined. It exits 1 and changes nothing

---

Requirements

• A selected product (SPLENT_APP), and a reachable database.
• The product is not deployed to production (SPLENT_ENV=prod), since the CLI would then reach the production database. Go back with splent product:down --prod and splent product:up --dev. See the CLI while production is deployed.