From 29d875bd1cfe1494444a7d69f8e3833643e86895 Mon Sep 17 00:00:00 2001 From: Tianzhou Date: Fri, 16 Oct 2026 01:12:52 +0800 Subject: [PATCH 1/2] docs: simplify the partitioned-index notes for dump, ignore, and plan The notes added in #643 ran to several paragraphs each, with worked examples and repeated explanations of constraint-backed indexes. Trim each to a short paragraph in the same style as the circular-foreign-key note from #642, keeping the behavior a reader needs: creation order, the indexes/ output directory, the dump error for ignored attached children, and when plan falls back to recursive index creation. Co-Authored-By: Claude Fable 5.1 --- docs/cli/dump.mdx | 15 ++++++--------- docs/cli/ignore.mdx | 26 ++++++++------------------ docs/cli/plan.mdx | 22 ++++++++-------------- 3 files changed, 22 insertions(+), 41 deletions(-) diff --git a/docs/cli/dump.mdx b/docs/cli/dump.mdx index 2c7de731..e214d164 100644 --- a/docs/cli/dump.mdx +++ b/docs/cli/dump.mdx @@ -256,15 +256,12 @@ prefix distinguishes multiple constraints on the same table. The exporter keeps these files in dependency order in `schema.sql`, after the required tables. Load files in the generated include order to preserve these dependencies. -For partitioned indexes, `pgschema` creates the tables and leaf indexes first. -The exporter then creates each parent index with `ON ONLY` and attaches its -recorded child indexes with `ALTER INDEX ... ATTACH PARTITION`. This preserves -custom child names and leaves intentionally unattached indexes separate. -If a child index backs a `UNIQUE` or `PRIMARY KEY` constraint, the constraint -generator creates that index. The exporter then attaches it to its recorded -parent index. -Multi-file dumps put parent indexes and their attachments under `indexes/`, -for example `indexes/0001_events_lookup.sql`, after the table includes. +For partitioned indexes, `pgschema` creates the tables and leaf indexes first, +then each parent index with `ON ONLY`, then attaches the children with +`ALTER INDEX ... ATTACH PARTITION`. This keeps custom child index names and +leaves unattached indexes unattached. Multi-file dumps write parent indexes and +their attachments under `indexes/`, such as `indexes/0001_events_lookup.sql`, +after the table includes. Each individual file (e.g., `tables/users.sql`) contains the specific object definition: ```sql diff --git a/docs/cli/ignore.mdx b/docs/cli/ignore.mdx index 3af60109..7a20da0b 100644 --- a/docs/cli/ignore.mdx +++ b/docs/cli/ignore.mdx @@ -121,24 +121,14 @@ The `[privileges]` section filters explicit grants (`GRANT ... TO role`), includ ## Partitioned indexes -When `dump` retains a partitioned index, it must also retain that index's attached -children. If the inspector excludes an attached child because of an index, table, -or owning constraint ignore pattern, `dump` returns an error naming the parent and child before writing -any output. Existing output files remain unchanged. `dump` performs the same check -for nested partitions. - -For example, `event_unique` has an attached child named `early_custom_unique`. -If `early_custom_unique` is ignored while `event_unique` is retained, `dump` returns -an error. -Remove the conflicting ignore pattern or add a negation pattern to retain the -child index and its table. Ignoring an unattached index remains supported. - -For constraint-backed child indexes, use `[constraints]` to ignore the owning -constraint. An `[indexes]` pattern does not exclude a constraint-backed index. -For example, if `early_custom_unique` is a `UNIQUE` constraint, excluding it under -`[constraints]` while retaining its parent index causes `dump` to reject the dump. - -`plan` and `apply` retain their existing ignore behavior. +A retained partitioned index must keep all of its attached child indexes. If a +pattern ignores an attached child (by index, table, or owning constraint) while +its parent is retained, `dump` fails before writing any output. Remove the +pattern or add a negation pattern to keep the child. Ignoring an unattached +index is fine. + +`[indexes]` patterns do not match constraint-backed indexes; use `[constraints]` +to ignore those. ## Constraints diff --git a/docs/cli/plan.mdx b/docs/cli/plan.mdx index 5ba553f9..22e8ba5c 100644 --- a/docs/cli/plan.mdx +++ b/docs/cli/plan.mdx @@ -18,20 +18,14 @@ By default, pgschema uses an embedded PostgreSQL instance to validate your desir ## Creating partitioned indexes -When `plan` creates an entirely new managed partition hierarchy and all recorded -table and index dependencies are present, it preserves standalone index names and -attachments. It creates the tables and leaf indexes first, then parent indexes -with `ON ONLY`, explicit attachments, and dependent foreign keys. - -For example, creating new `events` tables preserves the attachment of a named -child index `early_custom_lookup` to `event_lookup`. An equivalent unattached index -stays unattached. The same creation order applies when unrelated tables already -exist in the target schema. - -For hierarchies containing existing tables, unmanaged ancestors, or excluded -dependencies, migration generation retains recursive index creation. This does -not reconcile index attachments on existing tables. Constraint-backed indexes -remain under constraint management. +When `plan` creates a partition hierarchy from scratch, it keeps the index names +and attachments from the desired state: tables and leaf indexes first, then +parent indexes with `ON ONLY`, then the attachments and any dependent foreign +keys. An unattached index stays unattached. + +When part of the hierarchy already exists in the target, or part of it is +ignored, `plan` falls back to recursive index creation and does not reconcile +attachments on existing tables. ## Basic Usage From aa8c2c9da57482b432d545ffcd9d2c1ddab0cbac Mon Sep 17 00:00:00 2001 From: Tianzhou Date: Fri, 16 Oct 2026 01:19:44 +0800 Subject: [PATCH 2/2] docs: keep the standalone-index scope in the plan partitioned-index note The explicit ON ONLY plus ATTACH PARTITION schedule only covers standalone indexes; indexes backing PRIMARY KEY and UNIQUE constraints are still created through their constraints. Restore the qualifier and the caveat that the simplification dropped. Co-Authored-By: Claude Fable 5.1 --- docs/cli/plan.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/cli/plan.mdx b/docs/cli/plan.mdx index 22e8ba5c..fdba0061 100644 --- a/docs/cli/plan.mdx +++ b/docs/cli/plan.mdx @@ -18,10 +18,11 @@ By default, pgschema uses an embedded PostgreSQL instance to validate your desir ## Creating partitioned indexes -When `plan` creates a partition hierarchy from scratch, it keeps the index names -and attachments from the desired state: tables and leaf indexes first, then -parent indexes with `ON ONLY`, then the attachments and any dependent foreign -keys. An unattached index stays unattached. +When `plan` creates a partition hierarchy from scratch, it keeps standalone index +names and attachments from the desired state: tables and leaf indexes first, +then parent indexes with `ON ONLY`, then the attachments and any dependent +foreign keys. An unattached index stays unattached. Constraint-backed indexes +remain under constraint management. When part of the hierarchy already exists in the target, or part of it is ignored, `plan` falls back to recursive index creation and does not reconcile