@rebasepro/server-postgres 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/schema/plan/diff-plan.d.ts

@@ -81,7 +81,83 @@ export interface ExistingSchema {
     columnTypes?: Map<string, string>;
     /** `schema.table.trigger` of every trigger that already exists. */
     triggers?: Set<string>;
+    /**
+     * `schema.name` of every index (any relation of kind `i`/`I`) that already
+     * exists. Absent means unknown, and every index is planned as before —
+     * `IF NOT EXISTS` makes that correct, just not free.
+     */
+    indexes?: Set<string>;
+    /**
+     * `schema.name` of every index whose `pg_index.indisvalid` is false — the
+     * husk a `CREATE INDEX CONCURRENTLY` leaves behind when it is cancelled,
+     * times out, or loses a race with a peer. Such an index is in
+     * {@link indexes} too, maintained on every write and used by no query, and
+     * `IF NOT EXISTS` skips it by name forever. Absent means unknown.
+     */
+    invalidIndexes?: Set<string>;
+    /**
+     * Names of the extensions installed in the database. `CREATE EXTENSION IF
+     * NOT EXISTS` skips by name whatever schema the extension is in, so the name
+     * is the whole test. Absent means unknown.
+     */
+    extensions?: Set<string>;
+    /**
+     * {@link HELPER_FUNCTIONS} as they are in the catalogue: `schema.name(args)`
+     * → {@link describeHelperFunction} of what `CREATE OR REPLACE` would set.
+     * Absent means unknown, and every helper is re-created as before.
+     */
+    functions?: Map<string, string>;
 }
+/**
+ * The functions the plan creates with `CREATE OR REPLACE`, which the catalogue
+ * reader looks up so a boot that finds them unchanged plans nothing.
+ *
+ * A helper missing from this list is not wrong, only re-created on every boot,
+ * which is what all of them were before.
+ */
+export declare const HELPER_FUNCTIONS: readonly string[];
+/**
+ * Everything `CREATE OR REPLACE FUNCTION` sets on a function, as one string.
+ *
+ * Built from the catalogue by the reader and from the statement by
+ * {@link parseHelperFunction}, so the two meet in one shape. It covers every
+ * attribute a `CREATE OR REPLACE` resets — body, language, volatility,
+ * strictness, parallel safety, security, leakproofness, cost and `SET` options —
+ * so a function someone altered by hand (`ALTER FUNCTION … VOLATILE`) still
+ * compares unequal and is re-created, exactly as the unconditional statement
+ * used to re-create it.
+ */
+export interface HelperFunctionFacts {
+    returns: string;
+    language: string;
+    /** `provolatile`: `i`mmutable, `s`table, `v`olatile. */
+    volatility: string;
+    strict: boolean;
+    /** `proparallel`: `s`afe, `r`estricted, `u`nsafe. */
+    parallel: string;
+    securityDefiner: boolean;
+    leakproof: boolean;
+    cost: number;
+    /** Whether the function carries any `SET` options (`proconfig`). */
+    hasConfig: boolean;
+    /** `prosrc`: the text between the dollar quotes, exactly. */
+    body: string;
+}
+export declare const helperFunctionKey: (schema: string, name: string, args: string) => string;
+export declare const describeHelperFunction: (facts: HelperFunctionFacts) => string;
+/**
+ * What a helper's `CREATE OR REPLACE FUNCTION` statement would leave in the
+ * catalogue, or `undefined` for a statement this does not recognise — which is
+ * then planned unconditionally, as every statement was before.
+ *
+ * Only ever given statements this package renders (`searchHelperFunctions`,
+ * `setUpdatedAtFunction`), so a strict pattern is the right tool: anything it
+ * does not match exactly falls back to the safe behaviour.
+ */
+export declare function parseHelperFunction(statement: string): {
+    key: string;
+    definition: string;
+} | undefined;
 /**
  * How far the planner may go in making the database's constraints match the
  * configuration.
@@ -100,9 +176,21 @@ export type ConstraintPolicy = "additive" | "converge";
 export interface DiffOptions {
     /** Defaults to `additive`. See {@link ConstraintPolicy}. */
     constraints?: ConstraintPolicy;
