@rebasepro/server-postgres 0.19.1 → 0.19.2-canary.g08eed46

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

@@ -0,0 +1,220 @@
+/**
+ * The additive statements that bring a database up to a {@link SchemaPlan}.
+ *
+ * ## Why additive-only, forever
+ *
+ * This runs unattended, at boot, against a database with customers' data in it,
+ * with no human reading a diff. So it may only ever do things that cannot lose
+ * data: create a missing table, add a missing column, create a missing enum
+ * type, add an enum value, create an index.
+ *
+ * It will **never** drop a table or a column, narrow a type, or alter a
+ * constraint at boot. A removed field leaves its column behind; a renamed field
+ * looks like an addition and the old column stays. That is the correct trade
+ * for an automated path — the alternative is an unattended process that can
+ * silently destroy a column. Destructive changes stay a deliberate,
+ * human-reviewed migration. Because of that, this is safe to run on every boot,
+ * and re-running it is a no-op.
+ *
+ * ## What changed when the planner arrived
+ *
+ * This used to read `Property` itself — its own reading of the type, of
+ * `validation`, of relations, of enums — and disagreed with `db push` about all
+ * of them. The audit found a required `author_id` that was NOT NULL after a
+ * push and nullable after a boot, on the one path with no developer in the
+ * loop. Now it reads the same {@link ColumnPlan} the DDL renderer does, so a
+ * column's type, default, uniqueness and foreign key are decided once. What is
+ * left here is the half that is genuinely this path's own: *what the database
+ * already has*, and which of the planned constraints are safe to apply to it.
+ */
+import type { SchemaPlan } from "./types.js";
+import { type SkippedVectorIndex } from "../vector-index.js";
+import { type ColumnTypeDrift } from "../column-type-drift.js";
+/**
+ * Validation used to run only on the names read back OUT of the catalogue,
+ * which is the direction that cannot hurt anyone: those came from Postgres. The
+ * names going IN — the schema and table a collection declares — were quoted and
+ * concatenated on trust, and quoting is not escaping. A table named
+ * `x" (id int); DROP TABLE users; --` closes the quote and the statement, and
+ * the whole thing runs on the owner connection, which is the one connection in
+ * the system that is exempt from every RLS policy.
+ *
+ * That is only a config file on a self-hosted project, where the person writing
+ * it could run the SQL directly anyway. It is not only a config file where a
+ * collection can be defined over the wire — the live-schema and source editors
+ * both do that — and there the caller is an admin on the app, not an operator
+ * of the database.
+ */
+export declare function assertSafeIdentifier(value: string, what: string): string;
+/** What the database currently has, as the planner needs it. */
+export interface ExistingSchema {
+    /** `schema.table` → set of column names. */
+    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>;
+    /**
+     * `schema.table.column` → that column's comment, for the columns that have
+     * one. This is where a generated search column's fingerprint lives.
+     */
+    columnComments?: Map<string, string>;
+    /** `schema.typename` → its labels, in `enumsortorder`. */
+    enumValues?: Map<string, string[]>;
+    /** `schema.table.column` of every NOT NULL column. */
+    notNullColumns?: Set<string>;
+    /** `schema.table.column` of every column that has a DEFAULT. */
+    columnDefaults?: Set<string>;
+    /** `schema.table` of every table that holds at least one row. */
+    populatedTables?: Set<string>;
+    /**
+     * `schema.table.column` → the type Postgres reports, as `udt_name` (plus a
+     * modifier where one distinguishes two columns of the same family, e.g.
+     * `numeric(10,2)`).
+     */
+    columnTypes?: Map<string, string>;
+    /** `schema.table.trigger` of every trigger that already exists. */
+    triggers?: Set<string>;
+}
+/**
+ * How far the planner may go in making the database's constraints match the
+ * configuration.
+ *
+ * - `additive` — the boot default. Columns, tables, indexes and enum values are
+ *   created; no existing column's constraints are touched. Unattended boots run
+ *   against customer data with nobody reading a diff, and a database adopted by
+ *   introspection legitimately carries NOT NULL on columns the generated
+ *   collection leaves optional (`introspect-db-logic` withholds `required` from
+ *   a column with a default or a trigger behind it). Converging there would
+ *   strip real constraints on first boot.
+ * - `converge` — the live schema editor. Every statement is planned, shown to
+ *   the person making the change, and applied only once they confirm it.
+ */
+export type ConstraintPolicy = "additive" | "converge";
+export interface DiffOptions {
+    /** Defaults to `additive`. See {@link ConstraintPolicy}. */
+    constraints?: ConstraintPolicy;
+}
+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";
+    /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
+    target: string;
+    sql: string;
+}
+/** A NOT NULL column with no default that no property declares. */
+export interface OrphanedRequiredColumn {
+    /** `schema.table`. */
+    table: string;
+    /** The column left behind. */
+    column: string;
+    /** The collection that no longer declares it. */
+    slug: string;
+}
+/** A constraint the configuration asks for that the planner is not applying. */
+export interface WithheldConstraint {
+    /** `schema.table.column`. */
+    target: string;
+    kind: "not-null";
+    /**
+     * Why, in a sentence that names the obstacle rather than the rule. The
+     * reader is looking at a column that is nullable when they asked for
+     * required, and needs to know what to do about it.
+     */
+    reason: string;
+    /** What would make it applicable. */
+    remedy: string;
+}
+/**
+ * A generated search column built from a `search` block that has since changed.
+ *
+ * Reported instead of applied because the two ways to apply it are both worse
+ * than stopping. `ALTER COLUMN … SET EXPRESSION` exists only on PG17+ and
+ * rewrites the table either way; `DROP COLUMN` + `ADD COLUMN` rewrites it under
+ * an ACCESS EXCLUSIVE lock and rebuilds the GIN index. This module runs
+ * unattended against live customer data with nobody reading a diff, so a
+ * multi-minute outage is not a decision it may take on its own.
+ *
+ * Not applying it silently is not an option either: a collection that added a
+ * field, flipped `unaccent` or raised a weight kept indexing the *old* set
+ * forever, and the only symptom was searches returning nothing for content
+ * plainly in the row.
+ */
+export interface SearchColumnDrift {
+    /** `schema.table`. */
+    table: string;
+    column: string;
+    /** The fingerprint recorded on the column. */
+    found: string;
+    /** The fingerprint the current `search` block computes. */
+    expected: string;
+    /** The statements that would rebuild the column, for the operator to run. */
+    rebuild: string[];
+}
+/** 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 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.
+     *
+     * 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.
+     */
+    legacyForeignKeys: LegacyForeignKey[];
+    /** @see SearchColumnDrift */
+    searchDrift: SearchColumnDrift[];
+    /**
+     * Generated search columns that exist but carry no fingerprint — created
+     * before this check existed, or by `search.sql` on an older CLI. The plan
+     * stamps them so the *next* change is detectable.
+     */
+    searchAdopted: {
+        table: string;
+        column: string;
+    }[];
+    /**
+     * Vector columns this plan is deliberately leaving unindexed, because
+     * pgvector cannot build an ANN index that wide. Reported rather than
+     * thrown: the column is valid, storable and searchable.
+     */
+    vectorIndexSkipped: SkippedVectorIndex[];
+    /**
+     * Constraints the configuration asks for that this plan is not applying,
+     * and why. Every one of these was previously withheld in silence.
+     */
+    withheldConstraints: WithheldConstraint[];
+    /**
+     * Columns whose type in the database is in a different family from the one
+     * the collection declares. Reported and never acted on — this is the one
+     * divergence that presents as a *working* deploy.
+     */
+    columnTypeDrift: ColumnTypeDrift[];
+    /**
+     * Columns that are NOT NULL, have no default, and that no property declares
+     * any more — so every insert through the API is rejected for a field the
+     * author cannot name, because they already deleted it. This is what a
+     * **rename** looks like to an additive provisioner. Reported, never acted
+     * on: dropping the column is the right fix roughly always and destructive
+     * exactly once, which is not a decision to take unattended.
+     */
+    orphanedRequiredColumns: OrphanedRequiredColumn[];
+}
+export declare function diffPlanAgainstCatalogue(plan: SchemaPlan, existing: ExistingSchema, options?: DiffOptions): EnsurePlan;

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

