plain.postgres 0.117.0__tar.gz → 0.118.0__tar.gz

{plain_postgres-0.117.0 → plain_postgres-0.118.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plain.postgres
-Version: 0.117.0
+Version: 0.118.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -144,7 +144,7 @@ PLAIN_POSTGRES_MANAGEMENT_URL=postgresql://app@postgres:5432/myapp
 
 When `POSTGRES_MANAGEMENT_URL` is set, these commands connect through it instead of `POSTGRES_URL`:
 
-- `plain migrations create`, `plain migrations apply`, `plain migrations list`, `plain migrations prune`, `plain migrations squash`
+- `plain migrations create`, `plain migrations apply`, `plain migrations list`, `plain migrations prune`
 - `plain postgres sync`, `plain postgres converge`, `plain postgres schema`
 - `plain postgres diagnose`, `plain postgres drop-unknown-tables`, `plain postgres shell`
 
@@ -603,15 +603,16 @@ Key flags:
 
 Shared commands (apply equally to structural and data migrations):
 
-| Command                                     | Purpose                                              |
-| ------------------------------------------- | ---------------------------------------------------- |
-| `plain migrations apply`                    | Apply pending migrations                             |
-| `plain migrations apply --plan`             | Preview what would run                               |
-| `plain migrations apply --check`            | Exit non-zero if unapplied migrations exist (for CI) |
-| `plain migrations apply --fake`             | Mark as applied without running SQL                  |
-| `plain migrations list`                     | View migration status by package                     |
-| `plain migrations squash <pkg> <migration>` | Squash migrations into one                           |
-| `plain migrations prune`                    | Remove stale migration records                       |
+| Command                            | Purpose                                                           |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `plain migrations apply`           | Apply pending migrations                                          |
+| `plain migrations apply --plan`    | Preview what would run                                            |
+| `plain migrations apply --check`   | Exit non-zero if unapplied migrations exist (for CI)              |
+| `plain migrations apply --fake`    | Mark as applied without running SQL                               |
+| `plain migrations list`            | View migration status by package                                  |
+| `plain migrations prune`           | Remove orphan migration records                                   |
+| `plain migrations prune <package>` | Remove every record for one package (lets its baseline run again) |
+| `plain migrations reset <package>` | Replace the package's history with one baseline                   |
 
 #### Development workflow
 
@@ -626,43 +627,65 @@ Use this when migrations exist only in your local dev environment and haven't be
 3. `plain migrations create` — creates a single fresh migration with all the changes
 4. `plain migrations apply --fake` — marks the new migration as applied (the schema is already correct from the old migrations)
 
-**Consolidating committed migrations (squash):**
+Migrations that are committed but not yet deployed anywhere can be consolidated the same way if every developer resets their database; production then applies the consolidated migration normally. Once a migration has reached any deployed environment, use a full reset (below).
 
-Use this when migrations have already been committed or deployed to other environments.
+#### Baselines
 
-`plain migrations squash <package> <migration>` creates a replacement migration with a `replaces` list. Keep the original files until all environments have migrated past the squash point, then delete them and run `migrations prune`.
+A package whose migration history has been reset ships one **baseline** migration in place of the deleted files. It is an ordinary migration with three extra attributes:
 
-**Which method to use:**
-
-| Scenario                                  | Method                                                  |
-| ----------------------------------------- | ------------------------------------------------------- |
-| Migrations are local only (not committed) | Delete-and-recreate                                     |
-| Migrations are committed but not deployed | Delete-and-recreate (if all developers reset) or squash |
-| Migrations are deployed to production     | Squash or full reset                                    |
+```python
+class Migration(migrations.Migration):
+    supersedes = "0008_add_widgets"  # the sentinel: the last deleted migration; its record proves a database is caught up
+    retired = (
+        "0001_initial",
+        ...,
+        "0008_add_widgets",
+    )  # every deleted name, so dependencies on them still resolve
+    shipped_in = "0.61"  # the release that shipped the reset; empty until it has
+    dependencies = (("users", "0001_initial"),)
+    operations = (migrations.CreateModel(...), ...)
+```
+
+What `plain postgres sync` (or `plain migrations apply`) does with it depends only on what the database has recorded:
+
+| Database has                                                      | Result                                                                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| No records for the package, no tables (fresh, or newly installed) | Runs the baseline like any migration                                                                   |
+| No records for the package, but its tables exist                  | Refuses: record it with `apply <pkg> <baseline> --fake` if the schema is current, else drop the tables |
+| The baseline recorded                                             | Nothing                                                                                                |
+| The `supersedes` migration recorded                               | Records the baseline without running it - one row, once                                                |
+| Records, but not the `supersedes` migration                       | Refuses: upgrade through the last release that still has that migration                                |
+| Records, but none of the package's tables                         | Refuses: `plain migrations prune <pkg>` drops the records; then it runs                                |
+
+`plain migrations apply --plan --check` and `plain postgres sync --check` report a baseline waiting to be recorded as a pending change, and `plain preflight` reports a refusal as an error. Nothing ever deletes records on its own; `prune` stays explicit. A database where the baseline _ran_ (rather than was recorded) cannot roll back to code from before the reset.
 
 #### Resetting migrations
 
-Over time a package can accumulate dozens of migrations. Once **every environment** (dev, staging, production) has applied all of them, you can replace the entire history with a single fresh `0001_initial`.
+Once **every environment** has applied a package's migrations, its history can be collapsed into one baseline:
 
-**Prerequisites:**
+```bash
+plain migrations reset <package>
+```
 
-- Every environment (dev, staging, production) has applied all existing migrations. If any environment is behind, the reset will break it.
-- The first migration is named `0001_initial` (the default). If it has a different name, this workflow won't work cleanly.
+The command writes `NNNN_baseline.py` past the current leaf (the package's newest migration) — the package's schema as `CreateModel`s, `supersedes` set to the leaf, `retired` set to every deleted name — and deletes the old files. Commit the new file and the deletions together. Existing databases adopt it with one record on their next `plain postgres sync`; the retired records stay as the rollback path; a fresh database runs it. Other packages' migrations that depended on a deleted name resolve to the baseline; nothing there needs rewriting. Do not add a `prune` step. Before it touches anything it checks, in this order:
 
-**Steps:**
+- The models agree with the history (`plain migrations create` would write nothing). A change the history doesn't hold would be folded into the baseline, and databases that adopt it would never run it.
+- The package ends in a single leaf, and no earlier baseline is waiting unreleased (see second resets below).
+- The deleted history holds nothing a fresh database would miss. `RunPython`, `RunSQL`, any custom operation, and anything on the database side of `SeparateDatabaseAndState` are listed and refused until each carries `skip_on_reset=True` — "a fresh database can do without this." If it can't (a seed, an extension), move the effect somewhere a fresh database does get it, then mark it.
+- The migrations directory is committed — tracked, unmodified, inside a git repository (so an installed package in site-packages cannot be reset; the check applies to `--dry-run` too). The leaf becomes the baseline's sentinel, so it cannot be something you created a minute ago. No check can prove every environment applied it — the command prints that obligation, and a database that hasn't is refused until it does. If anything goes wrong the output has already printed the one line that puts it back: `git checkout -- <migrations dir> && rm <the new baseline>`.
+- The result loads: dependencies on retired names resolve, the graph has no cycle, the baseline reproduces the models exactly.
+- Nothing the baseline needs is defined inside a migration file. A custom field class or callable written in the history disappears with it; move it into the app first.
 
-1. Run `plain migrations list` locally and verify everything is applied.
-2. Delete every file in the package's `migrations/` directory except `__init__.py`.
-3. Run `plain migrations create` to generate a fresh `0001_initial`.
-4. Run `plain migrations prune --yes` to remove stale DB records. The existing `0001_initial` record matches the new file, so the database is immediately up to date.
-5. Verify with `plain postgres schema` (zero issues means the reset is clean) and `plain migrations create --check` (no pending changes).
-6. Commit and deploy. On every other environment, run `plain migrations prune --yes`. No actual SQL runs — it only cleans up migration history records. If `migrations prune` is already in your deploy steps, no changes are needed.
+Options:
 
-**Things to keep in mind:**
+- `--shipped-in <version>` — the release this reset ships in, named in the refusal a database that missed the leaf gets, and required before the package can be reset again. Plain's own packages leave it empty and fill it in at release time (a repository test enforces it, and the package's `plain.postgres` minimum is raised to the first release that understands baselines); an app should pass the version or deploy this ships in.
+- `--dry-run` — print the baseline and the deletion list, write nothing.
 
-- If resetting multiple packages, process depended-on packages first — the new `0001_initial` may have cross-package FK dependencies.
-- Data migrations (`RunPython`) in the deleted history are gone, which is fine since they've already run everywhere.
-- If CI runs `migrations create --check` or `migrations apply --check`, the reset PR must be merged and deployed before those checks pass in other branches.
+**Dependencies.** The baseline depends on each other package its models reference, at the earliest migration of that package where the referenced models exist — and on nothing else. A package that another package pinned early _and_ whose models now point back at that package cannot get a single root: the graph would be a cycle, and the command refuses with it. That is a limit of migration graphs, not of the command; nothing to do with a second package fixes it.
+
+**Support boundaries.** Adoption checks that the sentinel is recorded and the tables exist, not columns; editing history behind a released leaf is outside what any check can catch. A data migration in _another_ package that read this package's historical state (a field the baseline no longer has) keeps loading but can fail on a fresh database; the command cannot see it.
+
+**Second reset.** Run it again later and the previous baseline joins `retired`. It refuses while the previous baseline's `shipped_in` is empty: nothing shipped it yet, so superseding its name would strand every database still at the original sentinel — once that baseline has shipped everywhere, set its `shipped_in` to the version that shipped it and reset again; otherwise restore the history and reset once.
 
 ### Data migrations
 
@@ -685,7 +708,9 @@ def forwards(models, schema_editor):
 
 For large tables, chunk the work (e.g. by ID range) and commit between batches so no single transaction holds locks for too long.
 
-See [Structural migrations](#structural-migrations) for shared commands (`apply`, `list`, `squash`, `prune`).
+When the package's history is later collapsed (see [Resetting migrations](#resetting-migrations)), `plain migrations reset` refuses while any `RunPython`/`RunSQL` is unmarked. Pass `skip_on_reset=True` once a fresh database can do without its effect; if it can't, move the effect into a seed first.
+
+See [Structural migrations](#structural-migrations) for shared commands (`apply`, `list`, `prune`).
 
 #### Cascading deletes inside data migrations
 

{plain_postgres-0.117.0 → plain_postgres-0.118.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,32 @@
 # plain-postgres changelog
 
+## [0.118.0](https://github.com/dropseed/plain/releases/plain-postgres@0.118.0) (2026-09-18)
+
+### What's changed
+
+- Added baseline migrations. A package whose migration history has been collapsed ships one baseline in place of the deleted files: an ordinary migration with `supersedes` (the last deleted migration, whose record proves a database is caught up), `retired` (every deleted name, so other packages' dependencies on them still resolve), and `shipped_in` (the release that shipped the reset). `plain postgres sync` and `plain migrations apply` decide what to do from the database's records alone — a fresh database runs the baseline, a database that recorded the superseded migration adopts it with a single record write and no DDL, and a database from before the reset, or one whose tables are missing or unrecorded, is refused with a one-line remedy. Nothing deletes records on its own ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae), [4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- Added `plain migrations reset <package>`, which writes the baseline (the package's current schema as `CreateModel`s, named past the current leaf) and deletes the old migration files. Before touching anything it checks that the models agree with the history, that the package has a single leaf, that the deleted history holds nothing a fresh database would miss, that the migrations directory is committed and unmodified in git, and that the result loads. `--dry-run` prints the baseline and the deletion list; `--shipped-in <version>` records the release the reset ships in, which is named in the refusal a stale database gets and is required before the package can be reset a second time ([7c6045b1b9](https://github.com/dropseed/plain/commit/7c6045b1b9), [4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- Removed `Migration.replaces` and the `plain migrations squash` command. A migration file that still declares `replaces` now fails to load with a `BadMigrationError` that lists the steps to convert it back to ordinary records ([e154abc239](https://github.com/dropseed/plain/commit/e154abc239))
+- Renamed `Operation.elidable` to `skip_on_reset`; `RunPython` and `RunSQL` take it as `skip_on_reset=True`, and it is serialized into migration files when set. It means "a fresh database can do without this operation's effect" — `plain migrations reset` refuses while any `RunPython`, `RunSQL`, custom operation, or database-side `SeparateDatabaseAndState` in the deleted history is unmarked. The optimizer no longer elides operations across it ([7c6045b1b9](https://github.com/dropseed/plain/commit/7c6045b1b9))
+- `plain migrations prune` takes an optional `<package>` argument that removes every record for that package, which is how you let its baseline run again once the tables are gone. Without an argument it removes orphan records — recorded migrations with no file on disk that no baseline retired — and keeps retired records as the rollback path across a reset. "Stale" became "orphan" in its output ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae))
+- `plain migrations list` annotates a baseline waiting to be recorded with `(baseline: will be recorded, not run)` and prints the planner's refusal for a package as a red `!` line. The `[-]` "partially recorded" marker for squashed migrations is gone with `replaces` ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae))
+- `plain migrations apply --plan` and `plain postgres sync` report baselines being recorded separately from migrations being run ("Applying 2 migration(s), recording 1 baseline(s)"). `plain migrations apply <package> <migration> --fake` skips the consistent-history check — faking a named migration is how that history gets repaired — and can record a baseline by hand on a database whose tables already exist ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae), [4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- Preflight: `postgres.prunable_migrations` now reports orphan records as a warning without telling you to prune them (they are what rollback needs, and a branch switch or a reset leaves them behind on purpose), and the new `postgres.migration_history` check reports as an error any database the planner would refuse, so a deploy finds out before the release phase ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae))
+- Added `MigrationsError` as the base class for `AmbiguityError`, `BadMigrationError`, `CircularDependencyError`, `InconsistentMigrationHistory`, `NodeNotFoundError`, and the new `MigrationHistoryError` family (`ResetBoundaryError`, `StaleMigrationRecordsError`, `UnrecordedTablesError`), so a caller that only reports can catch one thing. A dependency on an unknown or unmigrated package raises `BadMigrationError` instead of `ValueError`. Database management commands print a `MigrationHistoryError` as one clean line instead of a traceback ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae), [4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- `MigrationExecutor` gained `split_plan()`, which returns a `PendingMigrations(run=, record=)` for a plan, a `record_only` property, and a `repair_baseline` argument on `migration_plan()`; `record_migration()` and `check_replacements()` were removed and a migration's record is now written inside the schema editor's transaction. `MigrationLoader` lost the `replace_migrations` argument and `replacements` attribute and gained `baselines`, `baseline_status`, `retired_to_baseline`, `resolved_dependencies()`, `orphan_records()`, and `with_migrations()`. `MigrationGraph.remove_replaced_nodes()` and `remove_replacement_node()` are gone ([e154abc239](https://github.com/dropseed/plain/commit/e154abc239), [b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae), [4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- The migration writer serializes an operation from what its `deconstruct()` returns — positional arguments as given, then every keyword argument in order — instead of inspecting the operation's `__init__` signature. A custom operation whose `deconstruct()` returns a keyword its `__init__` doesn't name positionally is now written faithfully ([4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- `MigrationAutodetector.arrange_for_graph()` and `deep_deconstruct()` are now module-level functions in `plain.postgres.migrations.autodetector` (`arrange_for_graph` takes `questioner=` as a keyword), alongside the new `detect_model_changes()`, `describe_changes()`, and `package_creation_operations()`. `parse_number()` no longer special-cases `_squashed_` names ([7c6045b1b9](https://github.com/dropseed/plain/commit/7c6045b1b9), [4eb466fa46](https://github.com/dropseed/plain/commit/4eb466fa46))
+- Added `plain.postgres.options.default_db_table()` and `CONVERGENCE_OPTIONS` ([b89b33acae](https://github.com/dropseed/plain/commit/b89b33acae))
+
+### Upgrade instructions
+
+- If any migration file declares `replaces`, the loader refuses to start and prints the conversion steps: delete the `replaces = ...` line, delete any replaced migration still on disk and repoint dependencies that named it to the replacing migration, run `plain migrations apply <package> <migration> --fake` on every database that had applied all of the replaced migrations, then `plain migrations prune` on each. Do this on staging and production before their next deploy.
+- Replace `elidable=True` with `skip_on_reset=True` on `RunPython` and `RunSQL`, and rename the `elidable` class attribute to `skip_on_reset` on custom operations.
+- Replace `plain migrations squash` in any docs or scripts with `plain migrations reset <package>`. Read the "Resetting migrations" section of the postgres docs first — it deletes files, and every environment must have applied the package's current leaf before the reset ships.
+- Deploy steps that ran `plain migrations prune` after a reset can drop it: records a baseline retired stay on purpose, and `prune` now leaves them alone.
+- If you subclassed or called migration internals: `MigrationLoader(replace_migrations=...)` and `loader.replacements` no longer exist, `MigrationExecutor.record_migration()` and `check_replacements()` are gone, and `MigrationAutodetector.arrange_for_graph()` / `.deep_deconstruct()` are now module-level imports from `plain.postgres.migrations.autodetector`.
+- If you caught `ValueError` from the loader for a dependency on an unknown package, catch `BadMigrationError` (or `MigrationsError`).
+
 ## [0.117.0](https://github.com/dropseed/plain/releases/plain-postgres@0.117.0) (2026-09-04)
 
 ### What's changed

{plain_postgres-0.117.0 → plain_postgres-0.118.0}/plain/postgres/README.md

@@ -131,7 +131,7 @@ PLAIN_POSTGRES_MANAGEMENT_URL=postgresql://app@postgres:5432/myapp
 
 When `POSTGRES_MANAGEMENT_URL` is set, these commands connect through it instead of `POSTGRES_URL`:
 
-- `plain migrations create`, `plain migrations apply`, `plain migrations list`, `plain migrations prune`, `plain migrations squash`
+- `plain migrations create`, `plain migrations apply`, `plain migrations list`, `plain migrations prune`
 - `plain postgres sync`, `plain postgres converge`, `plain postgres schema`
 - `plain postgres diagnose`, `plain postgres drop-unknown-tables`, `plain postgres shell`
 
@@ -590,15 +590,16 @@ Key flags:
 
 Shared commands (apply equally to structural and data migrations):
 
-| Command                                     | Purpose                                              |
-| ------------------------------------------- | ---------------------------------------------------- |
-| `plain migrations apply`                    | Apply pending migrations                             |
-| `plain migrations apply --plan`             | Preview what would run                               |
-| `plain migrations apply --check`            | Exit non-zero if unapplied migrations exist (for CI) |
-| `plain migrations apply --fake`             | Mark as applied without running SQL                  |
-| `plain migrations list`                     | View migration status by package                     |
-| `plain migrations squash <pkg> <migration>` | Squash migrations into one                           |
-| `plain migrations prune`                    | Remove stale migration records                       |
+| Command                            | Purpose                                                           |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `plain migrations apply`           | Apply pending migrations                                          |
+| `plain migrations apply --plan`    | Preview what would run                                            |
+| `plain migrations apply --check`   | Exit non-zero if unapplied migrations exist (for CI)              |
+| `plain migrations apply --fake`    | Mark as applied without running SQL                               |
+| `plain migrations list`            | View migration status by package                                  |
+| `plain migrations prune`           | Remove orphan migration records                                   |
+| `plain migrations prune <package>` | Remove every record for one package (lets its baseline run again) |
+| `plain migrations reset <package>` | Replace the package's history with one baseline                   |
 
 #### Development workflow
 
@@ -613,43 +614,65 @@ Use this when migrations exist only in your local dev environment and haven't be
 3. `plain migrations create` — creates a single fresh migration with all the changes
 4. `plain migrations apply --fake` — marks the new migration as applied (the schema is already correct from the old migrations)
 
-**Consolidating committed migrations (squash):**
+Migrations that are committed but not yet deployed anywhere can be consolidated the same way if every developer resets their database; production then applies the consolidated migration normally. Once a migration has reached any deployed environment, use a full reset (below).
 
-Use this when migrations have already been committed or deployed to other environments.
+#### Baselines
 
-`plain migrations squash <package> <migration>` creates a replacement migration with a `replaces` list. Keep the original files until all environments have migrated past the squash point, then delete them and run `migrations prune`.
+A package whose migration history has been reset ships one **baseline** migration in place of the deleted files. It is an ordinary migration with three extra attributes:
 
-**Which method to use:**
-
-| Scenario                                  | Method                                                  |
-| ----------------------------------------- | ------------------------------------------------------- |
-| Migrations are local only (not committed) | Delete-and-recreate                                     |
-| Migrations are committed but not deployed | Delete-and-recreate (if all developers reset) or squash |
-| Migrations are deployed to production     | Squash or full reset                                    |
+```python
+class Migration(migrations.Migration):
+    supersedes = "0008_add_widgets"  # the sentinel: the last deleted migration; its record proves a database is caught up
+    retired = (
+        "0001_initial",
+        ...,
+        "0008_add_widgets",
+    )  # every deleted name, so dependencies on them still resolve
+    shipped_in = "0.61"  # the release that shipped the reset; empty until it has
+    dependencies = (("users", "0001_initial"),)
+    operations = (migrations.CreateModel(...), ...)
+```
+
+What `plain postgres sync` (or `plain migrations apply`) does with it depends only on what the database has recorded:
+
+| Database has                                                      | Result                                                                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| No records for the package, no tables (fresh, or newly installed) | Runs the baseline like any migration                                                                   |
+| No records for the package, but its tables exist                  | Refuses: record it with `apply <pkg> <baseline> --fake` if the schema is current, else drop the tables |
+| The baseline recorded                                             | Nothing                                                                                                |
+| The `supersedes` migration recorded                               | Records the baseline without running it - one row, once                                                |
+| Records, but not the `supersedes` migration                       | Refuses: upgrade through the last release that still has that migration                                |
+| Records, but none of the package's tables                         | Refuses: `plain migrations prune <pkg>` drops the records; then it runs                                |
+
+`plain migrations apply --plan --check` and `plain postgres sync --check` report a baseline waiting to be recorded as a pending change, and `plain preflight` reports a refusal as an error. Nothing ever deletes records on its own; `prune` stays explicit. A database where the baseline _ran_ (rather than was recorded) cannot roll back to code from before the reset.
 
 #### Resetting migrations
 
-Over time a package can accumulate dozens of migrations. Once **every environment** (dev, staging, production) has applied all of them, you can replace the entire history with a single fresh `0001_initial`.
+Once **every environment** has applied a package's migrations, its history can be collapsed into one baseline:
 
-**Prerequisites:**
+```bash
+plain migrations reset <package>
+```
 
-- Every environment (dev, staging, production) has applied all existing migrations. If any environment is behind, the reset will break it.
-- The first migration is named `0001_initial` (the default). If it has a different name, this workflow won't work cleanly.
+The command writes `NNNN_baseline.py` past the current leaf (the package's newest migration) — the package's schema as `CreateModel`s, `supersedes` set to the leaf, `retired` set to every deleted name — and deletes the old files. Commit the new file and the deletions together. Existing databases adopt it with one record on their next `plain postgres sync`; the retired records stay as the rollback path; a fresh database runs it. Other packages' migrations that depended on a deleted name resolve to the baseline; nothing there needs rewriting. Do not add a `prune` step. Before it touches anything it checks, in this order:
 
-**Steps:**
+- The models agree with the history (`plain migrations create` would write nothing). A change the history doesn't hold would be folded into the baseline, and databases that adopt it would never run it.
+- The package ends in a single leaf, and no earlier baseline is waiting unreleased (see second resets below).
+- The deleted history holds nothing a fresh database would miss. `RunPython`, `RunSQL`, any custom operation, and anything on the database side of `SeparateDatabaseAndState` are listed and refused until each carries `skip_on_reset=True` — "a fresh database can do without this." If it can't (a seed, an extension), move the effect somewhere a fresh database does get it, then mark it.
+- The migrations directory is committed — tracked, unmodified, inside a git repository (so an installed package in site-packages cannot be reset; the check applies to `--dry-run` too). The leaf becomes the baseline's sentinel, so it cannot be something you created a minute ago. No check can prove every environment applied it — the command prints that obligation, and a database that hasn't is refused until it does. If anything goes wrong the output has already printed the one line that puts it back: `git checkout -- <migrations dir> && rm <the new baseline>`.
+- The result loads: dependencies on retired names resolve, the graph has no cycle, the baseline reproduces the models exactly.
+- Nothing the baseline needs is defined inside a migration file. A custom field class or callable written in the history disappears with it; move it into the app first.
 
-1. Run `plain migrations list` locally and verify everything is applied.
-2. Delete every file in the package's `migrations/` directory except `__init__.py`.
-3. Run `plain migrations create` to generate a fresh `0001_initial`.
-4. Run `plain migrations prune --yes` to remove stale DB records. The existing `0001_initial` record matches the new file, so the database is immediately up to date.
-5. Verify with `plain postgres schema` (zero issues means the reset is clean) and `plain migrations create --check` (no pending changes).
-6. Commit and deploy. On every other environment, run `plain migrations prune --yes`. No actual SQL runs — it only cleans up migration history records. If `migrations prune` is already in your deploy steps, no changes are needed.
+Options:
 
-**Things to keep in mind:**
+- `--shipped-in <version>` — the release this reset ships in, named in the refusal a database that missed the leaf gets, and required before the package can be reset again. Plain's own packages leave it empty and fill it in at release time (a repository test enforces it, and the package's `plain.postgres` minimum is raised to the first release that understands baselines); an app should pass the version or deploy this ships in.
+- `--dry-run` — print the baseline and the deletion list, write nothing.
 
-- If resetting multiple packages, process depended-on packages first — the new `0001_initial` may have cross-package FK dependencies.
-- Data migrations (`RunPython`) in the deleted history are gone, which is fine since they've already run everywhere.
-- If CI runs `migrations create --check` or `migrations apply --check`, the reset PR must be merged and deployed before those checks pass in other branches.
+**Dependencies.** The baseline depends on each other package its models reference, at the earliest migration of that package where the referenced models exist — and on nothing else. A package that another package pinned early _and_ whose models now point back at that package cannot get a single root: the graph would be a cycle, and the command refuses with it. That is a limit of migration graphs, not of the command; nothing to do with a second package fixes it.
+
+**Support boundaries.** Adoption checks that the sentinel is recorded and the tables exist, not columns; editing history behind a released leaf is outside what any check can catch. A data migration in _another_ package that read this package's historical state (a field the baseline no longer has) keeps loading but can fail on a fresh database; the command cannot see it.
+
+**Second reset.** Run it again later and the previous baseline joins `retired`. It refuses while the previous baseline's `shipped_in` is empty: nothing shipped it yet, so superseding its name would strand every database still at the original sentinel — once that baseline has shipped everywhere, set its `shipped_in` to the version that shipped it and reset again; otherwise restore the history and reset once.
 
 ### Data migrations
 
@@ -672,7 +695,9 @@ def forwards(models, schema_editor):
 
 For large tables, chunk the work (e.g. by ID range) and commit between batches so no single transaction holds locks for too long.
 
-See [Structural migrations](#structural-migrations) for shared commands (`apply`, `list`, `squash`, `prune`).
+When the package's history is later collapsed (see [Resetting migrations](#resetting-migrations)), `plain migrations reset` refuses while any `RunPython`/`RunSQL` is unmarked. Pass `skip_on_reset=True` once a fresh database can do without its effect; if it can't, move the effect into a seed first.
+
+See [Structural migrations](#structural-migrations) for shared commands (`apply`, `list`, `prune`).
 
 #### Cascading deletes inside data migrations
 

{plain_postgres-0.117.0 → plain_postgres-0.118.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -99,3 +99,4 @@ Run `uv run plain docs postgres` for check details, thresholds, and production u
 - Use `model_options = postgres.Options(...)` not `class Meta`
 - Never format raw SQL strings — always use parameterized queries
 - Migrations are forward-only — no reverse migrations. `RunPython` takes a single callable (no `reverse_code` or `noop`). The callable signature is `fn(models, schema_editor)`, not `fn(apps, schema_editor)`
+- No `squashmigrations`; collapse a package's history with `plain migrations reset <package>`. `RunPython`/`RunSQL` take `skip_on_reset=True` (Django's `elidable`)

{plain_postgres-0.117.0 → plain_postgres-0.118.0}/plain/postgres/cli/decorators.py

@@ -8,6 +8,7 @@ from typing import Any
 import click
 
 from ..db import use_management_connection
+from ..migrations.exceptions import MigrationHistoryError
 from ..schema_lock import SchemaLockLost, SchemaLockTimeout, schema_lock
 
 
@@ -30,11 +31,17 @@ def database_management_command[F: Callable[..., Any]](f: F) -> F:
     database management operations. Inside the command, `get_connection()`
     returns a connection opened against `POSTGRES_MANAGEMENT_URL` (falling
     back to `POSTGRES_URL` when unset).
+
+    A planner refusal (`MigrationHistoryError`) surfaces as one clean line
+    instead of a traceback, the same way `cli_schema_lock` treats lock errors.
     """
 
     @functools.wraps(f)
     def wrapper(*args: Any, **kwargs: Any) -> Any:
-        with use_management_connection():
-            return f(*args, **kwargs)
+        try:
+            with use_management_connection():
+                return f(*args, **kwargs)
+        except MigrationHistoryError as e:
+            raise click.ClickException(str(e)) from e
 
     return wrapper  # ty: ignore[invalid-return-type]