+    /**
+     * Plan every index a table that already exists needs — declared, search
+     * and vector, missing or left INVALID under its name — as a
+     * {@link DeferredIndexBuild} rather than an action, as the derived
+     * foreign-key indexes always are. `ensureCollectionTables` sets it: it
+     * hands them to `buildDeferredIndexes`, which builds them on a connection
+     * of its own with no `statement_timeout`, and drops and rebuilds a husk.
+     *
+     * Absent — the live schema editor, which applies `statements` as text —
+     * they stay `CREATE INDEX CONCURRENTLY IF NOT EXISTS` actions, as before.
+     */
+    deferLiveIndexes?: boolean;
 }
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column" | "create-extension" | "create-function" | "create-index" | "comment-column" | "add-enum-value" | "set-not-null" | "drop-not-null" | "set-default" | "create-trigger";
+    kind: "create-enum" | "create-table" | "enable-rls" | "add-column" | "add-constraint" | "rename-column" | "create-extension" | "create-function" | "create-index" | "comment-column" | "add-enum-value" | "set-not-null" | "drop-not-null" | "set-default" | "create-trigger";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -166,6 +254,42 @@ export interface LegacyForeignKey {
     /** The name the old rule derived, which the table already has. */
     legacy: string;
 }
+/**
+ * An index a table that already exists is missing, or holds INVALID — a
+ * derived foreign-key index always, and under
+ * {@link DiffOptions.deferLiveIndexes} a declared, search or vector one too.
+ *
+ * Not an {@link EnsureAction}, because it must not hold the boot: on a table
+ * with millions of rows `CREATE INDEX CONCURRENTLY` takes minutes, and every
+ * minute of it would be a minute the deployment is not serving. The caller
+ * builds these after the fact — boot in the background once it serves, every
+ * other caller inline after the actions — through `buildDeferredIndexes`. A
+ * {@link unique} one is the exception: it is built before the ensure returns.
+ *
+ * Kept out of {@link EnsurePlan.statements} for the same reason: a caller that
+ * applies statements as text (the live schema editor) may run them inside a
+ * transaction, which `CONCURRENTLY` refuses.
+ */
+export interface DeferredIndexBuild {
+    schema: string;
+    /** Bare table name. */
+    table: string;
+    indexName: string;
+    /** `CREATE [UNIQUE] INDEX CONCURRENTLY IF NOT EXISTS …;` */
+    sql: string;
+    /**
+     * The catalogue already holds an INVALID index under this name, which has
+     * to be dropped before the build — `IF NOT EXISTS` would skip it.
+     */
+    invalid: boolean;
+    /**
+     * A declared `unique: true` index. Not an optimization but the collection
+     * promising two rows cannot share a value, so `ensureCollectionTables`
+     * builds it before it returns — never after the server is serving — and
+     * fails when it cannot, as it did when this was an action. Absent is false.
+     */
+    unique?: boolean;
+}
 export interface EnsurePlan {
     actions: EnsureAction[];
     /** Every statement, in dependency order. Empty when the schema is current. */
@@ -217,5 +341,7 @@ export interface EnsurePlan {
      * exactly once, which is not a decision to take unattended.
      */
     orphanedRequiredColumns: OrphanedRequiredColumn[];
+    /** @see DeferredIndexBuild */
+    deferredIndexes: DeferredIndexBuild[];
 }
 export declare function diffPlanAgainstCatalogue(plan: SchemaPlan, existing: ExistingSchema, options?: DiffOptions): EnsurePlan;

package/dist/schema/plan/plan-schema.d.ts

@@ -12,7 +12,7 @@
  * imported would not be comparable with itself.
  *
  * It **throws** rather than guessing. A configuration no renderer can honour —
- * an empty enum, two `isId` properties, `isId: "cuid"`, an unknown
+ * an empty enum, `isId: "cuid"`, a foreign key into a composite key, an unknown
  * `columnType`, a relation to a collection that is not in the bundle, a
  * `search` block on a collection Postgres does not store — used to fail
  * differently in each of the three emitters, or not at all, and the failure
@@ -65,8 +65,17 @@ export declare const defaultBelongsToOnDelete: (required: boolean | undefined) =
  * One exception: a `serial` key owns a sequence, and a column pointing at it is
  * the plain integer of the same width — `SERIAL` there would give every
  * referencing column a sequence of its own.
+ *
+ * @param via the link asking, named if the collection's key is composite and so
+ *   cannot be pointed at — see `getPrimaryKeyProp`.
+ */
+export declare const primaryKeyPgType: (collection: CollectionConfig, via: string) => PgType;
+/**
+ * The DEFAULT of the implicit `id TEXT PRIMARY KEY` a collection that declares
+ * no key gets: a uuid, as text. The same generator `isId: "uuid"` uses, cast to
+ * the column the key has always been.
  */
-export declare const primaryKeyPgType: (collection: CollectionConfig) => PgType;
+export declare const IMPLICIT_ID_DEFAULT = "gen_random_uuid()::text";
 /**
  * The Postgres type a property's column has.
  *
@@ -79,12 +88,11 @@ export declare const columnPgType: (propName: string, prop: Property, collection
 /**
  * One security rule, compiled to the clauses a policy is made of.
  *
- * The desugaring (`access` / `ownerField` / `roles` / structured condition /
- * raw SQL → `PolicyExpression`) and the SQL compilation are `@rebasepro/common`'s,
- * which is what the client-side evaluator uses too — so the UI, the DDL and the
- * database agree about who can read a row. What lives here is only the shape:
- * which operations a rule expands to, which clauses each operation takes, and
- * the deny-all fallback for a clause that compiled to nothing.
+ * The compilation is `compileRulePolicies` in `@rebasepro/common`, which the
+ * Studio's RLS editor also compares the live database against — so the UI, the
+ * DDL and the database agree about who can read a row. What this adds is only
+ * the planner's bookkeeping: which rule a policy came from, and whether Rebase
+ * injected it.
  */
 export declare const compileSecurityRule: (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection, injected: boolean, ruleKey?: string) => PolicyPlan[];
 export declare function planSchema(allCollections: CollectionConfig[], options?: PlanOptions): SchemaPlan;

package/dist/schema/plan/render-ddl.d.ts

@@ -25,6 +25,12 @@ export declare const renderPgType: (type: PgType) => string;
  * DEFAULT, which is why it is rendered here and not in the DEFAULT slot.
  */
 export declare const renderColumnDefinition: (column: ColumnPlan) => string;
+/**
+ * `PRIMARY KEY ("a", "b")`, the clause a composite key takes inside a
+ * `CREATE TABLE`. Shared by `schema.sql` and boot-ensure's `CREATE TABLE`, so
+ * the two cannot list the columns differently.
+ */
+export declare const renderPrimaryKeyConstraint: (table: Pick<TablePlan, "primaryKey">) => string;
 /**
  * One policy as its `DROP` / `CREATE` pair — each a complete statement.
  *

package/dist/schema/plan/types.d.ts

@@ -200,6 +200,13 @@ export interface ColumnPlan {
     column: string;
     type: PgType;
     nullable: boolean;
+    /**
+     * This column alone is the table's primary key, declared inline on it.
+     *
+     * `false` for a column of a composite key: several inline `PRIMARY KEY`
+     * clauses would be several primary keys, so a composite key is one table
+     * constraint over {@link TablePlan.primaryKey} instead.
+     */
     primaryKey: boolean;
     unique: boolean;
     default?: ColumnDefault;
@@ -273,6 +280,14 @@ export interface PolicyPlan {
      * what `securityRules` reads like — `policies.sql` says so in a comment.
      */
     injected: boolean;
+    /**
+     * Policy names, as Postgres stored them, that this policy replaces — set
+     * only on the first policy of a rule whose per-operation names used to
+     * collide at 63 bytes (see `getPolicySupersededNames`). Rendered as a
+     * `DROP POLICY IF EXISTS` ahead of the policy, so a boot or push swaps the
+     * one truncated survivor for a policy per operation. Absent otherwise.
+     */
+    supersedes?: string[];
 }
 /** A `BEFORE UPDATE` trigger stamping `now()` onto an `on_update` column. */
 export interface TriggerPlan {
@@ -326,7 +341,13 @@ export interface TablePlan {
      */
     declaringSlugs?: string[];
     columns: ColumnPlan[];
-    /** Column names, in order. One entry for a collection, two for a junction. */
+    /**
+     * The primary key's column names, in key order.
+     *
+     * One entry is a key declared inline on its column ({@link ColumnPlan.primaryKey}).
+     * Several — a junction's two endpoints, or a collection marking several
+     * properties `isId` — are rendered as one `PRIMARY KEY (a, b)` constraint.
+     */
     primaryKey: string[];
     /** The declared `indexes:` block, with its frozen names. */
     indexes: CollectionIndexSpec[];
@@ -355,23 +376,35 @@ export interface TablePlan {
  * pair them; the rule that derives it is `sharedRelationName`, which both sides
  * compute independently from the table that owns the column.
  */
-export interface RelationPlan {
+export type RelationPlan = OneRelationPlan | ManyRelationPlan;
+interface RelationPlanBase {
     /** The Drizzle table variable this entry belongs to. */
     tableVar: string;
     /** The key in the relations object. */
     key: string;
-    kind: "one" | "many";
     targetVar: string;
-    /**
-     * Absent only for a `hasOne` inverse, which is the documented FK-less form:
-     * `one(target)` with no config. `one(target, { relationName })` is not a
-     * `RelationConfig` (TS2345) and throws at runtime besides.
-     */
-    relationName?: string;
+    relationName: string;
+}
+/**
+ * A `one()`. Every one names its join — Drizzle has no `one()` paired by
+ * `relationName` alone, and one paired by table is ambiguous as soon as two
+ * links join the same pair of tables.
+ */
+export interface OneRelationPlan extends RelationPlanBase {
+    kind: "one";
     /** Property keys on this table. */
-    fields?: string[];
+    fields: string[];
     /** Property keys on the target table. */
-    references?: string[];
+    references: string[];
+    /**
+     * Set on a `hasOne`, whose `fields` are this table's own key: the target
+     * row may not exist although every column in `fields` is NOT NULL, which
+     * is what Drizzle reads a `one()`'s nullability from.
+     */
+    nullable?: true;
+}
+export interface ManyRelationPlan extends RelationPlanBase {
+    kind: "many";
 }
 export interface PlanOptions {
     /**
@@ -413,3 +446,4 @@ export interface SchemaPlan {
     collections: CollectionConfig[];
     options: PlanOptions;
 }
+export {};

package/dist/schema/push-index-prebuild.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The foreign-key indexes `rebase db push` builds before Atlas plans.
+ *
+ * Rebase derives a btree for every `belongsTo` key and every junction's target
+ * column (15b00afcd). On a table that already exists — every table of a
+ * project upgraded across that release — the index is missing, and a push left
+ * it to Atlas, which builds it inside the push's one transaction: a plain
+ * `CREATE INDEX`, holding writes to the table for the whole build, about 0.4 s
+ * at a million rows and 6 s at ten million. Atlas's own concurrent mode would
+ * run the entire apply outside a transaction, which the push relies on.
+ *
+ * So the push builds those first, `CONCURRENTLY`, with the builder the boot
+ * uses for the same indexes (`deferred-index-build.ts`: one at a time, a lock
+ * budget for getting the table, an INVALID leftover dropped and rebuilt, a
+ * claim shared with booting instances). Atlas then finds them and plans
+ * nothing for them. One it could not build is still Atlas's, as before.
+ *
+ * Only an index whose columns are already there: a column this push adds is
+ * created by Atlas, and its index with it, on a column that holds no values.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { type DeferredIndexBuild } from "./plan/diff-plan.js";
+import { type Queryable } from "./ensure-collection-tables.js";
+/** The derived foreign-key indexes a live table lacks (or holds INVALID) whose columns it already has. */
+export declare function missingForeignKeyIndexes(client: Queryable, collections: CollectionConfig[]): Promise<DeferredIndexBuild[]>;

package/dist/schema/push-legacy-renames.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The relation columns an aged database still holds under the name Rebase
+ * derived before 0.13 (`categorie_id`, `people_id`), for `db push` to rename
+ * before Atlas plans.
+ *
+ * Boot renames them losslessly (`diff-plan.ts`, `renameLegacyColumn`). Push
+ * runs Atlas, which sees only "drop `categorie_id`, add `category_id` NOT
+ * NULL": it listed the links as destructive changes to approve, and with
+ * `--allow-destructive` dropped them. A pipeline that runs only `db push`
+ * could not upgrade an aged database at all. Renaming first — the same
+ * metadata-only statement boot runs — leaves Atlas nothing to plan.
+ */
+import { type CollectionConfig } from "@rebasepro/types";
+import { type LegacyForeignKey } from "./plan/diff-plan.js";
+import { type Queryable } from "./ensure-collection-tables.js";
+export interface LegacyRename extends LegacyForeignKey {
+    /** `ALTER TABLE … RENAME COLUMN …;` */
+    sql: string;
+}
+export declare function legacyForeignKeyRenames(client: Queryable, collections: CollectionConfig[]): Promise<LegacyRename[]>;

package/dist/schema/rls-bootstrap-sql.d.ts

@@ -45,6 +45,21 @@
  * a parser for a problem that does not need one.
  */
 export declare const RLS_BOOTSTRAP_STATEMENTS: readonly string[];
+/**
+ * Whether the `rebase` schema and every RLS helper function are exactly what
+ * {@link RLS_BOOTSTRAP_STATEMENTS} would make them — one catalogue read.
+ *
+ * The boot ran those statements unconditionally, on every boot and on every
+ * source: four `CREATE OR REPLACE FUNCTION`s in a transaction under an
+ * advisory lock. Replacing a function rewrites its `pg_proc` row even when
+ * nothing changed, and every cached plan that inlined it — every plan of every
+ * statement a policy applies to, on every connection — is invalidated by it.
+ * A function that differs in anything `CREATE OR REPLACE` sets (body,
+ * language, volatility, strictness, parallel safety, security, leakproofness,
+ * cost, `SET` options), or is missing, answers `false`, and the statements run
+ * as before.
+ */
+export declare function rlsRuntimeIsCurrent(run: (sql: string) => Promise<Record<string, unknown>[]>): Promise<boolean>;
 /** The same statements as one script, for migration files and raw clients. */
 export declare const RLS_BOOTSTRAP_SQL: string;
 /**