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

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

@@ -1,7 +1,7 @@
 /**
- * Bringing a database up to date with a bundle's collections, additively.
+ * Applying a schema plan to a database that is already running.
  *
- * ## Why this exists
+ * ## What this module is
  *
  * A managed runtime boots someone else's compiled project against a database it
  * has never seen. Auth tables are ensured at boot already, but collection tables
@@ -9,291 +9,49 @@
  * request answered 500 on a missing relation. `rebase db push` cannot help — it
  * is an Atlas-driven CLI command, and the runtime image ships no CLI.
  *
+ * Two halves, and only one of them is here. *What the collections ask for* is
+ * `schema/plan/plan-schema.ts`, shared with `db push` and the generated Drizzle
+ * file; *what the database already has, and which of those statements are safe
+ * to run against it* is `schema/plan/diff-plan.ts`. This module reads the
+ * catalogue, runs the statements, and reports what happened.
+ *
  * ## Why additive-only, forever
  *
  * This runs unattended, 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.
- *
- * It will **never** drop a table or a column, narrow a type, or alter a
- * constraint. 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, which is precisely the failure `db push` was hardened
- * against. 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.
+ * human reading a diff. So it may only ever do things that cannot lose data.
+ * See `diff-plan.ts` for the whole of that argument.
  */
 import { type CollectionConfig } from "@rebasepro/types";
-import { type SkippedVectorIndex } from "./vector-index.js";
-import { type ColumnTypeDrift } from "./column-type-drift.js";
+import { type ConstraintPolicy, type DiffOptions, type EnsureAction, type EnsurePlan, type ExistingSchema, type LegacyForeignKey, type OrphanedRequiredColumn, type SearchColumnDrift, type WithheldConstraint } from "./plan/diff-plan.js";
+export type { ConstraintPolicy, EnsureAction, EnsurePlan, ExistingSchema, LegacyForeignKey, OrphanedRequiredColumn, SearchColumnDrift, WithheldConstraint };
 /**
  * The subset of a database handle this needs: run a statement, get rows back.
  *
  * Deliberately parameterless. Everything here is DDL or catalogue reads keyed by
  * schema name, and schema names are identifiers — they cannot be bound as
- * parameters anyway. They are validated against {@link SAFE_IDENTIFIER} before
- * they reach a statement, so a config that somehow carried a quote is refused
- * rather than concatenated.
+ * parameters anyway. They are validated by `assertSafeIdentifier` before they
+ * reach a statement, so a config that somehow carried a quote is refused rather
+ * than concatenated.
  */
 export interface Queryable {
     query<T = unknown>(sql: string): Promise<{
         rows: T[];
     }>;
 }
