docs: engine-role provisioning contract — tiered access for schema changes - #24
Merged
Conversation
…anges PostgreSQL DDL is owner-gated with no grantable ALTER privilege, so an engine running changes against tables it does not own needs owning-role membership, not the owner's identity. Documents the verified tier model (membership alone for in-place ALTER; schema CREATE additionally for index builds; SET ROLE for owner-correct shadow objects; replication access for CDC), the provisioning grants, and what the role must not have. Preflight refusals will name the missing GRANT and point here.
Kiran01bm
marked this pull request as ready for review
August 11, 2026 21:37
Kiran01bm
requested review from
JashLal,
aparajon,
eeSeeGee,
jayjanssen,
jemiahw and
morgo
as code owners
August 11, 2026 21:37
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
morgo
approved these changes
Aug 11, 2026
…-contract * origin/main: extend app-breaking rename classification to table renames classify column renames as app-breaking, steer to expand/contract Add pkg/executor native CREATE INDEX CONCURRENTLY with fail-closed recovery # Conflicts: # docs/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the provisioning contract for the engine role — the PostgreSQL user pg-sprite connects as — answering precisely what minimum access is needed to run schema changes against tables the engine does not own. Prompted by real integration targets where DDL is owned by application-specific roles (non-standard owners, partitioned tables) rather than the connecting user.
What
docs/engine-role.md: the tiered access contract — Tier 0 connect/resolve, Tier 1 in-placeALTER TABLEvia owning-role membership, Tier 2 index builds (additionally schemaCREATE), Tier 3 copy-and-swap (SET ROLE-capable membership + replication access for CDC), Tier 4 planner scratch database. Includes the provisioningGRANTs, the PostgreSQL 16SET/INHERITmembership caveats, and an explicit "must not have" list (no superuser, nords_superuser, no app login, no ownership transfer).docs/low-level-design.md,docs/schemabot-integration.md,docs/README.md: cross-links so preflight refusals and the SchemaBot adapter point at one authoritative page.Why
PostgreSQL has no grantable
ALTERprivilege —ALTER TABLE,CREATE INDEX, and the rename-swap are owner-gated, and the only non-superuser mechanism is owning-role membership. Without a written contract, every new target becomes an ad-hoc credential negotiation and a missing grant surfaces as a mid-change failure instead of a plan-time refusal. Every claim here was verified against a live PostgreSQL 16 server (including the non-obvious one: membership alone suffices forALTER TABLEbut index builds are refused without schemaCREATE). Preflight enforcement of these tiers lands separately; this page is the target its typed refusals will point to.