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

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

@@ -0,0 +1,410 @@
+/**
+ * The one description of the database a set of collections asks for.
+ *
+ * ## Why this shape exists
+ *
+ * Rebase used to compile a `Property` into a column in three places:
+ * `getDrizzleColumn` (`schema.generated.ts`), `getSqlColumnType` plus the
+ * `CREATE TABLE` walk around it (`schema.sql`, what `db push` applies) and
+ * `planCollectionSchemaEnsure` (what a managed tenant gets at boot, where no
+ * `db push` ever runs). Three `switch (prop.type)` statements, three readings
+ * of `relations`, of `enum`, of `search`, of `validation.unique`. The audit
+ * that produced this module counted twelve open disagreements between them and
+ * found that a third of the commits touching those files were
+ * re-synchronisations.
+ *
+ * So a `Property` is read exactly once, by {@link planSchema}, into the types
+ * below — and the three emitters became renderers of the result. A
+ * disagreement now needs someone to write a second interpreter on purpose.
+ *
+ * ## The rules the shape enforces
+ *
+ * - **The type is tagged, never a string.** `{ kind: "varchar", length: 255 }`
+ *   rather than `"VARCHAR(255)"`. A renderer that has to parse a type back
+ *   apart is a renderer that will disagree with the one that wrote it, and the
+ *   Drizzle import list is derived from the tags actually present — which is
+ *   what makes "a builder used without its import" unrepresentable.
+ * - **A default is a value, not a spelling.** See {@link ColumnDefault}.
+ * - **Derived names are in the plan, not in the renderer.** Constraint names,
+ *   index names and enum type names are frozen identifiers (see
+ *   `contracts/derived-names.txt`); they are computed once, here, so the three
+ *   files cannot name the same object differently.
+ */
+import type { CollectionConfig } from "@rebasepro/types";
+import type { CollectionIndexSpec } from "../collection-index.js";
+import type { SearchColumnSpec } from "../search-column.js";
+import type { VectorColumnSpec, VectorIndexPlan } from "../vector-index.js";
+/**
+ * A Postgres column type, tagged.
+ *
+ * Every member renders to exactly one SQL spelling and exactly one
+ * drizzle-orm/pg-core builder, and those two mappings live in the renderers —
+ * so adding a type means adding it here and being told, by the compiler, about
+ * both. That is the property the three copies of `switch (prop.type)` did not
+ * have: `geopoint` had an arm in the DDL generator and none in the Drizzle one,
+ * so the database got a column the generated table had no key for and every
+ * write to it was discarded with a 201.
+ */
+export type PgType = {
+    kind: "text";
+} | {
+    kind: "varchar";
+    length: number;
+} | {
+    kind: "char";
+    length: number;
+} | {
+    kind: "uuid";
+}
+/** A Postgres `enum` type. `name` is the type name, unqualified. */
+ | {
+    kind: "enum";
+    schema: string;
+    name: string;
+    varName: string;
+    labels: string[];
+} | {
+    kind: "smallint";
+} | {
+    kind: "integer";
+} | {
+    kind: "bigint";
+} | {
+    kind: "smallserial";
+} | {
+    kind: "serial";
+} | {
+    kind: "bigserial";
+} | {
+    kind: "real";
+} | {
+    kind: "doublePrecision";
+}
+/** `precision`/`scale` present only when the property declares them. */
+ | {
+    kind: "numeric";
+    precision?: number;
+    scale?: number;
+} | {
+    kind: "boolean";
+} | {
+    kind: "timestamptz";
+} | {
+    kind: "date";
+} | {
+    kind: "time";
+} | {
+    kind: "json";
+} | {
+    kind: "jsonb";
+} | {
+    kind: "vector";
+    dimensions: number;
+} | {
+    kind: "bytea";
+}
+/** The generated full-text column. Only the search planner produces it. */
+ | {
+    kind: "tsvector";
+} | {
+    kind: "array";
+    of: PgType;
+};
+/**
+ * What a column defaults to, as the thing itself rather than a rendered string.
+ *
+ * The three emitters each spelled these differently and disagreed on all four
+ * id strategies: the DDL generator wrote `DEFAULT ${prop.isId}` verbatim, so
+ * the documented ``isId: "sql`gen_id()`"`` reached Postgres with the template
+ * wrapper still on it; boot-ensure gave a default to `uuid` and to nothing
+ * else, so every other strategy arrived with none and the first insert failed
+ * on a NULL primary key.
+ *
+ * `sql` carries the expression, wrapper already stripped. `identity` is not a
+ * DEFAULT at all — it is part of the column type
+ * (`INTEGER GENERATED BY DEFAULT AS IDENTITY`), which is where both SQL
+ * renderers put it. `literal` carries **both** the JavaScript value and the
+ * SQL literal it quotes to: the renderers all emit the SQL form (Drizzle as
+ * ``.default(sql`…`)``), so the three files cannot disagree about how a string
+ * with an apostrophe or a `Date` is spelled, and the value is kept so the write
+ * path and the schema can be checked against each other.
+ */
+export type ColumnDefault = {
+    kind: "sql";
+    expression: string;
+} | {
+    kind: "identity";
+} | {
+    kind: "literal";
+    value: unknown;
+    sql: string;
+};
+/** Where a column in a {@link TablePlan} came from. */
+export interface ColumnSource {
+    kind: 
+    /** A declared property. */
+    "property"
+    /** The `id TEXT PRIMARY KEY` a collection declaring no key gets. */
+     | "implicit-id"
+    /** A `belongsTo` relation's foreign key column. */
+     | "relation"
+    /** A `reference` property's foreign key column. */
+     | "reference"
+    /** A generated search column (`tsvector`, or the fuzzy `text` one). */
+     | "search"
+    /** An auth-owned column the collection does not declare. */
+     | "auth"
+    /** A junction endpoint column. */
+     | "junction-key";
+    /** The property that produced it, when one did. */
+    propName?: string;
+    /** The collection slug, for error messages. */
+    slug?: string;
+}
+/**
+ * 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. The name is derived by `toPostgresIdentifier`, which
+ * truncates to 63 bytes exactly as Postgres does, because the comparison is
+ * against a catalogue that already holds the truncated form.
+ */
+export interface ForeignKeyPlan {
+    constraintName: string;
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    column: string;
+    targetSchema: string;
+    targetTable: string;
+    targetColumn: string;
+    onDelete: string;
+    onUpdate?: string;
+    sql: string;
+}
+/**
+ * One column of one table.
+ *
+ * `key` and `column` are two names for one thing and this is where they meet:
+ * the wire name (the Drizzle object key, what the API serves) and the SQL
+ * identifier. They differ whenever a property is camelCase or carries an
+ * explicit `columnName` — `authorId` / `author_id` — and every emitter that
+ * conflated them produced either a schema that does not compile or an API that
+ * serves the wrong field name.
+ */
+export interface ColumnPlan {
+    /** Wire name: the Drizzle object key and the JSON field. */
+    key: string;
+    /** SQL identifier. */
+    column: string;
+    type: PgType;
+    nullable: boolean;
+    primaryKey: boolean;
+    unique: boolean;
+    default?: ColumnDefault;
+    /** A STORED generated column — today only the search ones. */
+    generated?: {
+        expression: string;
+        stored: true;
+    };
+    foreignKey?: ForeignKeyPlan;
+    /**
+     * `autoValue: "on_update"`: the column is stamped with `now()` by a
+     * `BEFORE UPDATE` trigger as well as by the driver, so a raw `UPDATE` — a
+     * seed, a migration, psql — keeps it honest. See {@link TriggerPlan}.
+     */
+    touchOnUpdate?: boolean;
+    /**
+     * True when a *declared property* emits this column and a relation
+     * contributes only the constraint — `postId` with `columnName: "post_id"`
+     * beside a `belongsTo` on `post_id`. Both used to emit the column and
+     * `CREATE TABLE` failed with "column specified more than once".
+     */
+    columnOwnedByProperty?: boolean;
+    /**
+     * What this column would have been called before `generateForeignKeyName`
+     * learned to singularize — set only when the two differ and the name is the
+     * derived default rather than one the author wrote. Carried so boot-ensure
+     * can recognise a database provisioned under the old rule and rename rather
+     * than add a second, empty column beside it. Never used to name anything.
+     */
+    legacyColumn?: string;
+    /**
+     * The verbatim SQL definition this column has when a **SQL** emitter
+     * creates it, overriding `type`/`nullable`/`default`/`unique`.
+     *
+     * Two producers. `auth-users-columns` is the single description of what an
+     * auth user table's columns must be — three code paths create
+     * `rebase.users` and they disagreed about `email`'s nullability and
+     * `roles`'s default until that module existed. And the generated search
+     * columns, whose `tsvector GENERATED ALWAYS AS (…) STORED` is one string in
+     * `search-column`, shared with the `ADD COLUMN` in `search.sql`.
+     *
+     * The Drizzle renderer ignores it: drizzle-kit does not create the auth
+     * table, and it spells a generated column with `.generatedAlwaysAs()`.
+     */
+    sqlDefinition?: string;
+    source: ColumnSource;
+}
+/** One compiled RLS policy: the clauses, not the SQL and not the rule. */
+export interface PolicyPlan {
+    name: string;
+    /**
+     * Which `SecurityRule` this came from.
+     *
+     * A rule with `operations: ["update", "delete"]` compiles to two policies,
+     * and the pair is still one thing the author wrote: `policies.sql` says
+     * "Rebase injected this" once above the run rather than once per statement.
+     */
+    ruleKey: string;
+    operation: string;
+    /** `permissive` | `restrictive`, lower-case as the rule spells it. */
+    mode: string;
+    /** Sorted, `["public"]` when the rule names none. */
+    roles: string[];
+    /** Compiled `USING` clause, or null when the operation takes none. */
+    using: string | null;
+    /** Compiled `WITH CHECK` clause, or null when the operation takes none. */
+    withCheck: string | null;
+    /**
+     * True when Rebase added this rule rather than the author. They are
+     * permissive, so they OR with the declared rules and widen the ACL beyond
+     * what `securityRules` reads like — `policies.sql` says so in a comment.
+     */
+    injected: boolean;
+}
+/** A `BEFORE UPDATE` trigger stamping `now()` onto an `on_update` column. */
+export interface TriggerPlan {
+    schema: string;
+    /** Bare table name. */
+    table: string;
+    column: string;
+    /** Frozen derived name — see `contracts/derived-names.txt`. */
+    name: string;
+}
+/** A Postgres enum type one or more columns reference. */
+export interface EnumPlan {
+    schema: string;
+    /** Type name, unqualified: `<table>_<column>`. A frozen derived name. */
+    name: string;
+    /** `schema.name` — the key `readExistingSchema` returns. */
+    qualified: string;
+    /**
+     * The schema the collection *declared*, before the `public` fallback.
+     *
+     * `pgEnum` can only declare a type in `public`; anything else has to go
+     * through `<name>Schema.enum(...)`, and the choice is the declaration, not
+     * the resolved name.
+     */
+    declaredSchema?: string;
+    /** The Drizzle variable the type is declared as. */
+    varName: string;
+    labels: string[];
+}
+export interface TablePlan {
+    schema: string;
+    /** Bare table name, no schema prefix. */
+    table: string;
+    /** `schema.table` — the key `readExistingSchema` returns. */
+    qualified: string;
+    /** The schema the collection *declared*, before the `public` fallback. */
+    declaredSchema?: string;
+    /** The Drizzle variable this table is declared as. */
+    varName: string;
+    kind: "collection" | "junction";
+    /** The collection slug, absent for a junction (no collection declares one). */
+    slug?: string;
+    /**
+     * For a junction: the slugs whose `manyToMany` declarations produced it.
+     * Named in `policies.sql` so a reader can find the collection to edit.
+     */
+    declaringSlugs?: string[];
+    columns: ColumnPlan[];
+    /** Column names, in order. One entry for a collection, two for a junction. */
+    primaryKey: string[];
+    /** The declared `indexes:` block, with its frozen names. */
+    indexes: CollectionIndexSpec[];
+    /** The opt-in `search` block's column, helpers and index. */
+    search?: SearchColumnSpec;
+    /** ANN indexes for the table's `vector` columns, and the ones skipped. */
+    vector?: VectorIndexPlan;
+    /**
+     * The table's `vector` columns, as `vector.sql` adds them.
+     *
+     * Wider than {@link TablePlan.vector}, which answers "what gets an ANN
+     * index" and skips a column too wide to index — one that still needs its
+     * column.
+     */
+    vectorColumns: VectorColumnSpec[];
+    /** RLS is enabled on every generated table; these are its policies. */
+    policies: PolicyPlan[];
+    triggers: TriggerPlan[];
+    /** Whether `auth-users-columns` owns part of this table. */
+    auth: boolean;
+}
+/**
+ * One entry in a generated `relations(...)` block.
+ *
+ * Both sides of a link must carry the same `relationName` or Drizzle cannot
+ * pair them; the rule that derives it is `sharedRelationName`, which both sides
+ * compute independently from the table that owns the column.
+ */
+export interface RelationPlan {
+    /** 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;
+    /** Property keys on this table. */
+    fields?: string[];
+    /** Property keys on the target table. */
+    references?: string[];
+}
+export interface PlanOptions {
+    /**
+     * Server extensions the project's databases gave Rebase leave to install —
+     * `declaredDatabaseExtensions()`. Absent means none, which is a refusal and
+     * the right default for a planner given no configuration at all.
+     */
+    databaseExtensions?: readonly string[];
+}
+/**
+ * Everything a set of collections asks the database for.
+ *
+ * Ordered as the emitters emit: `tables` is in the order the generators walk
+ * (each collection, then any junction its relations imply), because
+ * `schema.sql` and `schema.generated.ts` are compared byte-for-byte against
+ * their committed copies and a reordering reads as a change.
+ */
+export interface SchemaPlan {
+    /** `CREATE SCHEMA IF NOT EXISTS` targets, `rebase` first. */
+    schemas: string[];
+    /**
+     * The schemas collections declared, without `rebase`.
+     *
+     * The SQL file creates `rebase` unconditionally — the RLS helpers live in
+     * it, and a schema in Atlas's replayed state but absent from the desired one
+     * gets a `DROP SCHEMA … CASCADE` planned against it, which would take the
+     * auth tables. The Drizzle file declares only what a collection asked for,
+     * because a `pgSchema` variable nothing uses is dead code.
+     */
+    declaredSchemas: string[];
+    enums: EnumPlan[];
+    tables: TablePlan[];
+    relations: RelationPlan[];
+    /** `CREATE EXTENSION IF NOT EXISTS …;` statements, deduplicated. */
+    extensions: string[];
+    /** `CREATE OR REPLACE FUNCTION …` bodies, deduplicated, in apply order. */
+    functions: string[];
+    /** The collections this plan was built from, filtered to the SQL ones. */
+    collections: CollectionConfig[];
+    options: PlanOptions;
+}

