okmodel 0.8.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/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
+};

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

@@ -6,6 +6,50 @@
  * object for its records.
  */
 import type { ExtensionObject } from "../../../contracts/catalog/types.js";
+/** One type the definition says the extension provides. */
+export type ExtensionType = {
+    readonly name: string;
+};
+/** One operator the definition says the extension provides. */
+export type ExtensionOperator = {
+    readonly name: string;
+    readonly left?: string;
+    readonly right?: string;
+    readonly result: string;
+};
+/** One function the definition says the extension provides. */
+export type ExtensionFunction = {
+    readonly name: string;
+    readonly args: readonly string[];
+    readonly returns: string;
+};
+/** One index method the definition says the extension provides. */
+export type ExtensionIndexMethod = {
+    readonly name: string;
+    readonly opclass?: string;
+};
+/**
+ * Types, operators, functions, and index methods a definition declares.
+ *
+ * `okm ext test` checks these against the connected server. They are not
+ * catalog objects and they do not change the catalog hash.
+ */
+export type ExtensionProvides = {
+    readonly types?: readonly ExtensionType[];
+    readonly operators?: readonly ExtensionOperator[];
+    readonly functions?: readonly ExtensionFunction[];
+    readonly indexMethods?: readonly ExtensionIndexMethod[];
+};
+/**
+ * Version floors for a definition.
+ *
+ * `postgres` is `>=15`. `version` is an exact pin or a `>=` floor.
+ * `okm ext test` checks both against the connected server (OKM1812).
+ */
+export type ExtensionRequires = {
+    readonly postgres?: string;
+    readonly version?: string;
+};
 /** Options on {@link extension}. */
 export type ExtensionOptions = {
     /** Exact pin (`1.6`) or a floor (`>=0.7`). Omitted means unpinned. */
@@ -18,6 +62,14 @@ export type ExtensionOptions = {
      * The default is `true`. A move of a non-relocatable extension is OKM1814.
      */
     readonly relocatable?: boolean;
+    /**
+     * Floors `okm ext test` checks. Not stored in the catalog record.
+     */
+    readonly requires?: ExtensionRequires;
+    /**
+     * Objects `okm ext test` checks. Not stored in the catalog record.
+     */
+    readonly provides?: ExtensionProvides;
 };
 /**
  * One declared extension.
@@ -30,6 +82,10 @@ export type Extension = {
     readonly schema: string;
     readonly relocatable: boolean;
     readonly version?: string;
+    /** Floors from {@link ExtensionOptions.requires}. Absent when omitted. */
+    readonly requires?: ExtensionRequires;
+    /** Objects from {@link ExtensionOptions.provides}. Absent when omitted. */
+    readonly provides?: ExtensionProvides;
     /**
      * Catalog records for this declaration.
      *

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * The `ltree` extension. `ancestorOf` is `@>` and `descendantOf` is `<@`. This is not the parent-column walk.
+ *
+ * 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";
+/** `ltree` plus the methods the naming overlay selected. */
+export type Ltree = Extension & {
+    /**
+     * `column @> path`. The column is an ancestor of `path`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    ancestorOf(value: string): Fragment;
+    /**
+     * `column <@ path`. The column is a descendant of `path`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    descendantOf(value: string): Fragment;
+    /**
+     * A GiST index with `gist_ltree_ops`.
+     *
+     * @param column - SQL column name
+     * @returns An index call whose expression is the `using` tail
+     */
+    gist(column: string): IndexCall;
+};
+/**
+ * Declares `ltree`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function ltree(options?: ExtensionOptions): Ltree;

package/dist/dialects/pg/ext/ltree.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/ltree.ts
+function ltree(options = {}) {
+  const declared = extension2("ltree", options);
+  return {
+    ...declared,
+    ancestorOf(value) {
+      return opArg("@>", value, "ltree");
+    },
+    descendantOf(value) {
+      return opArg("<@", value, "ltree");
+    },
+    gist(column) {
+      return usingIndex(column, "gist", "gist_ltree_ops");
+    }
+  };
+}
+export {
+  ltree
+};

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

@@ -1,6 +1,9 @@
 import {
   extension2
-} from "../../../shared/jgqj11w4.js";
+} from "../../../shared/6f0z3hzh.js";
+import {
+  usingIndex
+} from "../../../shared/h9811jjm.js";
 import {
   tag
 } from "../../../shared/cn0n68ft.js";
@@ -25,18 +28,6 @@ function pgTrgm(options = {}) {
     }
   };
 }
-function usingIndex(column, method, opclass) {
-  const quoted = `"${column.replaceAll('"', '""')}"`;
-  const call = {
-    columns: [column],
-    isUnique: false,
-    expression: `using ${method} (${quoted} ${opclass})`,
-    unique() {
-      return call;
-    }
-  };
-  return call;
-}
 export {
   pgTrgm
 };

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

@@ -0,0 +1,33 @@
+/**
+ * The `pgcrypto` extension. `digest` compares a hex digest. `fipsMode` needs version 1.4 and PostgreSQL 18.
+ *
+ * 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";
+/** `pgcrypto` plus the methods the naming overlay selected. */
+export type Pgcrypto = Extension & {
+    /**
+     * `encode(digest(column, algorithm), 'hex') = hex`.
+     *
+     * @param algorithm - Digest algorithm, such as `sha256`
+     * @param hex - Expected hex digest
+     * @returns A where fragment
+     */
+    digest(algorithm: string, hex: string): Fragment;
+    /**
+     * `fips_mode()` is true or false on the column's row. Needs pgcrypto 1.4 and PostgreSQL 18.
+     *
+     * @returns A where fragment
+     */
+    fipsMode(): Fragment;
+};
+/**
+ * Declares `pgcrypto`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function pgcrypto(options?: ExtensionOptions): Pgcrypto;

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

@@ -0,0 +1,33 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  assertExtFeature
+} from "../../../shared/kzgrnckd.js";
+import {
+  bareCall,
+  digestEquals
+} from "../../../shared/xqacq37x.js";
+
+// src/dialects/pg/ext/pgcrypto.ts
+function pgcrypto(options = {}) {
+  const declared = extension2("pgcrypto", options);
+  const schema = declared.schema;
+  return {
+    ...declared,
+    digest(algorithm, hex) {
+      return digestEquals(schema, algorithm, hex);
+    },
+    fipsMode() {
+      assertExtFeature(options.version, "fips_mode", {
+        name: "pgcrypto",
+        extension: "1.4",
+        postgres: 18
+      });
+      return bareCall(schema, "fips_mode");
+    }
+  };
+}
+export {
+  pgcrypto
+};

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

@@ -0,0 +1,26 @@
+/**
+ * The `unaccent` extension. `unaccent` folds accents on a text 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 Extension, type ExtensionOptions } from "./index.js";
+/** `unaccent` plus the methods the naming overlay selected. */
+export type Unaccent = Extension & {
+    /**
+     * `unaccent(column) = unaccent(value)`.
+     *
+     * @param value - Text to compare
+     * @returns A where fragment
+     */
+    unaccent(value: string): Fragment;
+};
+/**
+ * Declares `unaccent`.
+ *
+ * @param options - Schema and version pin
+ * @returns The extension object and its methods
+ */
+export declare function unaccent(options?: ExtensionOptions): Unaccent;

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

@@ -0,0 +1,21 @@
+import {
+  extension2
+} from "../../../shared/6f0z3hzh.js";
+import {
+  fnEqualsArg
+} from "../../../shared/xqacq37x.js";
+
+// src/dialects/pg/ext/unaccent.ts
+function unaccent(options = {}) {
+  const declared = extension2("unaccent", options);
+  const schema = declared.schema;
+  return {
+    ...declared,
+    unaccent(value) {
+      return fnEqualsArg(schema, "unaccent", value);
+    }
+  };
+}
+export {
+  unaccent
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Index tails for extension operator classes.
+ *
+ * The catalog index stores `using …`. The core index factory does not grow a
+ * `using` field. `pg_trgm` and the generated packs share this helper.
+ */
+import type { IndexCall } from "../table.js";
+/**
+ * Quotes one identifier the extension wrote, not a caller string from SQL.
+ *
+ * @param name - Identifier
+ * @returns A double-quoted identifier
+ */
+export declare function quotedIdent(name: string): string;
+/**
+ * An index call whose expression is a `using` tail.
+ *
+ * @param column - SQL column name
+ * @param method - Index method, such as `gin` or `gist`
+ * @param opclass - Operator class, such as `gin_trgm_ops`
+ * @returns The index call
+ */
+export declare function usingIndex(column: string, method: string, opclass: string): IndexCall;