@@ -0,0 +1,84 @@
+/**
+ * The only place a `Property` is read for schema purposes.
+ *
+ * Everything that used to `switch (prop.type)` — the Drizzle generator, the DDL
+ * generator, the boot-time ensure — now renders the {@link SchemaPlan} this
+ * produces. See `./types.ts` for why.
+ *
+ * Pure and synchronous. It reads collections and nothing else: no database, no
+ * filesystem, no process-wide registry. The one fact about the world it needs
+ * (which extensions a project's databases gave Rebase leave to install) is
+ * passed in, because a plan that depended on whatever module happened to be
+ * 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
+ * `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
+ * landed at `CREATE TABLE` time on a managed tenant with nobody in the loop.
+ * Here it lands once, with the collection and the property named.
+ */
+import { type CollectionConfig, type Property, type SecurityRule } from "@rebasepro/types";
+import { SET_UPDATED_AT_FN } from "./updated-at-trigger.js";
+import type { PgType, PlanOptions, PolicyPlan, SchemaPlan } from "./types.js";
+type ResolveCollection = (slug: string) => CollectionConfig | undefined;
+/**
+ * Single-quote escaping for a SQL string literal (PostgreSQL doubles the
+ * quote). Enum labels and `defaultValue`s come straight from user-authored
+ * collection config, so a value like `it's` closes the literal early and the
+ * whole generated file stops parsing at that statement.
+ */
+export declare const quoteSqlLiteral: (value: string) => string;
+/**
+ * The `ON DELETE` a foreign key gets when the author did not say.
+ *
+ * One rule for every property that emits one — `belongsTo` relations and
+ * `reference` properties alike. `reference` kept its own `CASCADE` default for
+ * a release after this rule was written, which is exactly the split this
+ * function exists to prevent: two spellings of the same link, two
+ * data-retention behaviours, and only one of them documented.
+ *
+ * An optional link is `SET NULL`: the column can hold NULL, so dropping the
+ * parent leaves the child row with an empty pointer, which is what "optional"
+ * already means.
+ *
+ * A required link is **`RESTRICT`**, not `CASCADE`. `NOT NULL` says the child
+ * cannot exist without a parent; it does not say deleting the parent should
+ * take the child with it. That second claim is a data-retention decision, and
+ * defaulting to it meant `onDelete` — a field nobody has to write — silently
+ * turned every `DELETE FROM authors` into a cascade through posts, comments and
+ * anything else that hung off them.
+ */
+export declare const defaultBelongsToOnDelete: (required: boolean | undefined) => "RESTRICT" | "SET NULL";
+/**
+ * The type a column pointing at this collection's primary key must have — a
+ * junction endpoint, a `belongsTo` foreign key, a `reference`.
+ *
+ * One function because it was three: the ladder was spelled inline in
+ * `generatePostgresDdl`, again in `planJunctionTables` and a third time in the
+ * Drizzle generator.
+ */
+export declare const primaryKeyPgType: (collection: CollectionConfig) => PgType;
+/**
+ * The Postgres type a property's column has.
+ *
+ * Every member of `DataType` has an arm. A type this does not know is a
+ * generator that has not been taught it yet, and it says so — a silent `TEXT`
+ * here is how `geopoint` ended up with a database column, no Drizzle key, and
+ * every write to it discarded with a 201.
+ */
+export declare const columnPgType: (propName: string, prop: Property, collection: CollectionConfig, resolveCollection: ResolveCollection) => PgType;
+/**
+ * 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.
+ */
+export declare const compileSecurityRule: (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection, injected: boolean, ruleKey?: string) => PolicyPlan[];
+export declare function planSchema(allCollections: CollectionConfig[], options?: PlanOptions): SchemaPlan;
+export { SET_UPDATED_AT_FN };

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