package/dist/schema/plan/updated-at-trigger.d.ts

@@ -0,0 +1,22 @@
+import type { TriggerPlan } from "./types.js";
+/** The one trigger function, qualified. A frozen derived name. */
+export declare const SET_UPDATED_AT_FN = "rebase.set_updated_at";
+/**
+ * `CREATE OR REPLACE FUNCTION`, so replaying it against a database that already
+ * has it is a no-op — this is emitted into a file that runs on every push and
+ * is appended to migrations that run against databases at any stage of life.
+ */
+export declare const setUpdatedAtFunction: () => string;
+/**
+ * `DROP TRIGGER IF EXISTS` before the `CREATE`.
+ *
+ * `CREATE OR REPLACE TRIGGER` exists only on Postgres 14+, and this runs
+ * against whatever a self-hosted project points at. Two statements rather than
+ * one is also what the boot-time applier needs: it issues DDL one statement at
+ * a time over the extended query protocol, which forbids multiple commands in
+ * one execute.
+ */
+export declare const dropTriggerStatement: (plan: TriggerPlan) => string;
+export declare const createTriggerStatement: (plan: TriggerPlan) => string;
+/** Both statements, in the order they must run. */
+export declare const triggerStatements: (plan: TriggerPlan) => string[];

package/dist/schema/relation-names.d.ts

