plain.postgres 0.91.0__tar.gz → 0.92.0__tar.gz

{plain_postgres-0.91.0 → plain_postgres-0.92.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.91.0
+Version: 0.92.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -17,7 +17,10 @@ Description-Content-Type: text/markdown
 - [Overview](#overview)
 - [Database connection](#database-connection)
 - [Querying](#querying)
-- [Migrations](#migrations)
+- [Schema management](#schema-management)
+    - [Syncing](#syncing)
+    - [Migrations](#migrations)
+    - [Convergence](#convergence)
 - [Fields](#fields)
 - [Relationships](#relationships)
 - [Constraints](#constraints)
@@ -440,49 +443,86 @@ conn.set_read_only(False)  # back to normal
 
 Read-only mode must be set outside a transaction — calling it inside `atomic()` raises `TransactionManagementError`.
 
-## Migrations
+## Schema management
 
-Migrations track changes to your models and update the database schema accordingly. They are Python files stored in your app's `migrations/` directory.
+Your database schema is managed by two complementary systems: **migrations** and **convergence**. Migrations handle structural changes — creating tables, adding columns, renaming things. Convergence handles everything declarative — indexes, constraints, foreign keys, and NOT NULL enforcement. You declare these on your models and convergence makes the database match.
 
-### Creating migrations
+```
+Migrations                      Convergence
+(imperative, ordered)           (declarative, idempotent)
+─────────────────────────────   ─────────────────────────────
+Create / drop tables            Indexes
+Add / remove / rename columns   Check constraints
+Change column types             Unique constraints
+Data migrations (RunPython)     Foreign key constraints
+Custom SQL (RunSQL)             NOT NULL enforcement
+```
+
+This split exists because structural changes (adding a column) must happen in a specific order and can't be retried, while declarative objects (indexes, constraints) can be compared against model definitions and fixed automatically — even if a previous attempt failed.
+
+### Syncing
+
+The primary command for all schema management is `postgres sync`. It runs migrations and convergence together:
 
 ```bash
-plain migrations create
+plain postgres sync
 ```
 
-Key flags:
+```
+plain postgres sync
+│
+├─ 1. Create migrations (development only)
+│     Detects model changes, generates migration files
+│
+├─ 2. Apply migrations
+│     Runs pending migrations in a single transaction
+│
+└─ 3. Converge
+      Compares indexes, constraints, FKs, and nullability
+      against model declarations — applies fixes independently
+```
 
-- `--dry-run` — Show what migrations would be created (with operations and SQL) without writing files
-- `--check` — Exit non-zero if migrations are needed (for CI)
-- `--empty <package>` — Create an empty migration for custom data migrations
-- `--name <name>` — Set the migration filename
-- `-v 3` — Show full migration file contents
+In development (`DEBUG=True`), sync auto-generates migrations before applying them. In production, it only applies existing migrations and converges.
 
-Only write migrations by hand if they are custom data migrations.
+| Command                                 | Purpose                                                               |
+| --------------------------------------- | --------------------------------------------------------------------- |
+| `plain postgres sync`                   | Create + apply migrations + converge (the one command for everything) |
+| `plain postgres sync --check`           | Exit non-zero if anything would change (for CI)                       |
+| `plain postgres sync --drop-undeclared` | Also remove indexes/constraints not declared on any model             |
+| `plain postgres schema`                 | Show schema state with drift detection                                |
+| `plain postgres schema --json`          | Machine-readable schema output                                        |
+| `plain postgres converge`               | Run convergence alone (advanced)                                      |
 
-### Running migrations
+### Migrations
+
+Migrations track structural changes to your models. They are Python files stored in your app's `migrations/` directory.
 
 ```bash
-plain migrations apply
+plain migrations create
 ```
 
 Key flags:
 
-- `--plan` — Show what migrations would run without applying them
-- `--check` — Exit non-zero if unapplied migrations exist (for CI)
-- `--fake` — Mark migrations as applied without running them
-
-### Viewing migration status
+- `--dry-run` — Show what migrations would be created (with operations and SQL) without writing files
+- `--check` — Exit non-zero if migrations are needed (for CI)
+- `--empty <package>` — Create an empty migration for custom data migrations
+- `--name <name>` — Set the migration filename
 
-```bash
-plain migrations list
-```
+Only write migrations by hand if they are custom data migrations.
 
-`migrations apply` has no `--list` or `--status` flag. Use `plain migrations list`.
+Other migration commands:
 
-- `--format plan` — Show in dependency order instead of grouped by package
+| 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                       |
 
-### Development workflow
+#### Development workflow
 
 During development, iterating on models often produces multiple small migrations (0002, 0003, 0004...). Clean these up before committing.
 
@@ -509,7 +549,7 @@ Use this when migrations have already been committed or deployed to other enviro
 | Migrations are committed but not deployed | Delete-and-recreate (if all developers reset) or squash |
 | Migrations are deployed to production     | Squash or full reset                                    |
 
-### Resetting migrations
+#### 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`.
 
@@ -533,10 +573,61 @@ Over time a package can accumulate dozens of migrations. Once **every environmen
 - 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.
 
-### Other migration commands
+### Convergence
+
+Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
+
+```python
+@postgres.register_model
+class User(postgres.Model):
+    email: str = types.EmailField()
+    username: str = types.TextField(max_length=150)
+    age: int = types.IntegerField()
+
+    model_options = postgres.Options(
+        indexes=[
+            postgres.Index(fields=["email"], name="users_email_idx"),
+        ],
+        constraints=[
+            postgres.UniqueConstraint(fields=["email"], name="users_email_uniq"),
+            postgres.CheckConstraint(check=postgres.Q(age__gte=0), name="users_age_positive"),
+        ],
+    )
+```
+
+When you run `postgres sync`, convergence detects that these indexes and constraints are missing and creates them — using non-blocking DDL operations where possible (e.g. `CREATE INDEX CONCURRENTLY`, `ADD CONSTRAINT ... NOT VALID` followed by `VALIDATE CONSTRAINT`).
+
+**Key properties:**
+
+- **Idempotent** — safe to run repeatedly. If the database already matches, nothing happens.
+- **Non-blocking** — indexes are built with `CONCURRENTLY`, constraints use `NOT VALID` + `VALIDATE` to avoid locking writes.
+- **Per-operation commits** — each fix is committed independently so a single failure doesn't roll back other fixes.
+- **Self-healing** — detects and rebuilds `INVALID` indexes (e.g. from a previously failed `CREATE INDEX CONCURRENTLY`).
+- **Rename-aware** — detects renamed indexes and constraints by matching their structure, avoiding unnecessary drop + recreate.
+
+**Inspecting schema state:**
+
+Use `postgres schema` to see what convergence would do. It shows every model's columns, indexes, and constraints compared against the database, with issues highlighted:
+
+```bash
+plain postgres schema           # all models
+plain postgres schema User      # single model
+plain postgres schema --json    # machine-readable output
+```
+
+**Staged rollouts:**
+
+Some changes can't be applied automatically. For example, if you add `NOT NULL` to a column that has existing `NULL` rows, convergence will report this as a blocked change and tell you to backfill the data first. Run `postgres sync` again after the backfill.
+
+**Cleanup:**
+
+When you remove an index or constraint from a model, the database object still exists. By default, `postgres sync` reports undeclared objects but doesn't drop them. Use `--drop-undeclared` to remove them:
+
+```bash
+plain postgres sync --drop-undeclared
+```
 
-- `plain migrations squash <package> <migration>` — Squash migrations into one
-- `plain migrations prune` — Remove stale migration records
+Undeclared constraints block sync (they affect query behavior), while undeclared indexes are just reported as warnings.
 
 ## Fields
 
@@ -795,7 +886,7 @@ Field-level validation happens automatically based on field types and constraint
 
 ### Indexes and constraints
 
-You can optimize queries and ensure data integrity with indexes and constraints:
+You can optimize queries and ensure data integrity with indexes and constraints. These are managed automatically by [convergence](#convergence) — just declare them on the model and run `postgres sync`.
 
 ```python
 class User(postgres.Model):

{plain_postgres-0.91.0 → plain_postgres-0.92.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,42 @@
 # plain-postgres changelog
 
+## [0.92.0](https://github.com/dropseed/plain/releases/plain-postgres@0.92.0) (2026-03-30)
+
+### What's changed
+
+- **Foreign key constraints are now managed by convergence, not migrations.** The schema editor no longer creates, drops, or alters FK constraints — convergence handles them declaratively using `ADD CONSTRAINT ... NOT VALID` followed by `VALIDATE CONSTRAINT`. FK constraint names are deterministic and match the old migration-generated names. ([b2b968297fea](https://github.com/dropseed/plain/commit/b2b968297fea), [8658be035a46](https://github.com/dropseed/plain/commit/8658be035a46))
+
+- **NOT NULL enforcement is now managed by convergence.** Column nullability drift is detected and fixed automatically — convergence uses the safe `CHECK NOT VALID → VALIDATE → SET NOT NULL` pattern to avoid long table locks. Columns with existing NULL rows are reported as blocked, requiring a backfill before convergence can proceed. ([5ea3dc589453](https://github.com/dropseed/plain/commit/5ea3dc589453))
+
+- **Managed type boundaries** — convergence now distinguishes managed vs unmanaged index types and constraint types. Only btree/hash indexes and check/unique/FK constraints participate in drift detection and rename matching. Unmanaged types (GIN, GiST, BRIN, exclusion, trigger) are displayed for informational purposes but are never modified or reported as undeclared. ([f123eae2fa56](https://github.com/dropseed/plain/commit/f123eae2fa56))
+
+- **Unique constraint drift detection** — convergence now compares unique constraint definitions (not just column lists), detecting behavioral changes like modified WHERE clauses, opclasses, or expressions. Index-only uniques (partial, expression, or opclass) are correctly handled through both pg_constraint and pg_index. ([09b439e8448a](https://github.com/dropseed/plain/commit/09b439e8448a))
+
+- **Full index definition matching** — index drift detection now compares normalized `CREATE INDEX` definitions instead of just column lists, catching changes to conditions, expressions, opclasses, and include columns. ([70d7a6725498](https://github.com/dropseed/plain/commit/70d7a6725498))
+
+- Removed dead index/constraint/deferred SQL infrastructure and primary-key transition code from the schema editor. ([266b0635f0bf](https://github.com/dropseed/plain/commit/266b0635f0bf), [4a92f5479e4e](https://github.com/dropseed/plain/commit/4a92f5479e4e))
+
+- Rewrote the introspection layer to mirror Postgres catalog structures — `TableState` now uses a unified `constraints` dict keyed by constraint name with `ConType` enum, replacing the separate `unique_constraints`, `check_constraints`, and `foreign_keys` dicts. ([f123eae2fa56](https://github.com/dropseed/plain/commit/f123eae2fa56))
+
+- Expanded schema management documentation with a comprehensive overview of the migrations + convergence split, sync workflow, and convergence behavior. ([57caeee5ff89](https://github.com/dropseed/plain/commit/57caeee5ff89))
+
+### Upgrade instructions
+
+- If you have custom code that interacts with `TableState.unique_constraints`, `TableState.check_constraints`, or `TableState.foreign_keys`, update it to use the unified `TableState.constraints` dict with `ConType` filtering instead.
+- FK constraints in existing databases are left as-is. New FKs will be created by convergence on the next `postgres sync`.
+- NOT NULL enforcement is automatic — `postgres sync` will detect and fix nullability drift. If columns have existing NULL rows, you'll need to backfill before convergence can apply NOT NULL.
+
+## [0.91.1](https://github.com/dropseed/plain/releases/plain-postgres@0.91.1) (2026-03-29)
+
+### What's changed
+
+- Indented `sync` and `converge` sub-items under section headers for readability in environments without ANSI colors (e.g. Heroku deploy logs). ([b6b494dcc698](https://github.com/dropseed/plain/commit/b6b494dcc698))
+- `sync` now uses `MigrationExecutor` directly instead of calling through the CLI layer, giving cleaner indented output. ([b6b494dcc698](https://github.com/dropseed/plain/commit/b6b494dcc698))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.91.0](https://github.com/dropseed/plain/releases/plain-postgres@0.91.0) (2026-03-29)
 
 ### What's changed
@@ -22,7 +59,7 @@
 
 1. **Replace `migrate` with `postgres sync` in deploy scripts and CI.** `postgres sync` applies migrations and runs convergence in a single step. For CI checks, use `postgres sync --check` instead of `migrate --check` / `makemigrations --check`. The lower-level commands are still available as `migrations create` and `migrations apply`.
 
-2. **Remove index/constraint operations from migration files.** Delete any `AddIndex`, `RemoveIndex`, `RenameIndex`, `AddConstraint`, and `RemoveConstraint` operations from your migration files — these classes no longer exist and will cause import errors. If removing an operation leaves `operations = []`, delete the migration file and run `plain migrations prune --yes`. Indexes and constraints declared on your models will be created automatically by convergence.
+2. **Remove index/constraint operations from migration files.** Delete any `AddIndex`, `RemoveIndex`, `RenameIndex`, `AddConstraint`, and `RemoveConstraint` operations from your migration files — these classes no longer exist and will cause import errors. It's fine to leave a migration with `operations = []`. Indexes and constraints declared on your models will be created automatically by convergence.
 
 3. **Replace `PositiveIntegerField`** (and `PositiveBigIntegerField`, `PositiveSmallIntegerField`) with `IntegerField` (or `BigIntegerField`, `SmallIntegerField`) in both models and migration files. Add a `CheckConstraint` if you need to enforce positive values.
 

{plain_postgres-0.91.0 → plain_postgres-0.92.0}/plain/postgres/README.md

@@ -5,7 +5,10 @@
 - [Overview](#overview)
 - [Database connection](#database-connection)
 - [Querying](#querying)
-- [Migrations](#migrations)
+- [Schema management](#schema-management)
+    - [Syncing](#syncing)
+    - [Migrations](#migrations)
+    - [Convergence](#convergence)
 - [Fields](#fields)
 - [Relationships](#relationships)
 - [Constraints](#constraints)
@@ -428,49 +431,86 @@ conn.set_read_only(False)  # back to normal
 
 Read-only mode must be set outside a transaction — calling it inside `atomic()` raises `TransactionManagementError`.
 
-## Migrations
+## Schema management
 
-Migrations track changes to your models and update the database schema accordingly. They are Python files stored in your app's `migrations/` directory.
+Your database schema is managed by two complementary systems: **migrations** and **convergence**. Migrations handle structural changes — creating tables, adding columns, renaming things. Convergence handles everything declarative — indexes, constraints, foreign keys, and NOT NULL enforcement. You declare these on your models and convergence makes the database match.
 
-### Creating migrations
+```
+Migrations                      Convergence
+(imperative, ordered)           (declarative, idempotent)
+─────────────────────────────   ─────────────────────────────
+Create / drop tables            Indexes
+Add / remove / rename columns   Check constraints
+Change column types             Unique constraints
+Data migrations (RunPython)     Foreign key constraints
+Custom SQL (RunSQL)             NOT NULL enforcement
+```
+
+This split exists because structural changes (adding a column) must happen in a specific order and can't be retried, while declarative objects (indexes, constraints) can be compared against model definitions and fixed automatically — even if a previous attempt failed.
+
+### Syncing
+
+The primary command for all schema management is `postgres sync`. It runs migrations and convergence together:
 
 ```bash
-plain migrations create
+plain postgres sync
 ```
 
-Key flags:
+```
+plain postgres sync
+│
+├─ 1. Create migrations (development only)
+│     Detects model changes, generates migration files
+│
+├─ 2. Apply migrations
+│     Runs pending migrations in a single transaction
+│
+└─ 3. Converge
+      Compares indexes, constraints, FKs, and nullability
+      against model declarations — applies fixes independently
+```
 
-- `--dry-run` — Show what migrations would be created (with operations and SQL) without writing files
-- `--check` — Exit non-zero if migrations are needed (for CI)
-- `--empty <package>` — Create an empty migration for custom data migrations
-- `--name <name>` — Set the migration filename
-- `-v 3` — Show full migration file contents
+In development (`DEBUG=True`), sync auto-generates migrations before applying them. In production, it only applies existing migrations and converges.
 
-Only write migrations by hand if they are custom data migrations.
+| Command                                 | Purpose                                                               |
+| --------------------------------------- | --------------------------------------------------------------------- |
+| `plain postgres sync`                   | Create + apply migrations + converge (the one command for everything) |
+| `plain postgres sync --check`           | Exit non-zero if anything would change (for CI)                       |
+| `plain postgres sync --drop-undeclared` | Also remove indexes/constraints not declared on any model             |
+| `plain postgres schema`                 | Show schema state with drift detection                                |
+| `plain postgres schema --json`          | Machine-readable schema output                                        |
+| `plain postgres converge`               | Run convergence alone (advanced)                                      |
 
-### Running migrations
+### Migrations
+
+Migrations track structural changes to your models. They are Python files stored in your app's `migrations/` directory.
 
 ```bash
-plain migrations apply
+plain migrations create
 ```
 
 Key flags:
 
-- `--plan` — Show what migrations would run without applying them
-- `--check` — Exit non-zero if unapplied migrations exist (for CI)
-- `--fake` — Mark migrations as applied without running them
-
-### Viewing migration status
+- `--dry-run` — Show what migrations would be created (with operations and SQL) without writing files
+- `--check` — Exit non-zero if migrations are needed (for CI)
+- `--empty <package>` — Create an empty migration for custom data migrations
+- `--name <name>` — Set the migration filename
 
-```bash
-plain migrations list
-```
+Only write migrations by hand if they are custom data migrations.
 
-`migrations apply` has no `--list` or `--status` flag. Use `plain migrations list`.
+Other migration commands:
 
-- `--format plan` — Show in dependency order instead of grouped by package
+| 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                       |
 
-### Development workflow
+#### Development workflow
 
 During development, iterating on models often produces multiple small migrations (0002, 0003, 0004...). Clean these up before committing.
 
@@ -497,7 +537,7 @@ Use this when migrations have already been committed or deployed to other enviro
 | Migrations are committed but not deployed | Delete-and-recreate (if all developers reset) or squash |
 | Migrations are deployed to production     | Squash or full reset                                    |
 
-### Resetting migrations
+#### 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`.
 
@@ -521,10 +561,61 @@ Over time a package can accumulate dozens of migrations. Once **every environmen
 - 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.
 
-### Other migration commands
+### Convergence
+
+Convergence compares the indexes, constraints, foreign keys, and nullability declared on your models against what actually exists in the database, then applies fixes to make them match. You don't need to create migrations for these — just declare them on your model and run `postgres sync`.
+
+```python
+@postgres.register_model
+class User(postgres.Model):
+    email: str = types.EmailField()
+    username: str = types.TextField(max_length=150)
+    age: int = types.IntegerField()
+
+    model_options = postgres.Options(
+        indexes=[
+            postgres.Index(fields=["email"], name="users_email_idx"),
+        ],
+        constraints=[
+            postgres.UniqueConstraint(fields=["email"], name="users_email_uniq"),
+            postgres.CheckConstraint(check=postgres.Q(age__gte=0), name="users_age_positive"),
+        ],
+    )
+```
+
+When you run `postgres sync`, convergence detects that these indexes and constraints are missing and creates them — using non-blocking DDL operations where possible (e.g. `CREATE INDEX CONCURRENTLY`, `ADD CONSTRAINT ... NOT VALID` followed by `VALIDATE CONSTRAINT`).
+
+**Key properties:**
+
+- **Idempotent** — safe to run repeatedly. If the database already matches, nothing happens.
+- **Non-blocking** — indexes are built with `CONCURRENTLY`, constraints use `NOT VALID` + `VALIDATE` to avoid locking writes.
+- **Per-operation commits** — each fix is committed independently so a single failure doesn't roll back other fixes.
+- **Self-healing** — detects and rebuilds `INVALID` indexes (e.g. from a previously failed `CREATE INDEX CONCURRENTLY`).
+- **Rename-aware** — detects renamed indexes and constraints by matching their structure, avoiding unnecessary drop + recreate.
+
+**Inspecting schema state:**
+
+Use `postgres schema` to see what convergence would do. It shows every model's columns, indexes, and constraints compared against the database, with issues highlighted:
+
+```bash
+plain postgres schema           # all models
+plain postgres schema User      # single model
+plain postgres schema --json    # machine-readable output
+```
+
+**Staged rollouts:**
+
+Some changes can't be applied automatically. For example, if you add `NOT NULL` to a column that has existing `NULL` rows, convergence will report this as a blocked change and tell you to backfill the data first. Run `postgres sync` again after the backfill.
+
+**Cleanup:**
+
+When you remove an index or constraint from a model, the database object still exists. By default, `postgres sync` reports undeclared objects but doesn't drop them. Use `--drop-undeclared` to remove them:
+
+```bash
+plain postgres sync --drop-undeclared
+```
 
-- `plain migrations squash <package> <migration>` — Squash migrations into one
-- `plain migrations prune` — Remove stale migration records
+Undeclared constraints block sync (they affect query behavior), while undeclared indexes are just reported as warnings.
 
 ## Fields
 
@@ -783,7 +874,7 @@ Field-level validation happens automatically based on field types and constraint
 
 ### Indexes and constraints
 
-You can optimize queries and ensure data integrity with indexes and constraints:
+You can optimize queries and ensure data integrity with indexes and constraints. These are managed automatically by [convergence](#convergence) — just declare them on the model and run `postgres sync`.
 
 ```python
 class User(postgres.Model):

{plain_postgres-0.91.0 → plain_postgres-0.92.0}/plain/postgres/cli/converge.py

@@ -66,32 +66,32 @@ def converge(yes: bool, drop_undeclared: bool) -> None:
                 click.secho(f"  FAILED: {r.item.describe()} — {r.error}", fg="red")
 
         click.echo()
-        click.secho(result.summary, fg="green" if result.ok else "yellow")
+        click.secho(f"  {result.summary}", fg="green" if result.ok else "yellow")
         if not result.ok_for_sync:
             success = False
 
     if plan.blocked:
         click.echo()
-        click.secho("Schema changes require a staged rollout:", fg="red", bold=True)
+        click.secho("  Schema changes require a staged rollout:", fg="red", bold=True)
         for item in plan.blocked:
-            click.secho(f"  {item.drift.describe()}", fg="red")
+            click.secho(f"    {item.drift.describe()}", fg="red")
             if item.guidance:
-                click.secho(f"    {item.guidance}", fg="red", dim=True)
+                click.secho(f"      {item.guidance}", fg="red", dim=True)
         success = False
 
     if not drop_undeclared and plan.blocking_cleanup:
         click.echo()
-        click.secho("Undeclared constraints still in database:", fg="red", bold=True)
+        click.secho("  Undeclared constraints still in database:", fg="red", bold=True)
         for item in plan.blocking_cleanup:
-            click.secho(f"  {item.describe()}", fg="red")
-        click.secho("Rerun with --drop-undeclared to remove them.", fg="red")
+            click.secho(f"    {item.describe()}", fg="red")
+        click.secho("  Rerun with --drop-undeclared to remove them.", fg="red")
         success = False
 
     if not drop_undeclared and plan.optional_cleanup:
         click.echo()
         for item in plan.optional_cleanup:
-            click.echo(f"  {item.describe()}")
-        click.echo("Run with --drop-undeclared to remove undeclared indexes.")
+            click.echo(f"    {item.describe()}")
+        click.echo("  Run with --drop-undeclared to remove undeclared indexes.")
 
     if not success:
         sys.exit(1)

{plain_postgres-0.91.0 → plain_postgres-0.92.0}/plain/postgres/cli/schema.py

@@ -8,7 +8,7 @@ import click
 from ..convergence.analysis import ModelAnalysis, analyze_model
 from ..convergence.planning import can_auto_fix
 from ..db import get_connection
-from ..introspection import get_unknown_tables
+from ..introspection import MANAGED_CONSTRAINT_TYPES, get_unknown_tables
 from ..registry import models_registry
 
 
@@ -24,6 +24,10 @@ def _fixable(msg: str) -> None:
     click.secho(f"  ~ {msg} (auto-fix)", fg="yellow")
 
 
+def _unmanaged(type_label: str) -> None:
+    click.secho(f"  unmanaged ({type_label})", dim=True)
+
+
 def _render_model(analysis: ModelAnalysis) -> None:
     """Render a model analysis result as human-readable output."""
     click.secho(analysis.label, bold=True, nl=False)
@@ -52,7 +56,9 @@ def _render_model(analysis: ModelAnalysis) -> None:
 
         click.echo(f"  {col_display:30s}  {' '.join(type_parts)}", nl=False)
 
-        if col.issue:
+        if col.issue and col.drift and can_auto_fix(col.drift):
+            _fixable(col.issue)
+        elif col.issue:
             _err(col.issue)
         else:
             _ok()
@@ -66,7 +72,9 @@ def _render_model(analysis: ModelAnalysis) -> None:
         fields_str = ", ".join(idx.fields) if idx.fields else "expressions"
         click.echo(f"    {idx.name}  ({fields_str})", nl=False)
 
-        if idx.issue and idx.drift and can_auto_fix(idx.drift):
+        if idx.access_method:
+            _unmanaged(idx.access_method)
+        elif idx.issue and idx.drift and can_auto_fix(idx.drift):
             _fixable(idx.issue)
         elif idx.issue:
             _err(idx.issue)
@@ -79,15 +87,17 @@ def _render_model(analysis: ModelAnalysis) -> None:
         click.secho("  Constraints:", dim=True)
 
     for con in analysis.constraints:
-        con_type = con.type.upper()
+        con_label = con.constraint_type.label.upper()
         if con.fields:
             click.echo(
-                f"    {con.name}  {con_type} ({', '.join(con.fields)})", nl=False
+                f"    {con.name}  {con_label} ({', '.join(con.fields)})", nl=False
             )
         else:
-            click.echo(f"    {con.name}  {con_type}", nl=False)
+            click.echo(f"    {con.name}  {con_label}", nl=False)
 
-        if con.issue and con.drift and can_auto_fix(con.drift):
+        if con.constraint_type not in MANAGED_CONSTRAINT_TYPES:
+            _unmanaged(con.constraint_type.label)
+        elif con.issue and con.drift and can_auto_fix(con.drift):
             _fixable(con.issue)
         elif con.issue:
             _err(con.issue)