okmodel 0.7.0 → 0.9.0

package/README.md

@@ -135,6 +135,20 @@ export async function removeNote(id: string) {
 
 `okm push` is for a database you can recreate. A shared database uses reviewed migrations: `okm generate init`, then `okm migrate apply`.
 
+## 0.9
+
+This release is the tooling train. `okm pull` writes schema files from a database. `okm import drizzle` writes them from a Drizzle schema. Several catalogs share one database through `external()` and `okm catalog export`. `describe` and `buildCatalog` are on `okmodel/migrate`. Extension packs cover `unaccent`, `hstore`, `ltree`, `btree_gist`, `btree_gin`, `fuzzystrmatch`, and `pgcrypto`. The GitHub Action posts the migration plan on a pull request. A type change that rewrites a table is five migrations, not one `ALTER COLUMN … TYPE`.
+
+| Want…                   | Go to                                                                  |
+| ----------------------- | ---------------------------------------------------------------------- |
+| Pull a database         | [pull](https://okm.omqkhafi.dev/docs/reference/cli#pull)               |
+| Import Drizzle          | [From Drizzle](https://okm.omqkhafi.dev/docs/start/from-drizzle)       |
+| Several catalogs        | [Catalogs](https://okm.omqkhafi.dev/docs/define/schema/catalogs)       |
+| `describe`              | [Schema API](https://okm.omqkhafi.dev/docs/reference/schema-api)       |
+| Extension packs         | [Extensions](https://okm.omqkhafi.dev/docs/define/schema/extensions)   |
+| The GitHub Action       | [GitHub Action](https://okm.omqkhafi.dev/docs/reference/github-action) |
+| A rewriting type change | [Type change](https://okm.omqkhafi.dev/docs/reference/type-change)     |
+
 ## Next
 
 | Want…                       | Go to                                                                                    |

package/dist/adapters/capabilities.d.ts

@@ -78,6 +78,38 @@ export declare const BUNSQL_CAPABILITIES: {
     readonly prepared: "unnamed";
     readonly describe: false;
 };
+/**
+ * Neon WebSocket pool execution flags.
+ *
+ * Interactive transactions pass on a direct connection. `stream`, `listen`,
+ * `cancel`, and `describe` stay false: a server cursor, `LISTEN`, and a
+ * side-channel cancel are session features the pooler does not keep, and the
+ * client has no describe API. Statements use the unnamed protocol.
+ * `prepared: "named"` is not for a transaction-mode pooler.
+ */
+export declare const NEON_WEBSOCKET_CAPABILITIES: {
+    readonly transactions: "interactive";
+    readonly stream: false;
+    readonly listen: false;
+    readonly cancel: false;
+    readonly prepared: "unnamed";
+    readonly describe: false;
+};
+/**
+ * Neon HTTP execution flags.
+ *
+ * One request is one statement. `sql.transaction` is the atomic batch.
+ * There is no interactive `tx()`, no `LISTEN`, no server cursor, and no
+ * cancel of a statement the server has already started.
+ */
+export declare const NEON_HTTP_CAPABILITIES: {
+    readonly transactions: "batch";
+    readonly stream: false;
+    readonly listen: false;
+    readonly cancel: false;
+    readonly prepared: "none";
+    readonly describe: false;
+};
 /**
  * Reads one capability flag.
  *

package/dist/adapters/failure.d.ts

@@ -22,7 +22,7 @@ export declare function rejectClosed(): Promise<never>;
 /**
  * Rejects with OKM1120 when a driver cannot cancel a positive timeout.
  *
- * The message stays `timeout`. Kind stays `invalid`. Bun.sql and PGlite call
+ * The message stays `timeout`. Kind stays `invalid`. Bun.sql, PGlite, and Neon call
  * this. Other drivers do not, so their connect graphs omit it.
  *
  * @returns A rejected promise

package/dist/adapters/pg/bun-sql.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The slice of Bun.sql this adapter uses.
+ *
+ * `bun` is the runtime, not an npm package, and it ships no types. The
+ * published declarations name these types instead of importing `bun`, so a
+ * consumer can typecheck `okmodel/pg/bun` without `bun-types`.
+ */
+/** A pending query. `raw()` asks for rows as arrays. */
+export interface SQLQuery extends Promise<unknown> {
+    /** Rows as arrays instead of objects. */
+    raw(): SQLQuery;
+}
+/** One pooled Bun.sql client. */
+export interface SQL {
+    /**
+     * Runs a statement.
+     *
+     * @param text - SQL text
+     * @param values - Positional parameters
+     */
+    unsafe(text: string, values?: readonly unknown[]): SQLQuery;
+    /**
+     * Checks out one connection.
+     *
+     * @param options - `signal` aborts the wait
+     */
+    reserve(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ReservedSQL>;
+    /** Closes the pool. */
+    close(): Promise<void>;
+    /**
+     * Subscribes to one `LISTEN` channel.
+     *
+     * @param channel - Channel name
+     * @param onnotify - Payload callback
+     */
+    listen(channel: string, onnotify: (payload: string) => void): Promise<SQLListen>;
+}
+/** A `LISTEN` registration. */
+export interface SQLListen {
+    /** Drops this registration. */
+    unlisten(): Promise<void>;
+}
+/**
+ * One connection reserved from {@link SQL.reserve}.
+ *
+ * `release` returns it to the pool.
+ */
+export interface ReservedSQL extends SQL {
+    /** Returns the connection to the pool. */
+    release(): void;
+}

package/dist/adapters/pg/bunsql-extra.d.ts

@@ -4,7 +4,7 @@
  * Loaded on the first reserve, batch, stream, or dead connection. A read that
  * succeeds does not use it.
  */
-import type { ReservedSQL, SQL } from "bun";
+import type { ReservedSQL, SQL } from "./bun-sql.js";
 import type { DriverConnection, WireValue } from "../../contracts/driver.js";
 import { type HeldPool } from "./bunsql.js";
 /**

package/dist/adapters/pg/bunsql.d.ts

@@ -9,7 +9,7 @@
  * finished script exits without `close()`. `Query.cancel()` does not abort
  * the backend, so `cancel` is false. Server notices are not surfaced.
  */
-import { SQL, type ReservedSQL } from "bun";
+import type { ReservedSQL, SQL } from "./bun-sql.js";
 import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
 import { DriverError } from "../error.js";
 import { noticeBuffer, type WireQuery } from "./session.js";

package/dist/adapters/pg/neon-extra.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reserved connections for the Neon WebSocket pool.
+ *
+ * Loaded on the first reserve or batch. A read does not use it.
+ */
+import type { DriverConnection } from "../../contracts/driver.js";
+import { type HeldPool } from "./neon.js";
+/**
+ * Checks out one client and clears it on release.
+ *
+ * A client whose connection is gone is destroyed on release, and nothing more
+ * is sent to it. A checked-out client has no pool error listener, so one is
+ * set here: without it a dropped socket is an uncaught `error` event.
+ *
+ * @param held - The pool and its counters
+ * @returns A connection the caller must release
+ */
+export declare function checkout(held: HeldPool): Promise<DriverConnection>;

package/dist/adapters/pg/neon.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Neon adapter (`okmodel/pg/neon`).
+ *
+ * `@neondatabase/serverless` is an optional peer. This module is the only
+ * place that imports it. `mode: "websocket"` (the default) is a pooled
+ * WebSocket client with interactive transactions. `mode: "http"` is one HTTP
+ * request per statement, and `batch` is the driver's non-interactive
+ * transaction. A positive `timeout` is refused: neither mode aborts a
+ * statement the server has already started.
+ *
+ * The first WebSocket `open` sets `webSocketConstructor` only when it is
+ * still unset, so a caller can install one first. A transaction-mode pooler
+ * does not promise session state. One small compute can reuse a backend, so
+ * a custom `SET`, `LISTEN`, or a prepared statement may still be visible.
+ */
+import { Pool, type PoolClient } from "@neondatabase/serverless";
+import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
+import { noticeBuffer, type WireQuery } from "./session.js";
+export { NEON_WEBSOCKET_CAPABILITIES as capabilities, NEON_HTTP_CAPABILITIES as httpCapabilities, hasCapability, readCapability, } from "../capabilities.js";
+export { DriverError } from "../error.js";
+/** How {@link open} talks to Neon. */
+export type NeonMode = "websocket" | "http";
+/** Options for {@link open}. */
+export type NeonConfig = DriverPoolConfig & {
+    /** Connection URL for this endpoint. */
+    readonly url: string;
+    /**
+     * `websocket` is a pooled WebSocket client. `http` is one-shot HTTP.
+     *
+     * Omitted means `websocket`.
+     */
+    readonly mode?: NeonMode;
+    /**
+     * Named prepared statements, or the unnamed protocol.
+     *
+     * Unnamed is the default. It stays valid behind a pooler in transaction mode.
+     * `prepared: "named"` is not for transaction-mode poolers. HTTP ignores it.
+     */
+    readonly prepared?: "named" | "unnamed";
+    /** Session search path for every WebSocket connection in the pool. */
+    readonly searchPath?: string;
+};
+/** Pool occupancy. */
+export type Counters = {
+    reserved: number;
+    busy: number;
+    reservedBusy: number;
+    waiting: number;
+};
+/** What a WebSocket checkout needs from the pool that opened it. */
+export type HeldPool = {
+    readonly pool: Pool;
+    readonly acquireMs: number | undefined;
+    readonly counters: Counters;
+    readonly notices: ReturnType<typeof noticeBuffer>;
+    readonly named: boolean;
+    readonly isClosed: () => boolean;
+};
+/** A client that can run one array-mode statement. */
+type Queryable = {
+    query(config: {
+        text: string;
+        values?: readonly WireValue[];
+        rowMode: "array";
+        types: typeof WIRE;
+        name?: string;
+    }): Promise<unknown>;
+};
+declare const WIRE: {
+    getTypeParser(): (value: string) => string;
+};
+/**
+ * Opens a Neon pool for one endpoint.
+ *
+ * WebSocket mode connects once before returning, so a later short acquire
+ * timeout measures the queue and not a cold start. HTTP mode does not open a
+ * socket.
+ *
+ * @param config - URL, mode, pool size, and acquire timeout
+ * @returns The pool
+ */
+export declare function open(config: NeonConfig): Promise<DriverPool>;
+/**
+ * Checks out one WebSocket client.
+ *
+ * The wait uses `timeouts.acquire`. A timeout is OKM1846 and does not keep the
+ * client.
+ *
+ * @param pool - Neon pool
+ * @param acquireMs - Wait ceiling, when one was set
+ * @param counters - Pool occupancy
+ * @returns The client
+ */
+export declare function connectClient(pool: Pool, acquireMs: number | undefined, counters: Counters): Promise<PoolClient>;
+/**
+ * Sends one statement and returns the driver's promise.
+ *
+ * @param runner - Pool or checked-out client
+ * @param text - SQL
+ * @param params - Wire parameters
+ * @param named - Use a named prepared statement
+ * @returns The pending result
+ */
+export declare function send(runner: Queryable, text: string, params: readonly WireValue[] | undefined, named: boolean): WireQuery;

package/dist/adapters/pg/no-inflight-timeout.d.ts

@@ -1,7 +1,7 @@
 /**
  * Refusal for a driver that cannot cancel an in-flight statement (D224).
  *
- * Bun.sql and PGlite refuse a positive `timeout`. The OKM1120 text loads with
+ * Bun.sql, PGlite, and Neon refuse a positive `timeout`. The OKM1120 text loads with
  * the lazy error module, so a connect entry does not carry it. Kind is
  * `invalid`, which separates it from kind `timeout`. `timeout: 0` still fails
  * immediately as kind `timeout`. `signal` is unchanged. postgres.js and

package/dist/contracts/error.d.ts

@@ -31,7 +31,7 @@ export type ColumnCode = (typeof COLUMN_CODES)[number];
  * These are spec §21 codes. They are a type only, so the runtime entry does
  * not gain a second registry.
  */
-export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
+export type QueryCode = "OKM1101" | "OKM1102" | "OKM1104" | "OKM1105" | "OKM1111" | "OKM1120" | "OKM1121" | "OKM1124" | "OKM1125" | "OKM1130" | "OKM1190" | "OKM1701" | "OKM1704" | "OKM1801" | "OKM1802" | "OKM1803" | "OKM1843";
 /** Kinds from spec §14, in category order. */
 export declare const ERROR_KINDS: readonly ["invalid", "not_null", "check", "foreign_key", "unique", "exclusion", "conflict", "not_found", "not_unique", "forbidden", "serialization", "deadlock", "lock_timeout", "timeout", "cancelled", "unavailable", "schema_drift", "driver", "read_only", "outcome_unknown"];
 /** One spec §14 kind. */

package/dist/dialects/pg/ext/btree-gin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `btree_gin` extension. `gin` stores a GIN operator class for scalar equality.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { IndexCall } from "../table.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `btree_gin` plus the methods the naming overlay selected. */
+export type BtreeGin = Extension & {
+    /**
+     * A GIN index with `int4_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gin(column: string): IndexCall;
+};
+/**
+ * Declares `btree_gin`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function btreeGin(options?: ExtensionOptions): BtreeGin;

package/dist/dialects/pg/ext/btree-gin.js

@@ -0,0 +1,20 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  usingIndex
+} from "../../../shared/h9811jjm.js";
+
+// src/dialects/pg/ext/btree-gin.ts
+function btreeGin(options = {}) {
+  const declared = extension2("btree_gin", options);
+  return {
+    ...declared,
+    gin(column) {
+      return usingIndex(column, "gin", "int4_ops");
+    }
+  };
+}
+export {
+  btreeGin
+};

package/dist/dialects/pg/ext/btree-gist.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `btree_gist` extension. `gist` stores a GiST operator class so an exclude constraint can use `=`.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { IndexCall } from "../table.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `btree_gist` plus the methods the naming overlay selected. */
+export type BtreeGist = Extension & {
+    /**
+     * A GiST index with `gist_int4_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gist(column: string): IndexCall;
+};
+/**
+ * Declares `btree_gist`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function btreeGist(options?: ExtensionOptions): BtreeGist;

package/dist/dialects/pg/ext/btree-gist.js

@@ -0,0 +1,20 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  usingIndex
+} from "../../../shared/h9811jjm.js";
+
+// src/dialects/pg/ext/btree-gist.ts
+function btreeGist(options = {}) {
+  const declared = extension2("btree_gist", options);
+  return {
+    ...declared,
+    gist(column) {
+      return usingIndex(column, "gist", "gist_int4_ops");
+    }
+  };
+}
+export {
+  btreeGist
+};

package/dist/dialects/pg/ext/call.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SQL fragments for an extension function or operator.
+ *
+ * The fragment is the whole predicate, the same way `fragment` is. Values
+ * are parameters. The schema and function names are quoted identifiers the
+ * generator wrote.
+ */
+import { type Fragment } from "../ops/fragment.js";
+/**
+ * `schema.fn(column, …) = schema.fn($1)`.
+ *
+ * @param schema - Install schema
+ * @param name - Function name
+ * @param value - Parameter
+ * @returns A where fragment
+ */
+export declare function fnEqualsArg(schema: string, name: string, value: string): Fragment;
+/**
+ * `schema.fn(column, $1) = $2::integer`.
+ *
+ * @param schema - Install schema
+ * @param name - Function name
+ * @param value - Text argument
+ * @param distance - Integer the function result must equal
+ * @returns A where fragment
+ */
+export declare function fnDistance(schema: string, name: string, value: string, distance: number): Fragment;
+/**
+ * `column <op> $1`, with an optional cast on the parameter.
+ *
+ * @param op - Operator token the generator wrote
+ * @param value - Parameter
+ * @param cast - SQL type to cast the parameter to, when the operator needs one
+ * @returns A where fragment
+ */
+export declare function opArg(op: string, value: string, cast?: string): Fragment;
+/**
+ * `schema.fn()` as the whole predicate.
+ *
+ * @param schema - Install schema
+ * @param name - Function name
+ * @returns A where fragment
+ */
+export declare function bareCall(schema: string, name: string): Fragment;
+/**
+ * `encode(schema.digest(column, $1), 'hex') = $2`.
+ *
+ * @param schema - Install schema
+ * @param algorithm - Digest algorithm, a parameter
+ * @param hex - Expected hex digest, a parameter
+ * @returns A where fragment
+ */
+export declare function digestEquals(schema: string, algorithm: string, hex: string): Fragment;

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

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

package/dist/dialects/pg/ext/feature.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Version gate for one extension feature (OKM1812).
+ *
+ * The factory reads the declared extension version. An omitted pin is
+ * unpinned: apply checks the server. A pin that still allows a version
+ * without the feature fails here, at the call, which is schema build when
+ * the schema file calls the method. The message names the feature, the
+ * extension version, and `minPostgres`.
+ */
+/** What a feature needs. */
+export type FeatureNeed = {
+    /** Extension the feature belongs to. */
+    readonly name: string;
+    /** Minimum extension version (`1.2`). */
+    readonly extension: string;
+    /** Minimum Postgres major. Named in the message. */
+    readonly postgres: number;
+};
+/**
+ * Refuses a pin that does not guarantee the feature.
+ *
+ * @param declared - `version` on the extension, when the caller set one
+ * @param feature - Feature name, such as `daitch_mokotoff`
+ * @param need - Versions the feature needs
+ */
+export declare function assertExtFeature(declared: string | undefined, feature: string, need: FeatureNeed): void;

package/dist/dialects/pg/ext/fuzzystrmatch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `fuzzystrmatch` extension. `levenshtein` compares edit distance. `daitchMokotoff` needs version 1.2 and PostgreSQL 16.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { Fragment } from "../ops/fragment.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `fuzzystrmatch` plus the methods the naming overlay selected. */
+export type Fuzzystrmatch = Extension & {
+    /**
+     * `levenshtein(column, value) = distance`.
+     *
+     * @param value - Text to compare
+     * @param distance - Edit distance the function must return
+     * @returns A where fragment
+     */
+    levenshtein(value: string, distance: number): Fragment;
+    /**
+     * `daitch_mokotoff(column) = daitch_mokotoff(value)`. Needs fuzzystrmatch 1.2 and PostgreSQL 16.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    daitchMokotoff(value: string): Fragment;
+};
+/**
+ * Declares `fuzzystrmatch`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function fuzzystrmatch(options?: ExtensionOptions): Fuzzystrmatch;

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

@@ -0,0 +1,33 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  assertExtFeature
+} from "../../../shared/kzgrnckd.js";
+import {
+  fnEqualsArg,
+  fnDistance
+} from "../../../shared/xqacq37x.js";
+
+// src/dialects/pg/ext/fuzzystrmatch.ts
+function fuzzystrmatch(options = {}) {
+  const declared = extension2("fuzzystrmatch", options);
+  const schema = declared.schema;
+  return {
+    ...declared,
+    levenshtein(value, distance) {
+      return fnDistance(schema, "levenshtein", value, distance);
+    },
+    daitchMokotoff(value) {
+      assertExtFeature(options.version, "daitch_mokotoff", {
+        name: "fuzzystrmatch",
+        extension: "1.2",
+        postgres: 16
+      });
+      return fnEqualsArg(schema, "daitch_mokotoff", value);
+    }
+  };
+}
+export {
+  fuzzystrmatch
+};

package/dist/dialects/pg/ext/hstore.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `hstore` extension. `hasKey` is `?`. `gin` and `gist` index an hstore column.
+ *
+ * Generated by scripts/ext-generate.ts. Do not edit.
+ * `minPostgres` for the base methods is 15. A feature
+ * a declared version lacks fails with OKM1812.
+ */
+import type { Fragment } from "../ops/fragment.js";
+import type { IndexCall } from "../table.js";
+import { type Extension, type ExtensionOptions } from "./index.js";
+/** `hstore` plus the methods the naming overlay selected. */
+export type Hstore = Extension & {
+    /**
+     * `column ? key`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    hasKey(value: string): Fragment;
+    /**
+     * A GIN index with `gin_hstore_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gin(column: string): IndexCall;
+    /**
+     * A GiST index with `gist_hstore_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gist(column: string): IndexCall;
+};
+/**
+ * Declares `hstore`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function hstore(options?: ExtensionOptions): Hstore;

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

@@ -0,0 +1,29 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  opArg
+} from "../../../shared/xqacq37x.js";
+import {
+  usingIndex
+} from "../../../shared/h9811jjm.js";
+
+// src/dialects/pg/ext/hstore.ts
+function hstore(options = {}) {
+  const declared = extension2("hstore", options);
+  return {
+    ...declared,
+    hasKey(value) {
+      return opArg("?", value);
+    },
+    gin(column) {
+      return usingIndex(column, "gin", "gin_hstore_ops");
+    },
+    gist(column) {
+      return usingIndex(column, "gist", "gist_hstore_ops");
+    }
+  };
+}
+export {
+  hstore
+};