-/** 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, so it
-     * is the only evidence that a `search` block has changed since the column
-     * was built. Absent is read as "no column is stamped", which plans a stamp
-     * and reports nothing as drifted.
-     */
-    columnComments?: Map<string, string>;
-    /**
-     * `schema.typename` → the values that type currently holds, in order.
-     *
-     * Without this, an enum type that already exists is skipped whole and a
-     * value added to it never reaches the database — the type is there, so
-     * nothing plans anything, and the first row using the new value is rejected
-     * by a constraint nobody changed. Absent is read as "the values are
-     * unknown", which keeps the old skip-by-name behaviour rather than guessing.
-     */
-    enumValues?: Map<string, string[]>;
-    /** `schema.table.column` for every column the database marks NOT NULL. */
-    notNullColumns?: Set<string>;
-    /**
-     * `schema.table.column` → the column's `udt_name` as the database reports
-     * it (`int4`, `jsonb`, `_numeric` for an array of numeric).
-     *
-     * The only evidence that a column's declared type and its real type have
-     * parted company. Absent is read as "unknown", which reports no drift —
-     * see `column-type-drift.ts` for why silence is the right unknown here.
-     */
-    columnTypes?: Map<string, string>;
-    /**
-     * Tables known to hold at least one row.
-     *
-     * The only thing that decides whether a NOT NULL can be added without
-     * reading the data: on an empty table the constraint cannot fail, on a
-     * populated one it is checked against every existing row. Absent is read as
-     * "assume populated", which is the conservative direction — it withholds a
-     * constraint rather than attempting one that aborts the boot.
-     */
-    populatedTables?: Set<string>;
-    /**
-     * `schema.table.column` for every column the database gives a DEFAULT.
-     *
-     * Paired with {@link notNullColumns} to decide whether a column no property
-     * declares can still accept a write: NOT NULL with a default can, NOT NULL
-     * without one cannot. Absent is read as "unknown", which reports nothing.
-     */
-    columnDefaults?: 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. That
- *   is the context in which changing an existing column's constraints is a
- *   reviewed act rather than a surprise.
- */
-export type ConstraintPolicy = "additive" | "converge";
-export interface EnsureOptions {
-    /** Defaults to `additive`. See {@link ConstraintPolicy}. */
-    constraints?: ConstraintPolicy;
+export interface EnsureOptions extends DiffOptions {
     /**
      * Server extensions the project's databases gave Rebase leave to install —
      * `declaredDatabaseExtensions()`. Absent means none, which is a refusal and
      * is the right default for a planner given no configuration at all.
      *
-     * Explicit rather than read from the resource registry in here, because
-     * this function is pure and several callers plan against fixtures: reaching
-     * for a process-wide registry would make the plan depend on whatever some
-     * other module happened to import. `ensureCollectionTables` is the boundary
-     * that reads the world.
+     * Explicit rather than read from the resource registry in here, because the
+     * planner is pure and several callers plan against fixtures: reaching for a
+     * process-wide registry would make the plan depend on whatever some other
+     * module happened to import. `ensureCollectionTables` is the boundary that
+     * reads the world.
      */
     databaseExtensions?: readonly string[];
 }
-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";
-    /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
-    target: string;
-    sql: 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.
-     *
-     * 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[];
-    /**
-     * Generated search columns whose `search` block has changed since they were
-     * built. Reported, never planned into `actions` — see
-     * {@link SearchColumnDrift} for why applying it is not this path's call.
-     */
-    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; whether they match the
-     * current block cannot be known, which is what the caller reports.
-     */
-    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, and refusing the boot over it would make a working
-     * configuration unbootable. Reported rather than dropped: an unindexed
-     * vector column and an indexed one differ only in latency, so nothing
-     * about the running system says which one you got.
-     */
-    vectorIndexSkipped: SkippedVectorIndex[];
-    /**
-     * Constraints the configuration asks for that this plan is not applying,
-     * and why.
-     *
-     * This is the half of the feature that matters most. Every one of these was
-     * previously withheld in silence: a required property arrived nullable, and
-     * the only evidence was a database that disagreed with its own
-     * configuration. Reporting them is what lets boot warn, the live editor
-     * refuse, and the doctor explain — three surfaces that until now had nothing
-     * to read.
-     */
-    withheldConstraints: WithheldConstraint[];
-    /**
-     * Columns whose type in the database is in a different family from the one
-     * the collection declares.
-     *
-     * Reported and never acted on — see `column-type-drift.ts`. This is the one
-     * divergence that presents as a *working* deploy: the statement was never
-     * planned, so nothing failed, and the first evidence is a write rejected
-     * hours later by whichever end validates first.
-     */
-    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. Rename
-     * `title` to `headline` and boot does exactly what it promises: it adds
-     * `headline` (nullable, correctly, and says why) and leaves `title` alone,
-     * because dropping a column is destructive and this runs unattended. The
-     * table is then unwritable:
-     *
-     *     POST /api/data/posts -> 400 PG_23502
-     *     Missing required field: "title" in "posts" cannot be empty.
-     *
-     * naming a field that is no longer in the collection at all. On the default
-     * first-run path there is no way out inside the product either: the managed
-     * database is PGlite, and `db push` — the documented repair — refuses there
-     * because Atlas needs a second database to diff against.
-     *
-     * 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[];
-}
-/**
- * A NOT NULL column with no default that no property declares.
- * @see EnsurePlan.orphanedRequiredColumns
- */
-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 — the same
- * reason it withholds `SET NOT NULL` from an adopted table — so a multi-minute
- * outage is not a decision it may take on its own.
- *
- * Not applying it silently is not an option either: that is the bug this
- * detection exists for. 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 EnsureOutcome extends EnsurePlan {
     /**
      * Actions that could not be applied and are non-fatal by nature.
@@ -312,11 +70,16 @@ export interface EnsureOutcome extends EnsurePlan {
     }[];
 }
 /**
- * Decide what to add. Pure — the caller supplies what exists and runs the result.
- *
- * Ordering matters and is deliberate: enum types before the tables and columns
- * that reference them, tables before the columns added to other tables (a new
- * table may be the target of a relation), and nothing is emitted twice.
+ * Decide what to add. Pure — the caller supplies what exists and runs the
+ * result.
+ *
+ * A plan and a diff: the collections are read once, by `planSchema`, into the
+ * same {@link SchemaPlan} `db push` renders `schema.sql` from, and the diff
+ * subtracts what the database already has. Before that split this function had
+ * its own reading of every `Property`, and the audit found twelve places where
+ * it disagreed with the two generators — a required `author_id` that was
+ * NOT NULL after a push and nullable after a boot among them, on the one path
+ * with no developer in the loop.
  */
 export declare function planCollectionSchemaEnsure(allCollections: CollectionConfig[], existing: ExistingSchema, options?: EnsureOptions): EnsurePlan;
 /** Read what the database has, for the schemas the collections live in. */

package/dist/schema/generate-drizzle-schema-logic.d.ts

@@ -1,10 +1,28 @@
-import { CollectionConfig, Property } from "@rebasepro/types";
 /**
- * The Drizzle column declaration a property compiles to, or `null` when the
- * property puts no column on *this* table (an inverse relation, whose column
- * lives on the target). Exported so it can be checked against its DDL twin
- * `getSqlColumnType` directly — the two disagreeing is what left `geopoint`
- * with a database column and no Drizzle key.
+ * `schema.generated.ts`, the Drizzle half of `rebase db generate`.
+ *
+ * There is no interpretation left in this file. `schema/plan/plan-schema.ts`
+ * reads the collections into a {@link SchemaPlan} and
+ * `schema/plan/render-drizzle.ts` writes the TypeScript; this is the entry
+ * point they are reached through.
+ *
+ * It used to hold `getDrizzleColumn` — one of three `switch (prop.type)`
+ * statements, each with its own reading of relations, enums, search and
+ * `validation.unique`, and each disagreeing with the other two about something.
+ * See `schema/plan/types.ts`.
  */
-export declare const getDrizzleColumn: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string | null;
-export declare const generateSchema: (allCollections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;
+import type { CollectionConfig } from "@rebasepro/types";
+import { type DrizzleRenderOptions } from "./plan/render-drizzle.js";
+/**
+ * The generated Drizzle schema for a set of collections.
+ *
+ * Synchronous, and takes an options object. It was `async` with nothing to
+ * await and a positional `stripPolicies` boolean — `generateSchema(c, true)`,
+ * which reads as neither "with policies" nor "without".
+ *
+ * Sorted by slug here rather than in the writer script: the output is
+ * order-dependent and `rebase doctor` regenerates it in memory to compare
+ * against the file on disk, so with the sort in the writer only, a project
+ * whose file order differed from its slug order was reported stale forever.
+ */
+export declare const generateSchema: (allCollections: CollectionConfig[], options?: DrizzleRenderOptions) => string;

package/dist/schema/generate-drizzle-schema.js

@@ -1,6 +1,6 @@
 import { createRequire as __createRequire } from "module";
 __createRequire(import.meta.url);
-import { t as main } from "../generate-drizzle-schema-CwEgVyjO.js";
+import { t as main } from "../generate-drizzle-schema-vSK-VdYT.js";
 //#region src/schema/bin/generate-drizzle-schema.ts
 /**
 * The built entry point for `generate-drizzle-schema`.