@vibeorm/sql 4.3.0 → 5.0.0

package/dist/ast.d.ts

@@ -22,7 +22,13 @@ export type ColRef = {
      * `castText` renders a dialect text cast and preserves `alias ?? name`,
      * including timestamp identity before driver Date truncation. PostgreSQL
      * uses `"col"::text`; SQLite/MySQL use CAST AS TEXT/CHAR. `encodeBase64`
-     * is postgres-only and renders `encode("col", 'base64')`. Other users:
+     * is postgres-only and renders `encode("col", 'base64')`.
+     * `encodeArrayBase64` is postgres-only and renders
+     * `encode(array_send("col"), 'base64')` — a `bytea[]` column's binary array
+     * form (dimensions, NULL elements, raw element bytes) as base64: faithful
+     * whatever the session's `bytea_output`, keeping a NULL column (`NULL`), an
+     * empty array and NULL elements distinct (5.0 lane V; the lateral subselect's
+     * `Bytes[]` form, decoded by the runtime's JSON-transport plan). Other users:
      * the lateral subselect (SQL review B3: raw `to_jsonb` would ship BigInt/Decimal as float64 JSON
      * numbers and Bytes as `\x` hex text), and every row projection of a
      * `Float[]`/`Json[]` column (bun:sql's array parser refuses float arrays
@@ -30,7 +36,7 @@ export type ColRef = {
      * the runtime parses the array literal text itself). Never set on
      * filter/order refs.
      */
-    readonly transform?: "castText" | "encodeBase64" | "jsonText";
+    readonly transform?: "castText" | "encodeBase64" | "encodeArrayBase64" | "jsonText";
     /**
      * Comparison/order/aggregate cast, sqlite Decimal only (SQL review B4):
      * Decimal stores as exact TEXT there and text comparison is lexicographic —
@@ -456,7 +462,11 @@ export type OrderTerm = OrderByColumn | OrderByAggregate | OrderBySubquery;
 /**
  * One `LEFT JOIN LATERAL (…) AS alias ON true` clause aggregating a correlated
  * subquery into a single JSON value per outer row — the "join" relation-loading
- * strategy (postgres/pglite only; gated on `capabilities.lateralJoin`).
+ * strategy (postgres/pglite, and MySQL 8.0.14+ since lane J; gated on
+ * `capabilities.lateralJoin` and rendered through `SqlDialect.lateralJson`).
+ * MySQL renders positional rows only (`JSON_ARRAY`, `JSON_ARRAYAGG`, `ON
+ * true`); its aggregate cannot order, so an ordered list level carries a
+ * `select.rowNumber` without partition — rendered as the row's last slot.
  *
  * Renders (agg `jsonArray`):
  *   `LEFT JOIN LATERAL (SELECT COALESCE(json_agg(to_json("__sub".*)), '[]'::json)
@@ -694,6 +704,31 @@ export type KeyPage = {
     /** Output name of the rank column. */
     readonly rankAlias: string;
 };
+/**
+ * Statement-count pass EPIC 4 (round-3 ST-07): bound key tuples as the FROM
+ * of a select (`SelectStatement.fromKeys`) — a derived table named
+ * `table.name` whose columns are `columns`, one row per tuple. The write
+ * follow-up puts it where the parent table would be: the find path's laterals
+ * correlate to `"<table.name>"."<column>"` exactly as over the table, but read
+ * the RETURNED key values instead of the parent row (a deleted row, or a
+ * native-RLS parent whose SELECT policy the per-relation loads never met).
+ *
+ * Renders where `SqlDialect.keyListStrategy` is `unnest` (postgres) as the
+ * typed form of a `VALUES` list — one array per column, typed like the
+ * key-list filter's members (`postgresKeyListElementType`), so the text does
+ * not depend on the tuple count: `FROM unnest($1::text[], $2::int4[]) AS
+ * "Post" ("id", "authorId")`. A `DateTime` member without a declared native
+ * type (`keyListBindsUntypedRows`) and every other dialect refuse with
+ * `VIBE_UNSUPPORTED_CAPABILITY` — those dialects have no lateral joins either.
+ */
+export type KeyRows = {
+    /** Output column names of the derived table, in member order. */
+    readonly columns: readonly string[];
+    /** How each column binds, in column order — see {@link KeyListMember}. */
+    readonly members: readonly KeyListMember[];
+    /** Encoded tuples; never empty, each exactly `columns.length` long. */
+    readonly rows: readonly (readonly unknown[])[];
+};
 export type SelectStatement = {
     readonly kind: "select";
     readonly table: TableRef;
@@ -733,7 +768,7 @@ export type SelectStatement = {
      * by aggregate-over-a-subset shapes (`aggregate({ take, skip, orderBy })`).
      */
     readonly fromSelect?: SelectStatement;
-    /** Lateral JSON-aggregation joins — postgres-only, see {@link LateralJoin}. */
+    /** Lateral JSON-aggregation joins — postgres and MySQL 8.0.14+, see {@link LateralJoin}. */
     readonly lateralJoins?: readonly LateralJoin[];
     /** Plain equality INNER JOINs — portable, see {@link InnerJoin}. */
     readonly innerJoins?: readonly InnerJoin[];
@@ -762,6 +797,13 @@ export type SelectStatement = {
      * branch by branch, in text order.
      */
     readonly fromUnion?: readonly SelectStatement[];
+    /**
+     * Statement-count pass EPIC 4 (ST-07): derived-table FROM over bound key
+     * tuples, named `table.name` with the listed column names — see
+     * {@link KeyRows}. Never together with `fromSelect`, `keyPage`, `fromUnion`,
+     * a `table.alias` or a `rowLock`.
+     */
+    readonly fromKeys?: KeyRows;
     readonly where?: SqlExpr;
     readonly groupBy?: readonly ColRef[];
     /** HAVING predicate — grouped selects; may contain `aggCmp` expressions. */
@@ -797,6 +839,19 @@ export type RowLock = {
 export declare const SQL_DEFAULT_CELL: {
     readonly __sqlDefault: true;
 };
+/**
+ * Sentinel update-arm cell: the column keeps its current value —
+ * `` `col` = `table`.`col` `` (V8, the insert-if-missing upsert). Valid only in
+ * an {@link OnConflictUpdate} `update` set, where MySQL's `ON DUPLICATE KEY
+ * UPDATE` needs at least one assignment: a self-assignment changes nothing on a
+ * duplicate and, unlike `INSERT IGNORE`, leaves every other error an error.
+ * Refused in a plain UPDATE's SET list.
+ */
+export declare const SQL_KEEP_CELL: {
+    readonly __sqlKeep: true;
+};
+/** Is this update cell the {@link SQL_KEEP_CELL} sentinel? */
+export declare function isSqlKeepCell(value: unknown): boolean;
 /** Is this VALUES cell the {@link SQL_DEFAULT_CELL} sentinel? */
 export declare function isSqlDefaultCell(value: unknown): boolean;
 /**
@@ -925,11 +980,28 @@ export type OnConflictUpdate = {
 };
 /**
  * Conflicting rows are skipped (`createMany({ skipDuplicates: true })`).
- * An empty/absent target means "any conflict" — the mysql form (INSERT IGNORE)
- * can only express that, so it ignores a bare `columns` target (documented
- * degradation) and REFUSES the refined targets below.
+ * An empty/absent target means "any conflict" — the mysql form
+ * (`ON DUPLICATE KEY UPDATE k = t.k`, dialect `doNothingForm:
+ * "duplicateKeyKeep"`) can only express that, so it ignores a bare `columns`
+ * target (documented degradation) and REFUSES the refined targets below.
  */
 export type OnConflictDoNothing = {
+    /**
+     * MySQL form only (`duplicateKeyKeep`): the column the duplicate arm assigns
+     * to itself (`` `k` = `t`.`k` ``, a no-op). Absent = the first inserted
+     * column; an all-default row (no column) must name one.
+     */
+    readonly keepColumn?: string;
+    /**
+     * MySQL form only, single-row statements: a decimal literal S (digits only).
+     * The keep assignment becomes `` `k` = IF(LAST_INSERT_ID(S), `t`.`k`, `t`.`k`) ``,
+     * so a skipped duplicate reports S as the statement's insert id (an inserted
+     * row reports its own id, or 0) — the exact skipped verdict that the
+     * affected count cannot give with CLIENT_FOUND_ROWS (an unchanged duplicate
+     * counts 1, like an insert). The builder picks S unequal to the row's
+     * explicit AUTO_INCREMENT value.
+     */
+    readonly duplicateFlag?: string;
     readonly columns?: readonly string[];
     /**
      * Partial-index target predicate, RAW SQL: `ON CONFLICT (cols) WHERE pred
@@ -947,7 +1019,13 @@ export type OnConflictClause = OnConflictUpdate | OnConflictDoNothing;
 export type UpdateStatement = {
     readonly kind: "update";
     readonly table: TableRef;
-    /** Column → parameter value, or an atomic {@link SetOperation}. */
+    /**
+     * Column → parameter value, or an atomic {@link SetOperation}. As a
+     * {@link ChainStep} only (statement-maxx lane C3), a value may be a
+     * {@link StepColumnRef} to an EARLIER step: `"col" = (SELECT "c" FROM
+     * "step")` — the step must return at most one row (an owner resolved by a
+     * unique where, or an owner INSERT of one row).
+     */
     readonly set: Readonly<Record<string, unknown>>;
     readonly where?: SqlExpr;
     readonly returning?: readonly ReturningColumn[];
@@ -997,6 +1075,12 @@ export type RlsContextStatement = {
     readonly kind: "rlsContext";
     readonly context: RlsContextIR;
     readonly values: Readonly<Record<string, string | null>>;
+    /** PGlite: bind this trusted runtime role first, in the same statement. */
+    readonly role?: string;
+    /** Switch the transaction to READ ONLY in the same statement, after the claims. */
+    readonly readOnly?: boolean;
+    /** Report the backend as `"backendPid"` / `"backendStart"` text columns. */
+    readonly backend?: boolean;
 };
 /** Trusted pre-existing PGlite execution role; never a request-supplied principal. */
 export type RlsRoleStatement = {
@@ -1085,6 +1169,15 @@ export type InsertSelectStatement = {
      */
     readonly source?: ChainRowSource;
     readonly where?: SqlExpr;
+    /**
+     * `ON CONFLICT (<columns>) DO NOTHING` (statement-maxx lane C2): a row whose
+     * conflict target already exists is skipped and not returned — the implicit
+     * many-to-many join INSERT, where re-connecting an existing pair is a no-op.
+     * Postgres form only (the chain renders nowhere else); at least one column.
+     */
+    readonly conflictDoNothing?: {
+        readonly columns: readonly string[];
+    };
     readonly returning?: readonly ReturningColumn[];
 };
 /**

package/dist/codecs.d.ts

@@ -20,6 +20,7 @@
  * Database enums ride the String codec. String-backed enums use the field-bound
  * membership codec below; their wire values are still strings on every dialect.
  */
+import { VibeError } from "@vibeorm/schema";
 import type { Dialect, ScalarType } from "@vibeorm/schema";
 /**
  * One scalar type's transport rules for one dialect. Both directions see only
@@ -66,6 +67,23 @@ export type WireFidelity = {
     readonly json?: "parsed" | "text";
     /** Int/Float columns arrive as JS numbers (`"native"`) or as text (`"text"`). */
     readonly numbers?: "native" | "text";
+    /**
+     * Bytes columns arrive as Node `Buffer` instances (`"buffer"`: node-postgres,
+     * bun:sql); absent means a plain `Uint8Array` (PGlite). Never prunes a
+     * decoder: the runtime's JSON-transport plan reads it, so a `"join"`
+     * relation child's bytes (base64 on the wire) materialize in the same class
+     * the driver hands the `"query"` strategy — value identity (5.0 lane V).
+     */
+    readonly bytes?: "buffer";
+    /**
+     * Zone-less date-time text (MySQL DATETIME / TIMESTAMP / DATE) is read as a
+     * UTC instant by the driver (`"utc"`: mysql2 with `timezone: "Z"`). Absent
+     * means another or an unknown zone (another `timezone` option, an injected
+     * pool). Never prunes a decoder: the runtime reads it to decide whether a
+     * dialect default of `"join"` keeps value identity — the JSON transport
+     * decodes that text as UTC (`lateralJson.requiresUtcDateTimeWire`, lane J).
+     */
+    readonly zoneLessDateTime?: "utc";
 };
 /**
  * Is this scalar type's DECODE a no-op under the declared wire fidelity?
@@ -113,6 +131,32 @@ export declare function decodeIsNoop(params: {
 export declare function parseDateTimeText(params: {
     text: string;
 }): Date | undefined;
+/**
+ * PostgreSQL date/time text with a year of five or more digits or a ` BC` era,
+ * in the row text form and the JSON form: `12345-06-07 08:09:10.111+00`,
+ * `12345-06-07T08:09:10.111` (zone-less), `0044-03-15T12:00:00.5+00:00 BC`,
+ * `0044-03-15 BC` (`date`). ECMA-262 parses none of them (an expanded year
+ * needs `+012345`), and a value near the end of year 9999 reaches them
+ * through the session zone alone (`9999-12-31 23:59+00` prints as
+ * `10000-01-01 00:59+01` east of UTC). Built from its fields, by the rules of
+ * {@link parseDateTimeText}: the BC year astronomically (`1 BC` = year 0, the
+ * reading of node-postgres), zone-less text as UTC, the fraction truncated to
+ * milliseconds, an offset with seconds applied exactly.
+ *
+ * `undefined` for every other text — a 4-digit AD value keeps the parse it
+ * had — and for an instant outside the `Date` range. Exported for the adapters
+ * whose zone-less driver parsers fall back to it (one rule, rule 6).
+ */
+export declare function parseExtendedDateTimeText(params: {
+    text: string;
+}): Date | undefined;
+/**
+ * The decode refusal of a non-finite or unparseable DateTime — one error for
+ * every DateTime codec. Exported so a statement that refuses such a value
+ * itself (the runtime's in-statement value guard, round-trip follow-up D1)
+ * reports exactly this error.
+ */
+export declare function decodedDateTimeRefusal(): VibeError;
 /**
  * The time-of-day codec for a DateTime field's native type, or `undefined`
  * when the native type is not `time`/`timetz` (the DateTime table row

package/dist/dialect.d.ts

@@ -167,6 +167,51 @@ export type SqlDialect = {
      * `ROW_NUMBER()` window (MySQL: a lateral page still read every child).
      */
     readonly keyPageStrategy: "lateral" | "inLimit" | "window";
+    /**
+     * How the `"join"` relation strategy's lateral subselects build their JSON
+     * payload (`LateralJoin`), or `null` where the dialect has no LATERAL
+     * (`capabilities.lateralJoin` false). `rowArray` builds one positional row,
+     * `arrayAgg` aggregates the rows, `emptyArray` is the payload of a list
+     * level without rows. `order` says how a list level keeps its order:
+     * `"inAggregate"` — the aggregate takes the ORDER BY itself (postgres
+     * `json_agg(… ORDER BY …)`); `"positionSlot"` — the aggregate cannot order
+     * (MySQL `JSON_ARRAYAGG` has no ORDER BY and documents its element order as
+     * undefined), so an ordered level projects a `ROW_NUMBER()` position as
+     * its last positional slot and the runtime sorts the children by it.
+     * MySQL needs 8.0.14 or later (LATERAL and outer references in derived
+     * tables); MariaDB has no LATERAL.
+     */
+    readonly lateralJson: {
+        readonly rowArray: string;
+        readonly arrayAgg: string;
+        readonly emptyArray: string;
+        readonly order: "inAggregate" | "positionSlot";
+        /**
+         * Time-of-day values ride the payload as text (`CAST(… AS CHAR)`, the
+         * query path's form): MySQL 8.4.11 prints a TIME beyond a day inside JSON
+         * wrapped modulo 24 hours (`838:59:59` → `"06:59:59.000000"`), which would
+         * turn the query strategy's refusal into a wrong value.
+         */
+        readonly timeOfDayAsText: boolean;
+        /**
+         * Zone-less date-times (MySQL DATETIME / TIMESTAMP / DATE) ride the
+         * payload as the session's zone-less text, which the JSON transport
+         * decodes as UTC, while the query strategy's driver reads the same text
+         * in ITS configured zone (mysql2 `timezone`). `true`: the dialect default
+         * (`relationStrategyDefault`) joins only on an adapter whose wire declares
+         * `zoneLessDateTime: "utc"`; an explicit `"join"` is unaffected. `false`
+         * where every adapter pins zone-less values to UTC (postgres).
+         */
+        readonly requiresUtcDateTimeWire: boolean;
+    } | null;
+    /**
+     * The relation strategy a client uses when neither the call nor the client
+     * option names one (5.0 rule D-2). `"join"` only where `lateralJoin` holds.
+     * On MySQL (lane J, wave 3b) the runtime still loads `"query"` until the
+     * adapter knows its server runs LATERAL and declares a UTC date-time wire
+     * (`serverLateralJoins` in the runtime).
+     */
+    readonly relationStrategyDefault: "join" | "query";
     /**
      * Fix lane Q1 (round 3, DB-03): how a positive relation filter that pins ONE
      * related row by a unique key renders. `exists`: the correlated `EXISTS` —
@@ -241,11 +286,14 @@ export type SqlDialect = {
     };
     /**
      * Skip-conflicting-rows form. `onConflictDoNothing` appends
-     * `ON CONFLICT [(target)] DO NOTHING`; `insertIgnore` turns the statement into
-     * `INSERT IGNORE INTO` — which ignores a wider class of errors than a pure
-     * duplicate-key skip (see the catalog case).
+     * `ON CONFLICT [(target)] DO NOTHING`; `duplicateKeyKeep` appends
+     * `ON DUPLICATE KEY UPDATE k = t.k` — a self-assignment that skips ANY
+     * duplicate key and, unlike `INSERT IGNORE` (never emitted: it also turns NOT
+     * NULL, out-of-range and foreign-key errors into warnings), leaves every other
+     * error an error. A duplicate takes the update arm, so the table's UPDATE
+     * triggers fire (nothing changes).
      */
-    readonly doNothingForm: "onConflictDoNothing" | "insertIgnore";
+    readonly doNothingForm: "onConflictDoNothing" | "duplicateKeyKeep";
     /** Case-insensitive LIKE: native ILIKE or LOWER(col) LIKE LOWER(pattern). */
     readonly insensitiveLike: "ilike" | "lower";
     /**

package/dist/dialects/migration-inventory.d.ts

@@ -1,5 +1,16 @@
 import type { SqlDialect } from "../dialect.ts";
 import type { RenderedQuery } from "../render.ts";
+/**
+ * Ends a MySQL catalog listing whose row count has no small bound (the
+ * migration inventory, the visibility proof). `sql_select_limit` (session or
+ * global, e.g. 1 000 under `mysql --safe-updates`) silently cuts the rows of a
+ * SELECT without its own LIMIT, and a cut listing reads its last objects (or
+ * grants) as missing; an explicit LIMIT takes precedence over it. After the
+ * last `UNION` branch (and its ORDER BY) the LIMIT applies to the whole union.
+ * The value is MySQL's largest row count, so nothing is ever cut. The batched
+ * object readers end the same way (`migration-objects.ts`, LEFTOVERS-01).
+ */
+export declare const MYSQL_NO_ROW_LIMIT: string;
 /** SQLite column metadata includes generated columns omitted by table_info. */
 export declare function renderSqliteColumnInventory(params: {
     dialect: SqlDialect;
@@ -12,11 +23,57 @@ export declare function renderSqliteForeignKeyInventory(params: {
     namespace: string;
     table: string;
 }): RenderedQuery;
+/**
+ * {@link renderSqliteColumnInventory} for many tables in one statement. Rows
+ * carry `vibe_request` = the table's index in `tables`, then the single query's
+ * columns in its order (`cid`). The table-valued pragma runs the same PRAGMA
+ * per table, with the same namespace argument. Every table answers at least one
+ * row (`LEFT JOIN`): one whose `name` is NULL when its PRAGMA has no rows, so a
+ * table missing from the answer was not read.
+ */
+export declare function renderSqliteColumnInventoryBatch(params: {
+    dialect: SqlDialect;
+    namespace: string;
+    tables: readonly string[];
+}): RenderedQuery;
+/** {@link renderSqliteForeignKeyInventory} for many tables in one statement; rows as in {@link renderSqliteColumnInventoryBatch} (no-row marker: `id` NULL), ordered `id, seq` per table. */
+export declare function renderSqliteForeignKeyInventoryBatch(params: {
+    dialect: SqlDialect;
+    namespace: string;
+    tables: readonly string[];
+}): RenderedQuery;
+/** A PRAGMA SQLite introspection reads once per table (`table_xinfo`, `index_list`, `foreign_key_list`) or per index (`index_xinfo`). */
+export type SqliteIntrospectionPragma = "table_xinfo" | "index_list" | "index_xinfo" | "foreign_key_list";
+/**
+ * `PRAGMA <pragma>("<name>")` for every name in one statement. Rows carry
+ * `vibe_request` = the name's index in `names`, then exactly the PRAGMA's own
+ * columns (a table-valued pragma's hidden `arg`/`schema` columns are not in
+ * `p.*`), per name in the order the PRAGMA emits them. No schema argument, as
+ * in the single statement: the table-valued pragma runs `PRAGMA <pragma>='name'`
+ * internally, with the same temp-then-main name lookup.
+ *
+ * Literal text with no bound values, like every statement SQLite introspection
+ * sends (the names list is one quoted string literal): an executor that runs a
+ * value-less statement without binding anything reads the same rows.
+ *
+ * Every name answers at least one row (`LEFT JOIN`): a name whose PRAGMA has no
+ * rows answers one row whose PRAGMA columns are all NULL, so a name missing
+ * from the answer was not read (and an empty answer is never "no rows").
+ */
+export declare function renderSqliteIntrospectionPragmaBatch(params: {
+    dialect: SqlDialect;
+    pragma: SqliteIntrospectionPragma;
+    names: readonly string[];
+}): RenderedQuery;
 /** Exact SQL needed to restore independently existing indexes and triggers during a rebuild. */
 export declare function renderSqliteRebuildObjects(params: {
     dialect: SqlDialect;
 }): RenderedQuery;
-/** Enumerate scoped catalog identities, including constraints and their backing indexes. */
+/**
+ * Enumerate scoped catalog identities, including constraints and their backing
+ * indexes. The MySQL listing ends with {@link MYSQL_NO_ROW_LIMIT}, so
+ * `sql_select_limit` cannot drop objects from it.
+ */
 export declare function renderMigrationInventory(params: {
     dialect: SqlDialect;
     namespace: string;

package/dist/dialects/migration-objects.d.ts

@@ -11,6 +11,42 @@ export declare function renderMysqlObjectMembers(params: {
     dialect: SqlDialect;
     identity: SqlObjectIdentity;
 }): RenderedQuery | undefined;
+/**
+ * One batched MySQL catalog read. Its rows carry `vibe_position` = i, the
+ * branch that answers for request position `positions[i]`; member reads also
+ * carry `vibe_ordinal`, the single query's ORDER BY column.
+ */
+export type MysqlObjectBatch = RenderedQuery & {
+    readonly positions: readonly number[];
+};
+/**
+ * MySQL facts reads in bounded statements, grouped by query shape in request
+ * order, 100 objects per statement. Each `UNION ALL` branch is the UNCHANGED
+ * single-object query as a derived table, so the server matches names with the
+ * single read's own `WHERE` and collation: the rows of a position are exactly the
+ * rows {@link renderMigrationObjectQuery} returns for it. An identity MySQL cannot
+ * inspect is in no batch; the caller reads it on its own (and gets its refusal).
+ * The statement ends with `LIMIT 18446744073709551615`, so `sql_select_limit`
+ * cannot cut it.
+ */
+export declare function renderMysqlObjectBatch(params: {
+    dialect: SqlDialect;
+    identities: readonly SqlObjectIdentity[];
+}): readonly MysqlObjectBatch[];
+/**
+ * MySQL member reads (function parameters, index and constraint columns) in
+ * bounded statements, grouped by kind in request order, 100 objects per
+ * statement. Each branch is the single member query's select list and `WHERE`
+ * plus its ORDER BY column as `vibe_ordinal`; MySQL ignores an ORDER BY inside a
+ * union branch, so the statement orders by `vibe_position, vibe_ordinal` (then
+ * `LIMIT 18446744073709551615`, so `sql_select_limit` cannot cut it). Rows
+ * of a position equal {@link renderMysqlObjectMembers}' rows in its order
+ * whenever that object's ordinals are distinct; the caller checks that.
+ */
+export declare function renderMysqlObjectMembersBatch(params: {
+    dialect: SqlDialect;
+    identities: readonly SqlObjectIdentity[];
+}): readonly MysqlObjectBatch[];
 /** PostgreSQL dependency addresses are returned as server-owned strings, never guessed from SQL. */
 export declare function renderMigrationDependencies(params: {
     dialect: SqlDialect;

package/dist/dialects/migration-visibility.d.ts

@@ -1,6 +1,11 @@
 import type { SqlDialect } from "../dialect.ts";
 import type { RenderedQuery } from "../render.ts";
-/** Direct grants needed to enumerate MySQL objects without privilege-filtered omissions. */
+/**
+ * Direct grants needed to enumerate MySQL objects without privilege-filtered
+ * omissions. Ends with {@link MYSQL_NO_ROW_LIMIT}: a `sql_select_limit` below
+ * the grant count would otherwise cut grants and refuse a namespace whose
+ * grants are complete.
+ */
 export declare function renderMigrationVisibility(params: {
     dialect: SqlDialect;
     namespace: string;

package/dist/dialects/mysql.d.ts

@@ -7,8 +7,9 @@
  * - Upserts use ON DUPLICATE KEY UPDATE (no conflict-target refinement).
  * - OFFSET requires LIMIT → the documented huge-limit idiom.
  * - No NULLS FIRST/LAST → `col IS NULL` emulation terms.
- * - No `ON CONFLICT ... DO NOTHING` → `INSERT IGNORE`, which is broader: it
- *   downgrades other row-level errors to warnings too.
+ * - No `ON CONFLICT ... DO NOTHING` → `ON DUPLICATE KEY UPDATE k = t.k` (a
+ *   no-op self-assignment on ANY duplicate key). Never `INSERT IGNORE`, which
+ *   also downgrades NOT NULL, range and foreign-key errors to warnings.
  */
 import type { SqlDialect } from "../dialect.ts";
 export declare const mysqlDialect: SqlDialect;

package/dist/dialects/postgres-rls.d.ts

@@ -57,11 +57,26 @@ export declare function renderRlsPolicy(params: {
     policyName?: string;
     targetSchema?: "public" | "pg_temp";
 }): RenderedQuery;
-/** Every declared setting, parameterized in declaration order and transaction-local. */
+/**
+ * Every declared setting, parameterized in declaration order and transaction-local.
+ *
+ * Optional parts travel in the SAME statement (statement-count pass, EPIC 1-2);
+ * without them the text is exactly the claims statement:
+ * - `role` (PGlite): binds the trusted runtime role FIRST, as {@link renderRlsRole} does;
+ * - `readOnly`: switches the transaction to READ ONLY after the claims (`$all` on a
+ *   verified connection; PostgreSQL accepts this switch at any point of a transaction);
+ * - `backend`: reports the backend as `"backendPid"` / `"backendStart"` text columns,
+ *   the readiness catalog read's own expressions (adapters that name no connection object).
+ *
+ * A context with zero keys is accepted only when one of these parts is present.
+ */
 export declare function renderRlsContext(params: {
     dialect: SqlDialect;
     context: RlsContextIR;
     values: Readonly<Record<string, string | null>>;
+    role?: string;
+    readOnly?: boolean;
+    backend?: boolean;
 }): RenderedQuery;
 /** First transaction statement on eligible PGlite only; server roles are login roles. */
 export declare function renderRlsRole(params: {

package/dist/index.d.ts

@@ -40,8 +40,8 @@ export type { ResultDecoder, ResultReadDecoder, ResultParameterEncoder, ResultSc
  * lives in this package; see the root sql-catalog.md for the reviewable surface.
  */
 export { compileExclusion, renderExclusionSetup, renderExclusionDdl, renderExclusionCatalog, renderExclusionProbe } from "./exclusion.ts";
-export type { AdvisoryLockKey, AdvisoryLockStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, CountSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, TableRef, UpdateStatement, } from "./ast.ts";
-export { ADVISORY_LOCK_RESULT_COLUMN, CHAIN_VETO_PREFIX, CHAIN_VETO_TOKEN_PATTERN, SQL_DEFAULT_CELL, chainVetoToken, dbNowMarker, excludedRef, isDbNowMarker, isExcludedRef, isJsonParamCell, isListSetOperation, isSetOperation, isSqlDefaultCell, isStepColumnRef, jsonParamCell, returningColumnName, stepColumnRef, } from "./ast.ts";
+export type { AdvisoryLockKey, AdvisoryLockStatement, AggFn, AggRef, AggSelect, ChainResult, ChainRowSource, ChainStatement, ChainStep, ChainStepStatement, ChainTally, ChainVeto, ColRef, ComparisonOp, CountSubquery, DeleteStatement, ExcludedRef, InnerJoin, KeyListMember, KeyPage, KeyRows, KeyTableJoin, KeyTableMember, InsertSelectStatement, InsertStatement, ReturningColumn, JsonFilterOp, LateralJoin, LeftJoin, ListSetOperation, OnConflictClause, OnConflictDoNothing, OnConflictUpdate, OrderByAggregate, OrderByColumn, OrderBySubquery, OrderTerm, RowLock, RowNumberProjection, DbNowMarker, JsonParamCell, SelectExpr, SelectStatement, SetOperation, SetOperator, SqlExpr, SqlStatement, StepColumnRef, TableRef, UpdateStatement, } from "./ast.ts";
+export { ADVISORY_LOCK_RESULT_COLUMN, CHAIN_VETO_PREFIX, CHAIN_VETO_TOKEN_PATTERN, SQL_DEFAULT_CELL, SQL_KEEP_CELL, chainVetoToken, dbNowMarker, excludedRef, isDbNowMarker, isExcludedRef, isJsonParamCell, isListSetOperation, isSetOperation, isSqlDefaultCell, isSqlKeepCell, isStepColumnRef, jsonParamCell, returningColumnName, stepColumnRef, } from "./ast.ts";
 export type { AdvisoryLockFunctions, AdvisoryLockModeFunctions, RowLockSyntax, EmptyInsertSyntax, SqlDialect, } from "./dialect.ts";
 export { ADVISORY_KEY_BOUNDS, describeRowLock, renderAdvisoryLock, renderRowLockClause } from "./locks.ts";
 export { JSON_TRANSPORT, projectionOutputName } from "./json-transport.ts";
@@ -64,7 +64,7 @@ export { renderRowRule } from "./row-rules.ts";
 export type { RenderedRowRule, RowRuleStatement, RowRuleTriggerPlacement } from "./row-rules.ts";
 export type { PredicateModel, PredicateUsage } from "./predicate.ts";
 export { DIALECT_CAPABILITIES, MYSQL_CAPABILITIES, POSTGRES_CAPABILITIES, SQLITE_CAPABILITIES, } from "./capabilities.ts";
-export { DIALECT_CODECS, MYSQL_CODECS, POSTGRES_CODECS, SQLITE_CODECS, decodeIsNoop, enumMembershipCodec, float32Codec, localDateCodec, parseDateTimeText, parseJsonText, postgresArrayElementFromText, shortestFloat32, timeOfDayCodec, } from "./codecs.ts";
+export { DIALECT_CODECS, MYSQL_CODECS, POSTGRES_CODECS, SQLITE_CODECS, decodeIsNoop, decodedDateTimeRefusal, enumMembershipCodec, float32Codec, localDateCodec, parseDateTimeText, parseExtendedDateTimeText, parseJsonText, postgresArrayElementFromText, shortestFloat32, timeOfDayCodec, } from "./codecs.ts";
 export type { CodecTable, ScalarCodec, WireFidelity } from "./codecs.ts";
 export { renderExpr, renderFragment, renderProjection, renderStatement } from "./render.ts";
 export type { RenderedQuery } from "./render.ts";
@@ -87,9 +87,10 @@ export { renderMigrationHistoryQuery } from "./dialects/migration-history.ts";
 export { sqliteTableConstraints } from "./dialects/sqlite-constraints.ts";
 export type { SqliteConstraintClause } from "./dialects/sqlite-constraints.ts";
 export { renderMigrationVisibility } from "./dialects/migration-visibility.ts";
-export { renderMigrationInventory, renderSqliteColumnInventory, renderSqliteForeignKeyInventory, renderSqliteRebuildObjects } from "./dialects/migration-inventory.ts";
-export { renderMigrationObjectBatch, renderMigrationObjectQuery, renderCheckProbe, renderMigrationNamespace, renderMigrationServerVersion, renderMigrationDependencies, renderMysqlObjectMembers } from "./dialects/migration-objects.ts";
-export type { MigrationObjectBatch } from "./dialects/migration-objects.ts";
+export { renderMigrationInventory, renderSqliteColumnInventory, renderSqliteForeignKeyInventory, renderSqliteRebuildObjects, renderSqliteColumnInventoryBatch, renderSqliteForeignKeyInventoryBatch, renderSqliteIntrospectionPragmaBatch } from "./dialects/migration-inventory.ts";
+export { renderMigrationObjectBatch, renderMigrationObjectQuery, renderCheckProbe, renderMigrationNamespace, renderMigrationServerVersion, renderMigrationDependencies, renderMysqlObjectMembers, renderMysqlObjectBatch, renderMysqlObjectMembersBatch } from "./dialects/migration-objects.ts";
+export type { MigrationObjectBatch, MysqlObjectBatch } from "./dialects/migration-objects.ts";
+export type { SqliteIntrospectionPragma } from "./dialects/migration-inventory.ts";
 export type { DiagnosticStatement, FixedDiagnosticQuery } from "./dialects/diagnostics.ts";
 export { POSTGRES_DIAGNOSTIC_SQL, POSTGRES_WORKLOAD_LIMITS, renderPostgresExplain, renderPostgresWorkload, } from "./dialects/postgres-diagnostics.ts";
 export type { PostgresExplainOptions, PostgresWorkloadQuery } from "./dialects/postgres-diagnostics.ts";