@@ -0,0 +1,62 @@
+import type { ColumnPlan, PgType, PolicyPlan, SchemaPlan, TablePlan } from "./types.js";
+/** What `schema.sql` may leave out, because another file owns it. */
+export interface DdlRenderOptions {
+    /** RLS policies. `false` puts them in `policies.sql` alone. */
+    includePolicies?: boolean;
+    /** The search column, its helpers and its index. See `search.sql`. */
+    includeSearch?: boolean;
+    /** The vector columns and their ANN indexes. See `vector.sql`. */
+    includeVector?: boolean;
+}
+/**
+ * A {@link PgType} as Postgres spells it.
+ *
+ * The one place. `getSqlColumnType` and `getDrizzleColumn` each carried their
+ * own ladder and disagreed about `VARCHAR` widths, about `geopoint`, and about
+ * whether an `increment` id honours `columnType`.
+ */
+export declare const renderPgType: (type: PgType) => string;
+/**
+ * Everything after the column name, in one order for every SQL emitter.
+ *
+ * `CREATE TABLE` and `ADD COLUMN` used to assemble this separately, which is
+ * how a required relation column came out `NOT NULL` after `db push` and
+ * nullable after a boot-ensure. `identity` is part of the type rather than a
+ * DEFAULT, which is why it is rendered here and not in the DEFAULT slot.
+ */
+export declare const renderColumnDefinition: (column: ColumnPlan) => string;
+/**
+ * One policy as its `DROP` / `CREATE` pair — each a complete statement.
+ *
+ * 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 renderPolicyStatements: (table: Pick<TablePlan, "schema" | "table">, policy: PolicyPlan) => string[];
+/** `ALTER TABLE … ENABLE ROW LEVEL SECURITY;` — every generated table is locked. */
+export declare const renderEnableRls: (table: Pick<TablePlan, "schema" | "table">) => string;
+export declare function renderPostgresDdl(plan: SchemaPlan, options?: DdlRenderOptions): string;
+export declare function renderPoliciesDdl(plan: SchemaPlan): string;
+export declare function renderSearchDdl(plan: SchemaPlan): string;
+/**
+ * Glob patterns telling Atlas to leave an object alone.
+ *
+ * Fully qualified, `schema.table.object`, matching the include list. The
+ * two-part form is what Atlas wants when the connection URL scopes it to one
+ * schema and is *silently ignored* otherwise: it reads `posts.search_vector` as
+ * a table named `search_vector` in a schema named `posts`, matches nothing, and
+ * reports no error for the pattern that never fired.
+ */
+export declare const searchExcludePatternsOf: (plan: SchemaPlan) => string[];
+export declare function renderVectorDdl(plan: SchemaPlan): string;
+/** @see searchExcludePatternsOf */
+export declare const vectorExcludePatternsOf: (plan: SchemaPlan) => string[];
+/**
+ * `autoValue: "on_update"`, as the file Rebase applies itself.
+ *
+ * Empty when nothing declares one — the caller writes no file then, and removes
+ * a stale one.
+ */
+export declare function renderTriggersDdl(plan: SchemaPlan): string;
+/** @see searchExcludePatternsOf */
+export declare const triggerExcludePatternsOf: (plan: SchemaPlan) => string[];

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

