@rebasepro/server-postgres 0.12.1-canary.gf5f1d39 → 0.13.0

package/dist/schema/ensure-collection-policies.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Applying a bundle's RLS policies to a database at boot, idempotently.
+ *
+ * ## Why this exists
+ *
+ * {@link ensureCollectionTables} creates the collection *tables* a managed
+ * runtime boots against, but a table with row-level security disabled and no
+ * policies is not servable: authenticated requests run as the restricted
+ * `rebase_user` role, so a read with no `SELECT` policy returns nothing (a
+ * public collection answered 401) and a write with no `INSERT`/`UPDATE` policy
+ * is denied. The policies live in the collections' `securityRules`; nothing at
+ * boot applied them. `rebase db push` does — but it drives Atlas against a
+ * local `DATABASE_URL`, and a managed tenant's database is reachable only from
+ * inside the cluster, by the runtime that is already connected to it. So the
+ * runtime is the only thing that *can* apply them, and this is where it does.
+ *
+ * ## Why this is safe to run on every boot
+ *
+ * Every statement is idempotent: `ENABLE ROW LEVEL SECURITY` is a no-op once
+ * enabled, and each policy is a `DROP POLICY IF EXISTS` immediately followed by
+ * a `CREATE POLICY`, so re-applying asserts exactly the declared state. It adds
+ * and replaces; it never drops data. (It does not *reconcile* — a policy a
+ * previous push left behind under an old name is not removed here; that stays a
+ * `db push` / `db migrate` concern, alongside destructive schema changes.)
+ *
+ * Unlike table creation, a failure here is not fatal: RLS stays enabled, so a
+ * table whose policies could not be applied fails **closed** (denies) rather
+ * than leaking rows. One collection's policy failing (e.g. a rule that
+ * references a table a real migration has not created yet) must not crash-loop
+ * the whole deployment and take the other collections' working routes down with
+ * it. Failures are reported loudly and per-table so the operator can see
+ * exactly which collection is not yet servable and why.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { type Queryable } from "./ensure-collection-tables";
+export interface PolicyEnsureResult {
+    /** `CREATE POLICY` statements that ran successfully. */
+    policiesApplied: number;
+    /** Tables that had RLS enabled. */
+    tablesSecured: number;
+    /** Declared tables absent from the database — left to a real migration. */
+    skipped: {
+        table: string;
+        reason: string;
+    }[];
+    /** Tables whose RLS could not be fully applied (fail closed). */
+    failures: {
+        table: string;
+        error: string;
+    }[];
+}
+/**
+ * Bring the declared collections' RLS policies up to date. Returns what it did.
+ *
+ * Only tables that already exist are touched: the boot-time table creator runs
+ * first, so anything still missing is a table this additive path is not allowed
+ * to create (a junction, or a relation left to a migration). Enabling RLS on a
+ * non-existent table would error, so those are recorded as skipped, not failed.
+ */
+export declare function ensureCollectionPolicies(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<PolicyEnsureResult>;

package/dist/schema/ensure-collection-tables.d.ts

@@ -46,9 +46,17 @@ export interface ExistingSchema {
     tables: Map<string, Set<string>>;
     /** `schema.typename` of every enum type that already exists. */
     enums: Set<string>;
+    /**
+     * `schema.table.constraint` of every constraint that already exists.
+     *
+     * Optional so a caller that only cares about tables can still build one by
+     * hand; absent is read as "none known", which at worst re-attempts a
+     * constraint that then fails harmlessly as a duplicate.
+     */
+    constraints?: Set<string>;
 }
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column";
+    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -57,6 +65,40 @@ export interface EnsurePlan {
     actions: EnsureAction[];
     /** Every statement, in dependency order. Empty when the schema is current. */
     statements: string[];
+    /**
+     * Relation columns this plan is about to create where the table already
+     * carries the same column under its pre-singularization name.
+     *
+     * The reason this is reported rather than silently handled: the ensure is
+     * additive, so it would add `category_id` beside a populated
+     * `categorie_id` and the relation would then read the new, empty one. No
+     * statement fails, no table is missing, and the only symptom is relations
+     * resolving to nothing — which is indistinguishable from having no data.
+     */
+    legacyForeignKeys: LegacyForeignKey[];
+}
+/** A relation column whose old and new spellings both plausibly apply. */
+export interface LegacyForeignKey {
+    /** `schema.table`. */
+    table: string;
+    /** The name the current rule derives, and what this plan would create. */
+    expected: string;
+    /** The name the old rule derived, which the table already has. */
+    legacy: string;
+}
+export interface EnsureOutcome extends EnsurePlan {
+    /**
+     * Constraints that could not be added — always non-fatal.
+     *
+     * A foreign key can only fail on data that already violates it, and the
+     * column it would police exists either way, so the collection still serves.
+     * Refusing to boot over one would turn a pre-existing data problem into an
+     * outage. Reported loudly instead.
+     */
+    failures: {
+        target: string;
+        error: string;
+    }[];
 }
 /**
  * Decide what to add. Pure — the caller supplies what exists and runs the result.
@@ -76,4 +118,4 @@ export declare function readExistingSchema(client: Queryable, schemas: string[])
  * cannot be added, say) should not roll back the tables that were created fine.
  * The error is surfaced with the statement that caused it.
  */
-export declare function ensureCollectionTables(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<EnsurePlan>;
+export declare function ensureCollectionTables(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<EnsureOutcome>;

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -1,8 +1,142 @@
-import { CollectionConfig, Property } from "@rebasepro/types";
+import { CollectionConfig, Property, SecurityRule } from "@rebasepro/types";
 export declare const resolveColumnName: (propName: string, prop?: Property | null) => string;
+export declare const getPrimaryKeyProp: (collection: CollectionConfig) => {
+    name: string;
+    type: "string" | "number";
+    isUuid: boolean;
+};
+export declare const isNumericId: (collection: CollectionConfig) => boolean;
+export declare const getPrimaryKeyName: (collection: CollectionConfig) => string;
 export declare const isIdProperty: (propName: string, prop: Property, collection: CollectionConfig) => boolean;
+type ResolveCollection = (slug: string) => CollectionConfig | undefined;
+/**
+ * The individual SQL statements a single security rule compiles to: a
+ * `DROP POLICY IF EXISTS` / `CREATE POLICY` pair per operation, each a complete
+ * statement (terminated by `;`, no trailing newline).
+ *
+ * This is the primitive the boot-time RLS applier runs one statement at a time
+ * (the runtime's DB handle speaks the extended query protocol, which forbids
+ * multiple commands in one execute), while `db push` writes the joined string.
+ */
+export declare const generatePolicyStatements: (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection) => string[];
+/**
+ * Single-quote escaping for a SQL string literal (PostgreSQL doubles the
+ * quote). Enum labels come straight from user-authored collection config, so a
+ * label like `it's` closes the literal early and the whole generated file stops
+ * parsing at the `CREATE TYPE`. Lives here rather than next to its other caller
+ * because ensure-collection-tables already imports from this module — the
+ * reverse would be a cycle.
+ */
+export declare const quoteSqlLiteral: (value: string) => string;
 export declare const getSqlColumnType: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string;
 export declare const generatePostgresDdl: (collections: CollectionConfig[], options?: {
     includePolicies?: boolean;
 }) => Promise<string>;
+/** The RLS statements one declared collection's table needs, ready to run. */
+/**
+ * A foreign key, as both its parts and the statement that creates it.
+ *
+ * `ALTER TABLE … ADD CONSTRAINT` has no `IF NOT EXISTS`, so a caller applying
+ * these has to skip by name — hence the name is a field and not only a substring
+ * of the SQL.
+ */
+export interface ForeignKeyPlan {
+    constraintName: string;
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    targetSchema: string;
+    targetTable: string;
+    targetColumn: string;
+    sql: string;
+}
+/** A column a `relation` or `reference` property owns on its own table. */
+export interface RelationalColumnPlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    /** Postgres type, exactly as the DDL generator declares it. */
+    type: string;
+    /** Absent when the target collection is not part of this bundle. */
+    foreignKey?: ForeignKeyPlan;
+    /**
+     * What this column would have been called before `generateForeignKeyName`
+     * learned to singularize — set only when the two differ and the column name
+     * is the derived default rather than one the author wrote.
+     *
+     * Carried so the boot-time ensure can notice a database provisioned under
+     * the old rule. It is never used to name anything.
+     */
+    legacyColumn?: string;
+}
+/** The table behind a many-to-many `through` relation. */
+export interface JunctionTablePlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    columns: {
+        name: string;
+        type: string;
+        legacyName?: string;
+    }[];
+    /** Both endpoint columns plus the composite primary key. */
+    createTable: string;
+    foreignKeys: ForeignKeyPlan[];
+}
+/**
+ * The FK columns the declared collections own — one entry per `relation`
+ * (`belongsTo` side) or `reference` property.
+ *
+ * Split out of {@link generatePostgresDdl} so the boot-time schema ensure can
+ * create the same columns with the same names, types and constraints. Before
+ * this it skipped them outright, which was survivable only because `db push`
+ * always followed; on a managed tenant nothing follows, so a table arrived
+ * without the column its own collection reads and wrote 400 on every insert.
+ *
+ * A relation whose target is not in the bundle yields no column at all (the
+ * generator returns early on an unresolvable target); a `reference` whose target
+ * is unknown yields the column without a constraint. Both mirror the generator
+ * exactly — a divergence here is a schema fork between boot and `db push`.
+ */
+export declare const planRelationalColumns: (collections: CollectionConfig[]) => RelationalColumnPlan[];
+/**
+ * The junction tables a bundle's many-to-many relations imply.
+ *
+ * Derived from {@link resolveJunctionSpecs}, the same source the junction RLS
+ * comes from, so a table created here always has policies planned for it — a
+ * junction with row-level security left off is readable and writable by every
+ * signed-in user, which is why the two must ship together.
+ */
+export declare const planJunctionTables: (collections: CollectionConfig[]) => JunctionTablePlan[];
+export interface CollectionPolicyPlan {
+    /** The table's schema (e.g. `public`, `rebase`). */
+    schema: string;
+    /** The bare table name, no schema prefix. */
+    table: string;
+    /** `schema.table` — matches the keys `readExistingSchema` returns. */
+    qualified: string;
+    /** `ALTER TABLE … ENABLE ROW LEVEL SECURITY;` — locked by default. */
+    enableRls: string;
+    /** `DROP POLICY IF EXISTS` / `CREATE POLICY` statements, in order. */
+    policyStatements: string[];
+}
+/**
+ * The per-table RLS plan for the *declared* collections, as executable
+ * statements — what the managed runtime applies at boot so a freshly
+ * provisioned tenant database serves data instead of 401ing every read.
+ *
+ * Mirrors {@link generatePostgresPoliciesDdl} exactly (same
+ * `generatePolicyStatements`, same enable-RLS, same effective rules, same
+ * derived junction rules), so boot and `db push` produce identical policies from
+ * identical collections.
+ *
+ * Junction tables are included, and have to be: boot creates them now
+ * ({@link planJunctionTables}), and a junction with RLS left off is readable and
+ * writable by every signed-in user. A junction whose table is still absent is
+ * skipped by the applier, not planned away here.
+ */
+export declare const planCollectionPolicies: (collections: CollectionConfig[]) => CollectionPolicyPlan[];
 export declare const generatePostgresPoliciesDdl: (collections: CollectionConfig[]) => string;
+export {};

package/dist/schema/introspect-db-constraints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Reading validation rules out of CHECK constraints.
+ *
+ * A CHECK constraint is the schema author stating a rule the database already
+ * enforces. Introspection has never read them, so a generated form let the user
+ * type a value the database was always going to reject — the rule was written
+ * down, in the schema, and the UI asked anyway.
+ *
+ * Everything here parses the *normalized* text `pg_get_constraintdef` produces,
+ * not what the author typed: Postgres re-renders the expression from its parse
+ * tree, so `CHECK (price > 0)` on a `numeric` column always comes back as
+ * `CHECK ((price > (0)::numeric))`. That normalization is what makes a
+ * string-level parser tractable — the input is generated, and the shapes are
+ * few.
+ *
+ * Constraints this cannot read are skipped in full. A partially-understood
+ * constraint is worse than an unread one: it would produce validation that
+ * *narrows* differently from the database, so a value the UI accepts still
+ * fails on write, or — worse — a value the database allows is refused in the
+ * form with no way to see why.
+ *
+ * Pure module: no I/O, no logging.
+ */
+import type { CheckConstraintRow } from "./introspect-db-logic";
+/** What a table's CHECK constraints say about one column. */
+export interface ColumnCheckFacts {
+    /** Allowed values, from `IN (…)` / `= ANY (ARRAY[…])` / `= 'literal'`. */
+    enumValues?: string[];
+    /** `x >= n` */
+    min?: number;
+    /** `x <= n` */
+    max?: number;
+    /** `x > n` */
+    moreThan?: number;
+    /** `x < n` */
+    lessThan?: number;
+    /** `length(x) >= n` */
+    lengthMin?: number;
+    /** `length(x) <= n` */
+    lengthMax?: number;
+}
+/** Per-table, per-column facts. */
+export type CheckFactsByTable = Map<string, Map<string, ColumnCheckFacts>>;
+/** Removes one layer of wrapping parentheses, repeatedly, when balanced. */
+export declare function unwrapParens(input: string): string;
+/** Drops trailing `::type` casts, including array and quoted forms. */
+export declare function stripCasts(input: string): string;
+/**
+ * Reads one constraint definition into per-column facts.
+ *
+ * Returns an empty map for anything not understood — including a constraint
+ * that is understood but spans two columns (`start_date < end_date`), which no
+ * per-property validation rule can express.
+ */
+export declare function parseCheckDefinition(definition: string): Map<string, ColumnCheckFacts>;
+/** Merges every readable CHECK in the schema into per-table, per-column facts. */
+export declare function parseCheckConstraints(rows: CheckConstraintRow[]): CheckFactsByTable;

package/dist/schema/introspect-db-logic.d.ts

@@ -1,5 +1,10 @@
+import { mapPgType } from "./introspect-db-types";
+import type { CheckFactsByTable } from "./introspect-db-constraints";
+import type { TableClassification } from "./introspect-db-structure";
 export interface TableRow {
     table_name: string;
+    /** True for the parent of a partitioned table (`relkind = 'p'`). */
+    is_partitioned?: boolean;
 }
 export interface TableColumn {
     table_name: string;
@@ -9,6 +14,18 @@ export interface TableColumn {
     is_nullable: string;
     column_default: string | null;
     atttypmod: number | null;
+    /** 1-based position in the table, as declared. */
+    ordinal_position?: number;
+    /** `"ALWAYS"` for a generated column, `"NEVER"` otherwise. */
+    is_generated?: string;
+    /** `"YES"` for an identity column. */
+    is_identity?: string;
+    /** `"ALWAYS"` or `"BY DEFAULT"` on an identity column. */
+    identity_generation?: string | null;
+    /** The declared `varchar(n)` / `char(n)` bound, if any. */
+    character_maximum_length?: number | null;
+    numeric_precision?: number | null;
+    numeric_scale?: number | null;
 }
 export interface EnumValue {
     enum_name: string;
@@ -24,6 +41,53 @@ export interface ForeignKeyRow {
     column_name: string;
     foreign_table_name: string;
     foreign_column_name: string;
+    /** Name of the FK constraint — the only way to tell composite keys apart. */
+    constraint_name?: string;
+    /** 1-based position of this column within its constraint. */
+    ordinal?: number;
+    /** `"CASCADE"`, `"RESTRICT"`, `"SET NULL"`, `"SET DEFAULT"`, `"NO ACTION"`. */
+    delete_rule?: string;
+}
+/** A unique constraint or unique index, as an ordered column list. */
+export interface UniqueConstraintRow {
+    table_name: string;
+    constraint_name: string;
+    column_names: string[];
+}
+/** A CHECK constraint, as `pg_get_constraintdef` renders it. */
+export interface CheckConstraintRow {
+    table_name: string;
+    constraint_name: string;
+    definition: string;
+}
+/** A `COMMENT ON TABLE` (null `column_name`) or `COMMENT ON COLUMN`. */
+export interface CommentRow {
+    table_name: string;
+    column_name: string | null;
+    comment: string;
+}
+/**
+ * Everything one introspection run reads from the database.
+ *
+ * Passed around as one value so a new signal means a new field here rather than
+ * a new parameter on every function between the query and the generator — the
+ * shape `generateCollectionFile` had grown to seven positional arguments by.
+ */
+export interface SchemaMetadata {
+    schema: string;
+    tables: TableRow[];
+    columns: TableColumn[];
+    enumValues: EnumValue[];
+    pks: PrimaryKeyRow[];
+    fks: ForeignKeyRow[];
+    uniques: UniqueConstraintRow[];
+    checks: CheckConstraintRow[];
+    comments: CommentRow[];
+    /**
+     * Row counts for the tables that needed one, capped — see `countRowsUpTo`.
+     * Absent for every table introspection never had a reason to count.
+     */
+    rowCounts: Record<string, number>;
 }
 export interface TableMeta {
     name: string;
@@ -38,12 +102,23 @@ export declare function singularize(word: string): string;
  */
 export declare function toCollectionVarName(tableName: string): string;
 export declare function getIconForTable(tableName: string): string;
-/**
- * Map a PostgreSQL data type to a Rebase property type.
- */
-export declare function mapPgType(dataType: string): string;
+export { mapPgType };
 export declare function buildEnumMap(enumValues: EnumValue[]): Map<string, string[]>;
 export declare function buildTablesMap(tables: TableRow[], columns: TableColumn[], pks: PrimaryKeyRow[], fks: ForeignKeyRow[]): Map<string, TableMeta>;
+/**
+ * Join tables, identified by column name.
+ *
+ * Superseded for the CLI by `classifyTables` in `./introspect-db-structure`,
+ * which asks the database instead: two single-column keys, unique together, no
+ * payload column, nothing referencing the table. This rule folds away
+ * `northwind.order_details` — which has the key shape and carries unit price,
+ * quantity and discount — because it recognises `id`, `created_at` and
+ * `updated_at` by name and calls everything else a foreign key.
+ *
+ * Still used by `./introspect-runtime`, which builds collections in memory from
+ * a narrower set of catalog queries and has no unique-constraint or row-count
+ * data to reason with.
+ */
 export declare function identifyJoinTables(tablesMap: Map<string, TableMeta>): Set<string>;
 /**
  * Property metadata used to compute display priority.
@@ -93,11 +168,25 @@ export interface GeneratedFile {
     fileName: string;
     content: string;
 }
+/**
+ * The structural analysis a run can hand the generator.
+ *
+ * Optional in full, and the generator degrades to exactly its previous output
+ * without it. That is not politeness towards old callers: three existing test
+ * suites and the `rebase init` scaffold path build a `TableMeta` by hand and
+ * have no database to read constraints or row counts from, and they must keep
+ * producing a valid collection.
+ */
+export interface GenerationContext {
+    metadata?: SchemaMetadata;
+    classifications?: Map<string, TableClassification>;
+    checkFacts?: CheckFactsByTable;
+}
 /**
  * Generate the full TypeScript file content for a single collection.
  * Pure function — no I/O.
  */
-export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[]): string;
+export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[], context?: GenerationContext): string;
 /**
  * Generate the content for an index.ts file that re-exports all collections.
  */

package/dist/schema/introspect-db-queries.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The catalog queries introspection runs, and the shape they produce.
+ *
+ * These live apart from {@link ./introspect-db.ts} (the CLI entry point) on
+ * purpose: the fixture-capture script and the live e2e read a database through
+ * this module too, so what the tests see is what the CLI sees. A query that
+ * only exists inside the CLI's `main()` can only be tested by running the CLI.
+ *
+ * No side effects beyond `SELECT`. Introspection reads a database it does not
+ * own — it must never `ANALYZE`, create a temp table, or otherwise write.
+ */
+import type { SchemaMetadata } from "./introspect-db-logic";
+/** The subset of `pg.Client` this module needs, so tests can pass a fake. */
+export interface QueryableClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Base tables, excluding partitions.
+ *
+ * `relispartition` is the reason this reads `pg_class` rather than
+ * `information_schema.tables`, which reports every partition as a base table of
+ * its own. Pagila partitions `payment` by month; introspected through
+ * information_schema it yields `payment` plus 26 near-identical
+ * `payment_p2022_*` collections, each with its own nav entry.
+ *
+ * `relkind = 'p'` (the partitioned parent) is included and `'r'` partitions are
+ * dropped, which is the right way round: the parent is the queryable table.
+ */
+export declare const TABLES_QUERY = "\n    SELECT c.relname AS table_name,\n           c.relkind = 'p' AS is_partitioned\n    FROM pg_class c\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE n.nspname = $1\n      AND c.relkind IN ('r', 'p')\n      AND NOT c.relispartition\n      AND c.relname NOT LIKE 'drizzle_%'\n      AND c.relname NOT LIKE 'rebase_%'\n    ORDER BY c.relname\n";
+/**
+ * Columns, with the catalog facts that say a column is not the user's to edit.
+ *
+ * `is_generated`/`is_identity` are read for that reason: a generated column
+ * rejects any write, so a form that offers it is offering a field that always
+ * errors. `character_maximum_length` is the declared `varchar(n)` bound —
+ * already enforced by the database, and free to surface as validation.
+ */
+export declare const COLUMNS_QUERY = "\n    SELECT\n        c.table_name,\n        c.column_name,\n        c.data_type,\n        c.udt_name,\n        c.is_nullable,\n        c.column_default,\n        c.ordinal_position,\n        c.is_generated,\n        c.is_identity,\n        c.identity_generation,\n        c.character_maximum_length,\n        c.numeric_precision,\n        c.numeric_scale,\n        (SELECT a.atttypmod FROM pg_attribute a\n         JOIN pg_class pc ON a.attrelid = pc.oid\n         WHERE pc.relname = c.table_name\n           AND a.attname = c.column_name\n           AND pc.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = c.table_schema)) as atttypmod\n    FROM information_schema.columns c\n    WHERE c.table_schema = $1\n    ORDER BY c.table_name, c.ordinal_position\n";
+export declare const ENUMS_QUERY = "\n    SELECT t.typname AS enum_name,\n           e.enumlabel AS enum_value,\n           e.enumsortorder AS sort_order\n    FROM pg_type t\n    JOIN pg_enum e ON t.oid = e.enumtypid\n    JOIN pg_namespace n ON t.typnamespace = n.oid\n    WHERE n.nspname = $1\n    ORDER BY t.typname, e.enumsortorder\n";
+/**
+ * Primary key columns, in key order.
+ *
+ * `ORDER BY k.ord` matters for composite keys: the position of a column inside
+ * the key is what tells a two-column PK made of two foreign keys apart from an
+ * ordinary composite key, and `= ANY(i.indkey)` (the shape this replaced)
+ * returns catalog order instead.
+ */
+export declare const PRIMARY_KEYS_QUERY = "\n    SELECT t.relname AS table_name,\n           a.attname AS column_name\n    FROM pg_index i\n    JOIN pg_class t ON t.oid = i.indrelid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)\n    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum\n    WHERE i.indisprimary AND n.nspname = $1\n    ORDER BY t.relname, k.ord\n";
+/**
+ * Foreign keys, one row per referencing column, with the delete rule.
+ *
+ * Read from `pg_constraint` rather than through
+ * `information_schema.constraint_column_usage`, which does not preserve the
+ * pairing on a composite foreign key: it reports the cross product of the
+ * constraint's columns, so a two-column FK comes back as four rows, two of them
+ * pairing the wrong columns. `unnest(...) WITH ORDINALITY` on both sides joined
+ * on the ordinal keeps each referencing column with the column it references.
+ *
+ * `confdeltype` is carried because `ON DELETE CASCADE` is the schema author
+ * saying, in the database, that the child cannot outlive the parent — the one
+ * unambiguous declaration of ownership a schema contains.
+ *
+ * Constraints declared on a *partition* are attributed to the partition root,
+ * because that is the table this run generates a collection for. Pagila declares
+ * `payment`'s three foreign keys on each monthly partition and none on the
+ * parent, so reading `pg_constraint` at face value gives the `payment`
+ * collection no relations at all. `pick = 1` then keeps one row per logical key,
+ * preferring the root's own constraint when it has one, so a schema that
+ * declares the key on the parent *and* inherits it onto 26 partitions does not
+ * yield 27 copies of the same relation.
+ */
+export declare const FOREIGN_KEYS_QUERY = "\n    WITH fk AS (\n        SELECT con.oid,\n               con.conname,\n               con.conrelid,\n               con.confrelid,\n               con.conkey,\n               con.confkey,\n               con.confdeltype,\n               COALESCE(pg_partition_root(con.conrelid), con.conrelid) AS root_oid,\n               row_number() OVER (\n                   PARTITION BY COALESCE(pg_partition_root(con.conrelid), con.conrelid),\n                                con.confrelid, con.conkey, con.confkey\n                   ORDER BY (con.conrelid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)) DESC,\n                            con.oid\n               ) AS pick\n        FROM pg_constraint con\n        JOIN pg_namespace n ON n.oid = con.connamespace\n        WHERE con.contype = 'f' AND n.nspname = $1\n    )\n    SELECT root.relname AS table_name,\n           sa.attname AS column_name,\n           tgt.relname AS foreign_table_name,\n           ta.attname AS foreign_column_name,\n           fk.conname AS constraint_name,\n           s.ord::int AS ordinal,\n           CASE fk.confdeltype\n               WHEN 'a' THEN 'NO ACTION'\n               WHEN 'r' THEN 'RESTRICT'\n               WHEN 'c' THEN 'CASCADE'\n               WHEN 'n' THEN 'SET NULL'\n               WHEN 'd' THEN 'SET DEFAULT'\n           END AS delete_rule\n    FROM fk\n    JOIN pg_class root ON root.oid = fk.root_oid\n    JOIN pg_class tgt ON tgt.oid = fk.confrelid\n    CROSS JOIN LATERAL unnest(fk.conkey) WITH ORDINALITY AS s(attnum, ord)\n    JOIN pg_attribute sa ON sa.attrelid = fk.conrelid AND sa.attnum = s.attnum\n    CROSS JOIN LATERAL unnest(fk.confkey) WITH ORDINALITY AS f(attnum, ord)\n    JOIN pg_attribute ta ON ta.attrelid = fk.confrelid AND ta.attnum = f.attnum\n    WHERE fk.pick = 1 AND s.ord = f.ord\n    ORDER BY root.relname, fk.conname, s.ord\n";
+/**
+ * Unique constraints and unique indexes, as ordered column lists.
+ *
+ * Indexes rather than constraints alone, because `CREATE UNIQUE INDEX` and
+ * `ADD CONSTRAINT ... UNIQUE` produce the same guarantee and schemas use both.
+ * Partial indexes (`indpred IS NOT NULL`) are excluded: they promise uniqueness
+ * only over the rows matching their predicate, which is not the promise a
+ * `validation: { unique: true }` field makes.
+ */
+export declare const UNIQUE_CONSTRAINTS_QUERY = "\n    SELECT t.relname AS table_name,\n           ic.relname AS constraint_name,\n           -- ::text, because the driver has no parser for an array of `name`\n           -- and hands back the raw `{a,b}` literal as a string. Every consumer\n           -- here indexes and compares it as an array, and a string of that\n           -- shape fails those silently rather than loudly.\n           array_agg(a.attname::text ORDER BY k.ord) AS column_names\n    FROM pg_index i\n    JOIN pg_class t ON t.oid = i.indrelid\n    JOIN pg_class ic ON ic.oid = i.indexrelid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)\n    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum\n    WHERE i.indisunique\n      AND NOT i.indisprimary\n      AND i.indpred IS NULL\n      AND n.nspname = $1\n      AND NOT t.relispartition\n    GROUP BY t.relname, ic.relname\n    ORDER BY t.relname, ic.relname\n";
+/**
+ * CHECK constraints, as the source text Postgres reproduces them from.
+ *
+ * `pg_get_constraintdef` output is normalized by the server — the parser in
+ * {@link ./introspect-db-constraints.ts} reads that normalized form, not
+ * whatever the author typed.
+ */
+export declare const CHECK_CONSTRAINTS_QUERY = "\n    SELECT DISTINCT\n           root.relname AS table_name,\n           con.conname AS constraint_name,\n           pg_get_constraintdef(con.oid) AS definition\n    FROM pg_constraint con\n    JOIN pg_namespace n ON n.oid = con.connamespace\n    JOIN pg_class root ON root.oid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)\n    WHERE con.contype = 'c'\n      AND n.nspname = $1\n    ORDER BY root.relname, con.conname\n";
+/**
+ * `COMMENT ON TABLE` / `COMMENT ON COLUMN`, which is documentation the author
+ * already wrote and which nothing downstream has ever read.
+ */
+export declare const COMMENTS_QUERY = "\n    SELECT t.relname AS table_name,\n           a.attname AS column_name,\n           d.description AS comment\n    FROM pg_description d\n    JOIN pg_class t ON t.oid = d.objoid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = d.objsubid\n    WHERE n.nspname = $1\n      AND t.relkind IN ('r', 'p')\n      AND (d.objsubid = 0 OR a.attname IS NOT NULL)\n    ORDER BY t.relname, d.objsubid\n";
+/**
+ * Counts a table's rows, stopping once the answer can only be "more than
+ * `limit`".
+ *
+ * Introspection asks this to tell a small reference table from a table that
+ * merely looks like one (see `classifyTables`). `reltuples` would answer for
+ * free but lies on a table that has never been analyzed — which is every table
+ * in a database restored from a dump, i.e. exactly the case introspection meets
+ * — and reports -1 there rather than an error, so the lie is silent.
+ *
+ * The subquery's LIMIT caps the work at `limit + 1` rows however large the
+ * table is, so this stays cheap on a table with a billion rows.
+ */
+export declare function countRowsUpTo(client: QueryableClient, schema: string, table: string, limit: number): Promise<number>;
+/**
+ * Reads everything the generator needs, in one pass.
+ *
+ * `rowCounts` is deliberately absent here: it costs a query per table and only
+ * a handful of tables can possibly need it. The caller fills it in for the
+ * candidates `lookupCandidates()` names.
+ */
+export declare function readSchemaMetadata(client: QueryableClient, schema: string): Promise<SchemaMetadata>;