preflight

func CheckTableAbsent ¶ added in v0.2.0

func CheckTableAbsent(ctx context.Context, pool *pgxpool.Pool, schema, table string) (AbsentTarget, error)

CheckTableAbsent verifies that schema.table names no existing relation or standalone type, so a CREATE TABLE at that name has nothing to collide with. When schema is empty the session's creation schema (current_schema()) is resolved first — the schema an unqualified CREATE TABLE would land in — and the proof carries it. The facts come from one catalog snapshot read directly from pg_class and pg_type, which are visible regardless of privileges, so a missing grant can never masquerade as absence; whether the role may create in the schema is a separate privilege check, not this fact check. The proof is time-of-check: nothing locks the name, so a concurrent create can still take it before the CREATE TABLE runs — the create path must still treat a duplicate-name error as a collision; the proof turns the common case into a clean refusal, not a guarantee.

This check is NOT the complement of CheckTable for an unqualified name: CheckTable resolves across the whole search_path (to_regclass), while this check resolves current_schema() only — the one schema an unqualified CREATE TABLE lands in. A table in a later search_path schema makes both checks succeed for the same arguments: CheckTable finds it, and this check correctly reports the creation schema free. A caller deciding between create and alter on that pairing would create a new table that shadows the one the user meant — so such a caller must pass an explicit schema, where the two checks share one namespace and are true inverses.

func CheckCreatePrivileges ¶ added in v0.2.0

func CheckCreatePrivileges(ctx context.Context, pool *pgxpool.Pool, schema string) (CreationRole, error)

CheckCreatePrivileges verifies the connected role can create a table in the schema (the session's creation schema, current_schema(), when schema is empty): CONNECT on the database, USAGE and CREATE on the schema. A missing grant is a *PrivilegeError naming the exact statement that would satisfy it — the grantee is the connected role itself, because a table that does not exist yet has no owning role to inherit from. On success it returns the CreationRole proof.

func CheckCreatePrivilegesAs ¶ added in v0.3.3

func CheckCreatePrivilegesAs(ctx context.Context, pool *pgxpool.Pool, schema, owner string) (CreationRole, error)

CheckCreatePrivilegesAs verifies creation access for owner. When owner is empty, creation remains under the connected role. Otherwise the connected role must be able to SET ROLE to owner, and owner must hold schema access.

SET ROLE consults membership, not inheritance: pg_has_role(..., 'MEMBER') is the predicate on every supported version, and PostgreSQL 16 adds the SET membership option as a second, narrower gate. A non-inheriting member can assume the owner and is admitted; the USAGE mode — whether the owner's privileges are already available without SET ROLE — is not what the mechanism needs, and a refusal keyed on it could not be cleared by the GRANT it prints.

func LookupOwnedRelationNames ¶ added in v0.3.1

func LookupOwnedRelationNames(ctx context.Context, pool *pgxpool.Pool, schema, table string) (OwnedRelationNames, error)

LookupOwnedRelationNames reads the relation names owned by an ordinary or partitioned table so a caller can verify them after a create step. Schema must be explicit because the caller must inspect the exact schema covered by its earlier absence proof rather than resolve a possibly different search_path target. The read excludes standalone indexes, whose own create steps report duplicate-name SQLSTATEs; the table itself, whose name is covered by the caller's absence proof; and the indexes a foreign key borrows from its referenced table, which belong to that table.

func PartitionRefusalCauses ¶ added in v0.3.2

func PartitionRefusalCauses() []PartitionRefusalCause

PartitionRefusalCauses returns the closed set of partitioned-parent refusal causes, so documentation and consumers can enumerate them instead of maintaining their own list.

func RefusesPartitionedParent ¶

func RefusesPartitionedParent(serverMajor int, execSQL []string) (PartitionRefusalCause, error)

RefusesPartitionedParent reports the cause that makes steps unsupported on a partitioned parent, or the zero value when they are supported. It is the shared static policy used by preflight, plan reporting, and executor admission.

func CheckTable ¶

func CheckTable(ctx context.Context, pool *pgxpool.Pool, schema, table string, limitBytes int64) (PreflightedTable, error)

CheckTable verifies that schema.table (search_path when schema is empty) exists, is an ordinary or partitioned table, and is at most limitBytes on disk. Above the limit it returns a *SizeError; on success it returns the PreflightedTable proof.

The unqualified lookup is search_path-wide (to_regclass), so success does not mean the name is occupied in the session's creation schema: a table in a later search_path schema satisfies this check while CheckTableAbsent — which resolves current_schema() only — still proves the creation schema free for the same name. The two checks are inverses only when the caller passes an explicit schema.

func CheckPrivileges ¶

func CheckPrivileges(ctx context.Context, pool *pgxpool.Pool, schema, table string, req Requirement) (PrivilegedRole, error)

CheckPrivileges verifies the connected role holds the access the requirement needs against schema.table (search_path resolution when schema is empty), per the tiered contract in docs/engine-role.md. A missing requirement is a *PrivilegeError naming the exact statement that would satisfy it; on success it returns the PrivilegedRole proof.

It runs before CheckTable in the preflight order: a role that cannot see the target would otherwise report "table not found" and mask the real cause.

func LookupTargetFacts ¶

func LookupTargetFacts(ctx context.Context, pool *pgxpool.Pool, schema, table string) (TargetFacts, error)

LookupTargetFacts verifies that the target is an ordinary or partitioned table and returns its relation kind and server major in one catalog query.

func RequiredTier ¶

func RequiredTier(execSQL []string) (Tier, error)

RequiredTier derives the engine-role tier a routed change's exec SQL needs: an in-place ALTER TABLE step is owner-gated (TierAlterInPlace), and any step that builds a new index — every CREATE INDEX, and the ALTER TABLE shapes that build one as a side effect — additionally needs CREATE on the schema (TierIndexBuild), so the requirement is the most demanding step's tier — the ladder check covers every rung below it. The mapping from step shape to required access lives here, next to Tier and CheckPrivileges, so every consumer of the routed plan derives the same answer. A step shape the engine does not execute fails closed here, before anything runs.

A CREATE TABLE step derives the off-ladder TierCreateTable — the greenfield create plan's shape: one CREATE TABLE plus CREATE INDEX steps on the table it creates, checked by CheckCreatePrivileges, never by CheckPrivileges, whose ladder states facts about an existing table. A set that mixes CREATE TABLE with ALTER TABLE fails closed: the off-ladder tier proves creation access only and cannot vouch for the ladder rungs an alter on an existing table needs — and no front door produces such a set.