@@ -0,0 +1,31 @@
+/**
+ * `schema.generated.ts`, rendered from a {@link SchemaPlan}.
+ *
+ * This file is what a developer running drizzle-kit themselves diffs against,
+ * and what the runtime's query builder is typed by. It has to *compile*, which
+ * nothing in this repo checked until `generated-schema-compiles.test.ts`: six
+ * ordinary inputs used to produce a file TypeScript rejects, and the class the
+ * bigint incident already taught is that a file which will not build gets
+ * hand-patched and then sits stale until a security fix misses production.
+ *
+ * Two structural rules keep that from coming back:
+ *
+ * - **The import list is derived from what was emitted.** Every builder is
+ *   recorded as it is used ({@link BuilderUses}), and the header is written
+ *   last, from that set. It used to be a fixed roster plus three
+ *   property-scanning heuristics, so `columnType: "uuid"` on a plain string
+ *   emitted `uuid(…)` and imported nothing.
+ * - **Nothing here reads a `Property`.** Types, defaults, keys and constraints
+ *   all arrive decided. The Drizzle generator disagreeing with the DDL one is
+ *   what left `geopoint` with a database column and no Drizzle key.
+ */
+import type { SchemaPlan } from "./types.js";
+/** What the generated file may leave out. */
+export interface DrizzleRenderOptions {
+    /**
+     * `false` strips the `pgPolicy(...)` calls. RLS is still enabled on every
+     * table regardless — a bare table must default-deny, not fail open.
+     */
+    policies?: boolean;
+}
+export declare function renderDrizzleSchema(plan: SchemaPlan, options?: DrizzleRenderOptions): string;