[PATCH] doc: Document that invalid indexes are skipped during ATTACH PARTITION

Hi,

added logic to skip invalid indexes when ALTER TABLE ... ATTACH
PARTITION matches partition indexes to the parent table's indexes.
This prevents choosing an incomplete partitioned index as a match,
which could create inconsistent partition index trees.

However, this behavior was never documented. A user who has an
invalid index on a partition (e.g., from a failed CREATE INDEX
CONCURRENTLY) may be surprised when ATTACH PARTITION silently
creates a new index instead of attaching the existing one.

Rght.

-- Before ATTACH: index marked invalid
indexrelid | indisvalid
---------------+------------
child_val_idx | f
(1 row)

-- After ATTACH: invalid index skipped, new one created
indexrelid | indisvalid
----------------+------------
child_val_idx | f
child_val_idx1 | t
(2 rows)

The current documentation says "or, if an equivalent index already exists,
it will be attached to the target table's...", but makes no mention that this
equivalent index must be valid. What about we just reinforce that point
in the current lines of documentation. I also think it's better to flip things
around where the positive case of an equivalent index being found goes
first.

```
-      For each index in the target table, a corresponding
-      one will be created in the attached table; or, if an equivalent
-      index already exists, it will be attached to the target table's index,
-      as if <command>ALTER INDEX ATTACH PARTITION</command> had been executed.
+      For each index in the target table, if a valid equivalent
+      index already exists in the partition, it will be attached
+      to the target table's index, as if
+      <command>ALTER INDEX ATTACH PARTITION</command> had been executed;
+      otherwise, a corresponding one will be created.
```

What do you think?

--
Sami

Hi Sami,

Thanks for the review. I agree, rewriting the existing sentence reads
much better than appending a separate one.

I've adopted your suggestion in v2, with one addition: a sentence
noting that invalid indexes remain on the partition and
should be dropped manually if no longer needed.
I think this helps make it clear that the user is responsible for
cleaning those up.

The full paragraph now reads:

For each index in the target table, if a valid equivalent
index already exists in the partition, it will be attached
to the target table's index, as if ALTER INDEX ATTACH
PARTITION had been executed; otherwise, a corresponding
one will be created. Any invalid indexes on the partition remain
unchanged and should be dropped manually if they are no longer
needed.

v2 patch attached.

--
Mohamed Ali

On Tue, Jun 02, 2026 at 10:58:23PM -0700, Mohamed ALi wrote:

The full paragraph now reads:

For each index in the target table, if a valid equivalent
index already exists in the partition, it will be attached
to the target table's index, as if ALTER INDEX ATTACH
PARTITION had been executed; otherwise, a corresponding
one will be created. Any invalid indexes on the partition remain
unchanged and should be dropped manually if they are no longer
needed.

Hmm. How about?
For each index in the target table, if a valid equivalent index
already exists in the partition, it will be attached to the target
table's index, as if ALTER INDEX ATTACH PARTITION had been executed;
otherwise, a new corresponding index will be created. Invalid indexes
on the partition are skipped.

In short, I am not sure that there is a need to mention the drop;
that's up to the user to decide what to do and that's a DROP INDEX
thing, not an ALTER thing.
--
Michael

On Wed, Jun 03, 2026 at 04:27:18PM +0900, Michael Paquier wrote:

Hmm. How about?
For each index in the target table, if a valid equivalent index
already exists in the partition, it will be attached to the target
table's index, as if ALTER INDEX ATTACH PARTITION had been executed;
otherwise, a new corresponding index will be created. Invalid indexes
on the partition are skipped.

Took me some time to get back to this one. I have reused my previous
wording, applied it down to v14.
--
Michael