okmodel 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 okmodel is a catalog-first TypeScript ORM, PostgreSQL first. Other SQL databases are the direction. CI runs PostgreSQL 15 to 18. The schema is the single source. Migrations and queries come from it.
 
-Version 0.3.0. Apache-2.0.
+Version 0.5.0. Apache-2.0.
 
 ## Contents
 
@@ -54,7 +54,16 @@ Version 0.3.0. Apache-2.0.
   - [Views](#views)
   - [Roles and grants](#roles-and-grants)
   - [okm ext and okm doctor](#okm-ext-and-okm-doctor)
+  - [Linter](#linter)
+  - [Reference data](#reference-data)
+  - [Backfill](#backfill)
+  - [Testing](#testing)
+  - [Topology](#topology)
+  - [Reference app](#reference-app)
+  - [Startup](#startup)
+  - [Protected targets](#protected-targets)
 - [Commands](#commands)
+- [Check a history in CI](#check-a-history-in-ci)
 - [Roadmap](#roadmap)
 - [Size](#size)
 - [Docs](#docs)
@@ -143,13 +152,15 @@ A protected target refuses push. Production settings are in the [production chec
 
 ### Reviewed migrations
 
-Generate writes a SQL file and `.okm`, and apply runs that file later so you can read the migration first.
+Generate writes a SQL file and `.okm`. On an empty database, apply installs that schema and any reference rows. A database that already has history runs the new file, so you can read it first.
 
 ```sh
 bunx okm generate init
 bunx okm migrate apply
 ```
 
+Each step is `expand`, `contract`, or unclassified SQL. Expand is additive. Contract removes or tightens something. On an existing table the planner writes the safe form: a concurrent index, a check or foreign key as `NOT VALID` then `VALIDATE`, and `SET NOT NULL` through a validated check. A backfill step updates rows in batches and resumes after a failure. See [Backfill](#backfill).
+
 ### One client
 
 Import `db` from this file wherever the server handles a request. The process keeps one client.
@@ -880,25 +891,250 @@ okm doctor
 okm doctor OKM1811
 ```
 
+### Linter
+
+A migration plan is checked before it runs. Dropping a table, renaming a column, or adding a unique constraint on a table that already exists is an error. On an existing table the planner writes the safe form: a concurrent index, a check or foreign key as `NOT VALID` then `VALIDATE`, and `SET NOT NULL` through a validated check. The same statements written by hand, without that form, are errors. A type change that rewrites the table stays a warning. `okm generate` prints the finding and still writes the file. `okm migrate plan` and `okm check` exit non-zero on an error. `okm migrate apply` refuses with OKM1510 before any statement. The linter reads the plan and the catalogs. It does not connect. See [the linter](https://github.com/omqkhafi/okmodel/blob/main/docs/linter.md).
+
+```text
+error OKM1511 step 1: drops a table -- fix: Stop reading the table in an expand migration, then drop it in a later contract. Or allow OKM1511 with a reason.
+```
+
+```sql
+-- okm-allow OKM1511: the table is empty and nothing reads it
+drop table "public"."notes";
+```
+
+### Reference data
+
+Rows the application needs are declared on the table. Apply on an empty database inserts a missing key. It does not update or delete. The rows are not part of the catalog hash, so a new key does not need a DDL migration.
+
+`reference.ts`:
+
+```ts
+import { schema, table, t } from "okmodel/pg";
+
+const roles = table(
+  "roles",
+  { code: t.text().primaryKey(), label: t.text() },
+  {
+    reference: {
+      key: "code",
+      rows: [{ code: "admin", label: "Admin" }],
+    },
+  },
+);
+
+export default schema({ tables: [roles] });
+```
+
+### Backfill
+
+A backfill is one idempotent `UPDATE` in the migration file. `$1` is the exclusive lower bound and `$2` is the inclusive upper bound. Null opens that side. Apply commits one batch at a time and resumes from `okm_backfill`. There is no `okm backfill` command. A protected target refuses the step unless that invocation passes `--allow-protected`.
+
+```sql
+-- name: fill
+-- class: expand
+
+-- class: expand
+-- action: backfill
+-- lock: ROW EXCLUSIVE
+-- transactional: false
+-- backfill table="public"."notes" key="id" batch=10
+update "public"."notes" set "title" = 'noted' where "title" = 'hello' and ("id" > $1 or $1 is null) and ("id" <= $2 or $2 is null);
+```
+
+### Testing
+
+`okmodel/testing` opens a real pool. `factories` insert rows, `expectQueries` counts statements, and `isolation()` checks that tenant A cannot see tenant B. `okm seed <file>` calls the file's default export with that harness. The target must already be migrated. A protected target is refused unless `--allow-protected`.
+
+`factory.ts`:
+
+```ts
+import { schema, table, t } from "okmodel/pg";
+import { open } from "okmodel/pg/pglite";
+import { testing } from "okmodel/testing";
+
+const notes = table("notes", { id: t.identity(), title: t.text() });
+const app = schema({ tables: [notes] });
+const harness = await testing(app, { driver: open() });
+const factories = harness.factories({
+  notes: (x) => ({ title: x.words(2) }),
+});
+await harness.expectQueries(1, () => factories.notes.create());
+const rows = await harness.db.notes.find({ limit: 5 });
+if (rows.length !== 1) throw new Error("expected one note");
+await harness.close();
+```
+
+`seed.ts`:
+
+```ts
+export default async function seed(t: {
+  factories(definitions: {
+    authors(x: { words(count: number): string }): { name: string };
+    notes(x: { words(count: number): string; ref(table: string): unknown }): {
+      title: string;
+      authorId: unknown;
+    };
+  }): {
+    notes: { create(): Promise<unknown> };
+  };
+}): Promise<void> {
+  const factories = t.factories({
+    authors: (x) => ({ name: x.words(2) }),
+    notes: (x) => ({ title: x.words(2), authorId: x.ref("authors") }),
+  });
+  await factories.notes.create();
+}
+```
+
+```sh
+bunx okm seed seed.ts
+```
+
+### Topology
+
+`connect({ primary, replicas }, options)` opens one pool per endpoint. An automatic read chooses a replica that has replayed at least as far as this client's last committed write. `routing.consistency` is `"session"` by default. `"eventual"` does not keep that watermark. `routing.maxLag` is a duration (`"5s"`, `"500ms"`, `"2m"`) or a size (`"16MB"`, `"512KB"`, `"1GB"`, `"4096B"`). A bare number is rejected. `find({ route: "primary" })` reads the primary. `find({ route: "replica" })` requires a replica that satisfies the same watermark and lag, and it does not fall back to the primary. `db.using("primary")` or `db.using("replica")` returns a client that forces that route. That client has no `close` and no `using`. `onRoute` receives `{ op, endpoint, reason }`. A throw from it is ignored. A string or an existing pool is one endpoint and serves either `route` from it, and it has no `using`.
+
+The watermark is one value for the whole `connect()`. The root, `for()`, `unscoped()`, `using()`, and `reserve()` share it. A write through any of them moves it for the others. A watermark per `for()` client is not in this version.
+
+When replicas are configured and consistency is `"session"`, a committed write reads `pg_current_wal_insert_lsn()` before its promise resolves. That is one extra round trip: on the primary pool after an autocommit `execute` or `batch`, and on the reserved connection after a successful `COMMIT`. A rollback does not read it. `"eventual"`, and a connect with no replicas, do not read it either.
+
+`routing.select` picks among the replicas that passed health, the watermark, and `maxLag`. The default is `"weighted"`. `weighted` is smooth weighted round-robin. Equal weights take turns. A weight of `0` is rejected. `roundRobin` ignores weights and rotates through the eligible replicas. `leastConnections` uses the replica with the fewest statements already in flight on this client. A tie follows configuration order. `latencyAware` uses the replica with the lowest moving average of round-trip time. A function receives each candidate as `{ name, weight, inflight, latencyMs, lag }` and `{ op: "read" }`. `lag` is the number of bytes the replica is behind the primary, or `null` when that distance is unknown. The function returns one of those objects or its `name`. It runs only when an automatic read has two or more candidates.
+
+A write, a batch, a transaction, or a locking read on a replica route is OKM1840. `route: "replica"` or `using("replica")` with no eligible replica is OKM1843, including a topology with no replicas. An automatic read with `routing.fallback: "error"` and no eligible replica is OKM1844. A migrate target that carries `primary`, `replicas`, `weight`, or `pool` is OKM1845. Waiting for a connection past `timeouts.acquire` is OKM1846, and that wait stays on the endpoint's own pool. The rules are in [topology](https://github.com/omqkhafi/okmodel/blob/main/docs/topology.md).
+
+A replica whose pool is at its maximum, with no idle connection and callers waiting, is skipped. If every replica that can serve the read is in that state, the read uses the primary and `onRoute` reports `fallback:saturated`. When healthy replicas exist and none has caught up, or none is inside `maxLag`, the reason is `fallback:behind`. `route: "replica"` still uses a saturated replica, and it still requires the watermark and `maxLag`.
+
+`replicas.ts`:
+
+```ts
+import { connect } from "okmodel/pg/postgresjs";
+
+import schema from "./schema.ts";
+
+const url = process.env.DATABASE_URL;
+if (url === undefined || url.length === 0) throw new Error("DATABASE_URL is not set");
+const east = process.env.REPLICA_URL;
+if (east === undefined || east.length === 0) throw new Error("REPLICA_URL is not set");
+const west = process.env.REPLICA_URL_WEST ?? east;
+
+const endpoints = {
+  primary: url,
+  replicas: [{ url: east, weight: 2, name: "east" }, west],
+};
+
+const db = await connect(endpoints, {
+  schema,
+  routing: { probe: "1s", fallback: "primary", consistency: "session", select: "weighted" },
+  onRoute(event) {
+    // { op: "read", endpoint: "east", reason: "auto:east" }
+    void event;
+  },
+});
+
+await db.notes.find({ limit: 50 });
+await db.notes.find({ limit: 50, route: "primary" });
+await db.notes.find({ limit: 50, route: "replica" });
+const replica = db.using("replica");
+await replica.notes.find({ limit: 50 });
+await db.close();
+
+const eventual = await connect(endpoints, {
+  schema,
+  routing: { consistency: "eventual" },
+});
+await eventual.notes.find({ limit: 50 });
+await eventual.close();
+
+for (const select of ["roundRobin", "leastConnections", "latencyAware"] as const) {
+  const client = await connect(endpoints, { schema, routing: { select } });
+  await client.notes.find({ limit: 1 });
+  await client.close();
+}
+
+const custom = await connect(endpoints, {
+  schema,
+  routing: {
+    select(candidates) {
+      return candidates[0] ?? "east";
+    },
+  },
+});
+await custom.notes.find({ limit: 1 });
+await custom.close();
+```
+
+### Reference app
+
+The worked example is a project tracker: workspaces as tenants, archive, a function, two views, three generated migrations, and this topology. It is a private package in the repository, not on npm. CI runs it on the primary and two standbys. Board reads go to a replica. A read just after a write, with replay paused, comes back from the primary. The report uses `route: "replica"`. See the [example app](https://github.com/omqkhafi/okmodel/blob/main/docs/example-app.md) and the [reference app notes](https://github.com/omqkhafi/okmodel/blob/main/packages/reference-app/README.md).
+
+### Startup
+
+`connect()` compares the app with `okm_history`. A database that is ahead by expand migrations still opens. Ahead by a contract migration, or behind the app, is OKM1520 and names the migration. `okm migrate status` prints the same states, plus `failed at step N (resume with okm migrate apply)`.
+
+### Protected targets
+
+`protected: true` is a flag on the target, not on the name and not on `NODE_ENV`. Plan, status, check, ext check, and drift stay allowed. Expand and reference rows stay allowed. An empty protected database can be provisioned. Contract, unclassified SQL, push, backfill, and seed are OKM1850 unless that invocation passes `--allow-protected`. `okm migrate check` writes a scratch schema, so it stays refused, and the flag does not apply. Point it at a throwaway Postgres. Protection does not affect `connect()`.
+
 ## Commands
 
-| Command                   | What it does                                                                                                                 |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `okm build`               | Validates the schema and writes `.okm/` (catalog, hash, emitted row types). `okm generate` writes those files too.           |
-| `okm check`               | Reports a stale `renamedFrom` and a table file the schema does not import.                                                   |
-| `okm generate [name]`     | Writes a SQL migration and `.okm/`. The name defaults to `migration`. Prints `no changes` when the schema matches.           |
-| `okm dev`                 | Uses a target named `dev`, or creates a PGlite database in `.okm/dev-db`. It does not apply migrations or write the catalog. |
-| `okm push`                | Applies the schema directly. Refused when the target is protected.                                                           |
-| `okm migrate plan <name>` | Prints the plan and its class. The name is required.                                                                         |
-| `okm migrate apply`       | Replays migration files on the database.                                                                                     |
-| `okm migrate status`      | Prints version, catalog hash, and state for each target.                                                                     |
-| `okm ext list`            | Prints the extensions the connected server can install and the version that is installed.                                    |
-| `okm ext check`           | Compares those versions with the schema. A missing extension is OKM1811. A pin the server does not meet is OKM1812.          |
-| `okm doctor [code]`       | Lists the triggers on each table. A code argument prints that code.                                                          |
-| `okm --version`           | Prints the package version.                                                                                                  |
+| Command                   | What it does                                                                                                                                                                                             |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `okm build`               | Validates the schema and writes `.okm/`. Does not connect.                                                                                                                                               |
+| `okm check`               | Lints the schema and, after `okm_meta` exists, compares the database. Drift is OKM1520. Allowed on a protected target.                                                                                   |
+| `okm generate [name]`     | Writes a SQL migration and `.okm/`. Prints lint findings and still writes the file. Offline.                                                                                                             |
+| `okm dev`                 | Opens a PGlite database in `.okm/dev-db`, or a target named `dev`. It does not apply migrations.                                                                                                         |
+| `okm push`                | Applies the schema directly. OKM1850 on a protected target unless `--allow-protected`.                                                                                                                   |
+| `okm migrate plan <name>` | Prints each step's class and lock, plus a row estimate when the target answers. Read-only on a protected target. An error finding exits non-zero.                                                        |
+| `okm migrate apply`       | Installs the head snapshot on an empty database, or runs pending files. Expand is allowed on a protected target. Contract, unclassified SQL, and backfill need `--allow-protected`.                      |
+| `okm migrate check`       | Replays the history in a scratch schema and checks the previous catalog, the head, and the linter. Prints `ok N migrations`. Refused on a protected target, and `--allow-protected` does not apply.      |
+| `okm migrate status`      | Prints version, catalog hash, and state. Read-only on a protected target. An unfinished backfill is listed under the table.                                                                              |
+| `okm seed <file>`         | Runs the file's default export against the migrated target. OKM1850 on a protected target unless `--allow-protected`.                                                                                    |
+| `okm ext list`            | Prints extensions the server can install. Read-only on a protected target.                                                                                                                               |
+| `okm ext check`           | Compares installed extensions with the schema. OKM1811 if one is missing, OKM1812 if the pin is not met. Read-only on a protected target. `okm ext test` and `okm ext scaffold` are not in this version. |
+| `okm doctor [code]`       | Lists triggers, or explains one error code. A role check is read-only on a protected target.                                                                                                             |
+| `okm --version`           | Prints the package version.                                                                                                                                                                              |
 
 `okmodel` and `okm` are the same command.
 
+## Check a history in CI
+
+`okm migrate check` is the command for a pipeline. It applies every migration into a scratch schema, plans each result back to that file's catalog, checks the previous catalog, requires the last catalog to match the schema, and lints the history. Success prints `ok N migrations`. A failure exits non-zero.
+
+Point it at a throwaway Postgres. A protected target is refused, and `--allow-protected` does not apply. `defineConfig({ lintFrom: "<migration id>" })` skips lint for files before that id, which is how a project adopts the linter without failing on old migrations. Apply still lints pending migrations only.
+
+The previous-catalog check is schema-level. It does not prove application behaviour. Tenant targets are not checked.
+
+```yaml
+name: migrate
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx okm migrate check
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
+```
+
+The config reads `DATABASE_URL`, and that target is not protected.
+
 ## Roadmap
 
 Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each release is a milestone.
@@ -906,8 +1142,8 @@ Status is on the [board](https://github.com/users/omqkhafi/projects/1). Each rel
 - [x] [0.1](https://github.com/omqkhafi/okmodel/milestone/1) — Schema, queries, and migrations on PostgreSQL, with postgres.js and PGlite.
 - [x] [0.2](https://github.com/omqkhafi/okmodel/milestone/2) — Hidden and sensitive fields, validation, traits, tenancy, archive and restore, richer relations, presets, transactions, and operators for JSON, arrays, ranges, and search.
 - [x] [0.3](https://github.com/omqkhafi/okmodel/milestone/3) — Extensions, domains, functions, triggers, views, roles, and grants.
-- [ ] [0.4](https://github.com/omqkhafi/okmodel/milestone/4) — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
-- [ ] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
+- [x] [0.4](https://github.com/omqkhafi/okmodel/milestone/4) — Safer migration plans, backfill, drift checks, provisioning, reference data, and a testing package.
+- [x] [0.5](https://github.com/omqkhafi/okmodel/milestone/5) — A primary with replicas, read routing, and a reference app.
 
 `okmodel/internal` has no stability promise. Names on that subpath can change or disappear in any release.
 
@@ -919,11 +1155,11 @@ Measured on this release.
 
 |                                              | Minified |   Gzip | Cold import |
 | -------------------------------------------- | -------: | -----: | ----------: |
-| Runtime entry                                |    5,288 |  2,026 |    1.794 ms |
-| App startup (10 tables, one find)            |   89,465 | 29,723 |   10.554 ms |
-| App startup, every 0.2 feature in use (full) |  119,940 | 39,123 |   12.663 ms |
+| Runtime entry                                |    5,288 |  2,026 |    2.347 ms |
+| App startup (10 tables, one find)            |   89,751 | 29,801 |   15.061 ms |
+| App startup, every 0.2 feature in use (full) |  120,132 | 39,162 |   15.956 ms |
 
-The full app has column tenancy, `archivable()`, `timestamps()`, validation rules, `one`, `many` and `manyThrough` relations, presets, and calls `include`, `page`, `aggregate`, `tx` and `batch`. A feature costs bytes only in an app that uses it: the full app is 30,475 minified and 9,400 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated.
+The full app has column tenancy, `archivable()`, `timestamps()`, validation rules, `one`, `many` and `manyThrough` relations, presets, and calls `include`, `page`, `aggregate`, `tx` and `batch`. A feature costs bytes only in an app that uses it: the full app is 30,381 minified and 9,361 gzip bytes above the plain one. The runtime entry and the plain app are gated. The full app is printed, not gated. The plain app's cold import on this sample is above the 15 ms local reference. That figure is printed and is not a gate.
 
 The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/blob/main/docs/size.md).
 
@@ -931,6 +1167,10 @@ The rest of the measurements are in [size](https://github.com/omqkhafi/okmodel/b
 
 - [Quickstart](https://github.com/omqkhafi/okmodel/blob/main/docs/quickstart.md)
 - [Production checklist](https://github.com/omqkhafi/okmodel/blob/main/docs/production.md)
+- [Linter](https://github.com/omqkhafi/okmodel/blob/main/docs/linter.md)
+- [Backfill](https://github.com/omqkhafi/okmodel/blob/main/docs/backfill.md)
+- [Provisioning](https://github.com/omqkhafi/okmodel/blob/main/docs/provisioning.md)
+- [Testing](https://github.com/omqkhafi/okmodel/blob/main/docs/testing.md)
+- [Topology](https://github.com/omqkhafi/okmodel/blob/main/docs/topology.md)
 - [Known limits](https://github.com/omqkhafi/okmodel/blob/main/docs/known-limits.md)
 - [Changelog](https://github.com/omqkhafi/okmodel/blob/main/changelog.md)
-- [Design spec](https://github.com/omqkhafi/okmodel/blob/main/docs/okmodel-api-design.md)

package/dist/contracts/catalog/document.d.ts

@@ -35,8 +35,12 @@ export declare function renameColumn(source: Catalog, change: {
 /**
  * Renames a table without renaming its constraints or indexes.
  *
- * Column, index, and constraint parents move to the new name. Expression text
- * that names the table is rewritten. Constraint and index names stay.
+ * Column, index, constraint, and trigger parents move to the new name, and
+ * edges that pointed at those objects move with them. Expression text that
+ * names the table is rewritten. Constraint and index names stay. A grant on
+ * the table, or on an identity sequence named `{table}_{column}_seq`, follows
+ * the name the schema will use. The planner emits the `RENAME` for a default
+ * name; a custom name is left as it is.
  *
  * @param source - Catalog document
  * @param change - Namespace, current table name, and the new name
@@ -58,6 +62,26 @@ export declare function serializeCatalog(source: Catalog): string;
  * @returns Lowercase hex digest
  */
 export declare function catalogHash(source: Catalog): string;
+/**
+ * The catalog `connect()` compares with `okm_meta` (D208).
+ *
+ * Roles, grants, and default privileges come from the migration config, not
+ * the schema, so they are left out. A `schema()` catalog never has them, so
+ * `connect()` hashes it unchanged. `okm check` still verifies them. A
+ * catalog without them is returned as is.
+ *
+ * @param source - Catalog document
+ * @returns The catalog without role, grant, and default-privilege objects
+ */
+export declare function startupCatalog(source: Catalog): Catalog;
+/**
+ * {@link catalogHash} of {@link startupCatalog}. The hash `okm_meta` and
+ * `okm_history` store, and the one `connect()` computes.
+ *
+ * @param source - Catalog document
+ * @returns Lowercase hex digest
+ */
+export declare function startupHash(source: Catalog): string;
 /**
  * Loads a build artifact without validating objects.
  *

package/dist/contracts/driver.d.ts

@@ -61,6 +61,13 @@ export type ExecuteOptions = {
      * A deadline is kind `timeout`.
      */
     readonly timeout?: number;
+    /**
+     * Read routing hint.
+     *
+     * Drivers ignore it. A topology router reads it. Absent, the router
+     * classifies the statement.
+     */
+    readonly route?: "primary" | "replica";
 };
 /** Column names and parameter count from a describe. */
 export type DescribeResult = {

package/dist/dialects/pg/ext/citext.js

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/7fvtrkwr.js";
+} from "../../../shared/ycatkxmq.js";
 
 // src/dialects/pg/ext/citext.ts
 function citext(options = {}) {

package/dist/dialects/pg/ext/index.js

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/7fvtrkwr.js";
+} from "../../../shared/ycatkxmq.js";
 export {
   extension2 as extension
 };

package/dist/dialects/pg/ext/pg-trgm.js

@@ -1,6 +1,6 @@
 import {
   extension2
-} from "../../../shared/7fvtrkwr.js";
+} from "../../../shared/ycatkxmq.js";
 import {
   tag
 } from "../../../shared/cn0n68ft.js";

package/dist/dialects/pg/index.js

@@ -20,10 +20,10 @@ import {
   many2,
   manyThrough2,
   schema2
-} from "../../shared/x6wysh83.js";
+} from "../../shared/3p4b1fg0.js";
 import {
   domainType
-} from "../../shared/qbxzvwwc.js";
+} from "../../shared/g7ez901n.js";
 import {
   id2,
   uuid2
@@ -32,7 +32,7 @@ import {
   table2,
   index2,
   sql2
-} from "../../shared/6w5j844a.js";
+} from "../../shared/jsd07prz.js";
 import {
   text2,
   varchar2,

package/dist/dialects/pg/introspect.d.ts

@@ -39,6 +39,12 @@ export type CatalogQuery = {
  * @returns A checked catalog
  */
 export declare function introspectSchema(runner: CatalogQuery, concrete: string, logical?: string, options?: IntrospectOptions): Promise<Catalog>;
+/**
+ * A function's argument types as a grant names them, for `pg_proc p`.
+ *
+ * Types only, comma-separated, no spaces. Argument names are left out.
+ */
+export declare const FUNCTION_ARG_TYPES = "replace(oidvectortypes(p.proargtypes), ' ', '')";
 /**
  * Applies one expression as a check and reads Postgres's reprint.
  *

package/dist/dialects/pg/role/sql.d.ts

@@ -8,11 +8,16 @@ import type { CatalogObject } from "../../../contracts/catalog/types.js";
 /** Statements the planner inserts around the rest of the catalog. */
 export type PrivilegeSql = {
     /** Revokes, run while the objects still exist. */
-    readonly revoke: readonly string[];
+    readonly revoke: readonly PrivilegeStatement[];
     /** Role creates, role alters, and default privileges. Before new tables. */
-    readonly prepare: readonly string[];
+    readonly prepare: readonly PrivilegeStatement[];
     /** Grants on objects that exist, or that this plan creates first. */
-    readonly grant: readonly string[];
+    readonly grant: readonly PrivilegeStatement[];
+};
+/** One privilege statement and the planner kind it is. */
+export type PrivilegeStatement = {
+    readonly sql: string;
+    readonly kind: "revoke" | "revoke-default" | "create-role" | "alter-role" | "grant-default" | "grant";
 };
 /**
  * Diffs role, grant, and default-privilege objects into SQL.
@@ -25,9 +30,11 @@ export type PrivilegeSql = {
  * @param before - Previous catalog objects
  * @param after - Next catalog objects
  * @param schema - Concrete schema name
+ * @param recreated - Identity keys this plan drops and creates. Postgres drops
+ * grants with the object, so those grants are issued again after it exists
  * @returns Statements in three groups
  */
-export declare function privilegeSql(before: readonly CatalogObject[], after: readonly CatalogObject[], schema: string): PrivilegeSql;
+export declare function privilegeSql(before: readonly CatalogObject[], after: readonly CatalogObject[], schema: string, recreated?: ReadonlySet<string>): PrivilegeSql;
 /**
  * Role name in `create role`, when the statement is one.
  *
@@ -35,6 +42,16 @@ export declare function privilegeSql(before: readonly CatalogObject[], after: re
  * @returns The role, or `undefined` when the statement is not `CREATE ROLE`
  */
 export declare function createdRoleName(sql: string): string | undefined;
+/**
+ * Runs a plan's `CREATE ROLE` so a role another session created first is not an error.
+ *
+ * Roles belong to the cluster. Two databases provisioned at once both find the
+ * role absent, and the second `CREATE ROLE` fails on `pg_authid`.
+ *
+ * @param sql - A `CREATE ROLE` statement from the plan
+ * @returns The statement in a `DO` block that ignores a duplicate role
+ */
+export declare function createRoleOnce(sql: string): string;
 /**
  * Reports whether a statement creates or alters a role.
  *

package/dist/dialects/pg/schema.d.ts

@@ -144,6 +144,13 @@ type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
     readonly "~insert": InsertFrom<TFields>;
     readonly "~update": UpdateFrom<TFields>;
 } & HasArchive<TTraits> & PresetsOfList<TTraits>;
+/**
+ * `~views` when `schema({ views })` declared any, so `db.views` is typed.
+ * Nothing at runtime carries the key.
+ */
+type SchemaViews<TViews extends readonly unknown[]> = TViews extends readonly [] ? unknown : {
+    readonly "~views": TViews;
+};
 /**
  * Compiles tables into a catalog.
  *
@@ -156,19 +163,21 @@ type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
  */
 export declare function schema<const TTables extends readonly AnyTable[], const TTraits extends readonly {
     readonly fields: Readonly<Record<string, object>>;
-}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation"> & {
+}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined, const TViews extends readonly unknown[] = readonly []>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation" | "views"> & {
     readonly traits: TTraits;
     readonly tenancy?: TTenancy;
     readonly validation?: TValidation;
-}): [TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
+    readonly views?: TViews;
+}): ([TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
     readonly "~validation": TValidation;
-};
-export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation"> & {
+}) & SchemaViews<TViews>;
+export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined, const TViews extends readonly unknown[] = readonly []>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation" | "views"> & {
     readonly tenancy?: TTenancy;
     readonly validation?: TValidation;
-}): [TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
+    readonly views?: TViews;
+}): ([TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
     readonly "~validation": TValidation;
-};
+}) & SchemaViews<TViews>;
 /**
  * Registers a hook from an opt-in module.
  *

package/dist/dialects/pg/table.d.ts

@@ -112,7 +112,13 @@ export type TableOptions<TColumns> = {
      */
     readonly presets?: PresetMap<RowFrom<TColumns>>;
     readonly policies?: unknown;
-    readonly reference?: unknown;
+    /**
+     * Rows the application requires to exist.
+     *
+     * Apply inserts a row when its key is missing. It does not update or delete.
+     * The rows stay on the schema. They are not a diff in the catalog.
+     */
+    readonly reference?: ReferenceOption;
     /** `one` and `many`. Other relation kinds stay reserved. */
     readonly relations?: unknown;
 };
@@ -207,6 +213,16 @@ export type InsertFrom<TColumns> = {
 export type UpdateFrom<TColumns, TKey extends string = never> = {
     readonly [K in keyof TColumns as K extends TKey ? never : ColumnUpdateOf<TColumns[K]> extends never ? never : K]: ColumnUpdateOf<TColumns[K]>;
 };
+/**
+ * Rows declared with the table option `reference`.
+ *
+ * `key` is one column name or several, in constraint order. `rows` are the
+ * values apply inserts when that key is absent.
+ */
+export type ReferenceOption = {
+    readonly key: string | readonly string[];
+    readonly rows: readonly Readonly<Record<string, string | number | boolean | null>>[];
+};
 /**
  * Declares a table.
  *