@@ -0,0 +1,28 @@
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+/**
+ * The `relationName` both sides of a link must agree on.
+ *
+ * Drizzle pairs an owning `one()` with its inverse `many()` by this string and
+ * by nothing else, and the two sides are computed by different callers holding
+ * different collections — so the rule has to be derivable from either end. It
+ * is: name the link after the table that carries the foreign key and the field
+ * key that column is served under.
+ *
+ *   owning  (belongsTo)      → `{thisTable}_{fieldKey(localKey)}`
+ *   inverse (hasMany/hasOne) → `{targetTable}_{fieldKey(foreignKeyOnTarget)}`
+ *
+ * Both spellings of `jobs.company` produce `jobs_companyId`. A many-to-many is
+ * named through its junction wiring and a `via` chain is not a Drizzle relation
+ * at all, so both keep the local name.
+ *
+ * The field key rather than the column: the Drizzle object is keyed by the wire
+ * name (`fieldKeyForColumn` is the one definition of it), and a name built from
+ * the column would differ between a collection that declares `columnName` and
+ * one that does not, for the same link.
+ *
+ * **This is the one definition.** `generate-drizzle-schema-logic.ts` holds a
+ * private copy (`computeSharedRelationName`) that this was lifted from verbatim;
+ * the generator should import this instead, so the file it writes and the
+ * relations the runtime builds from the live catalogue cannot drift apart.
+ */
+export declare function sharedRelationName(relation: ResolvedRelation, sourceCollection: CollectionConfig): string;

package/dist/schema/search-column.d.ts

@@ -140,6 +140,15 @@ export declare const searchHelperFunctions: (spec: SearchColumnSpec) => string[]
  * with "text search dictionary does not exist". Observed, not theorised.
  */
 export declare const searchExtensionStatements: (spec: SearchColumnSpec) => string[];
+/**
+ * Everything after the column name — the type and the generation expression.
+ *
+ * Split out because four emitters need it and only two of them have a place to
+ * put the name: `CREATE TABLE` and `ADD COLUMN` write `"col" <this>`, while the
+ * schema plan carries it as the column's SQL definition and the boot-time
+ * rebuild statement interpolates it on its own.
+ */
+export declare const searchColumnTypeSql: (expression: string, kind: "tsvector" | "text") => string;
 /** The column definition as it appears inside `CREATE TABLE`. */
 export declare const searchColumnDefinition: (spec: SearchColumnSpec) => string;
 /** The fuzzy column definition, when the spec asks for one. */

package/dist/security/rls-enforcement.d.ts

@@ -97,6 +97,23 @@ export interface AuthContext {
      * rather than having every one of its users reclassified as guests.
      */
     isAnonymous?: boolean;
+    /**
+     * The **custom** claims on the caller's token, as `rebase.jwt()` reports
+     * them.
+     *
+     * This is how a policy reaches a fact about the session that is neither the
+     * uid nor the roles — which, before this, it could not: `app.jwt` was built
+     * from three fields the driver already had, so `rebase.jwt()`, documented
+     * as "full JWT claims as JSONB", returned a three-key object that never had
+     * a claim in it.
+     *
+     * Multi-tenancy's `claim` form is the first caller — `policy.authClaim(…)`
+     * compiles to `rebase.jwt() ->> '<name>'`. Identity claims are stripped out
+     * before they reach here (`AccessTokenPayload.claims`) and the identity
+     * fields are written *over* them below, so nothing a hook put on a token
+     * can assert a uid, roles or guest status.
+     */
+    claims?: Record<string, unknown>;
 }
 /**
  * Warn when the connection role shares its name with an existing schema.