Skip to content

docs+lint: safer forms are not semantic equivalents - #13

Open
Kiran01bm wants to merge 1 commit into
kiran01bm/p2-5-linterfrom
kiran01bm/safer-form-wording
Open

docs+lint: safer forms are not semantic equivalents#13
Kiran01bm wants to merge 1 commit into
kiran01bm/p2-5-linterfrom
kiran01bm/safer-form-wording

Conversation

@Kiran01bm

Copy link
Copy Markdown
Collaborator

Summary

CREATE INDEX and CREATE INDEX CONCURRENTLY converge on the same declared end state but
are not semantic equivalents — different locking, transactionality, and failure modes.
This PR sweeps docs, API comments, and CLI output so every safer-rewrite recommendation
reads as an advisory safer form the engine owns executing, never as an equivalent or an
instruction to run manually. No behavior change.

What

  • docs/design-principles.md, docs/high-level-design.md, docs/low-level-design.md:
    replace "native equivalent" / "safer equivalent" with "safer native form" and state the
    operational differences (a failed CONCURRENTLY build leaves an INVALID index the
    executor must detect via pg_index.indisvalid and recover); the HLD advisory diagram now
    says safer form: instead of run instead:.
  • pkg/planner (Decision.SaferSQL) and pkg/lint (CodeBlockingIdiom,
    Finding.Suggestion) doc comments carry the same caveat.
  • CLI output: lint prints safer form (not equivalent — see docs/postgres-online-ddl-reference.md); diff dry-run prints safer form the engine would run (not equivalent — …) instead of the engine would run instead:.

Why

A recommendation that prints "run instead: CREATE INDEX CONCURRENTLY …" invites an operator
to paste it into psql — bypassing the engine's execution-time guards (invalid-index
detection and recovery) while implying identical semantics. The distinction is declarative
vs. operational: from a desired-state diff standpoint the end state is identical
(CONCURRENTLY is not catalog state), but the execution paths fail differently, and only
the engine owns the recovery. Wording everywhere now matches the execution-safety model in
docs/postgres-online-ddl-reference.md.

CREATE INDEX and CREATE INDEX CONCURRENTLY converge on the same
declared end state but differ operationally: locking, transactionality,
and failure modes (a failed CONCURRENTLY build leaves an INVALID index
the executor must detect via pg_index.indisvalid and recover). Reword
docs, API comments, and CLI output so recommendations read as advisory
safer forms the engine owns executing, never as equivalents or
instructions to run manually.
@Kiran01bm
Kiran01bm marked this pull request as ready for review August 6, 2026 10:25
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant