@lunora/hyperdrive 1.0.0-alpha.211 → 1.0.0-alpha.213

package/README.md

@@ -101,7 +101,7 @@ import { defineApp } from "../../lunora/_generated/app";
 
 const app = defineApp<Env>()
     .shard((env) => env.SHARD)
-    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString)))
+    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString, { fetch_types: false, max: 5 })))
     .build();
 
 export const ShardDO = app.ShardDO;
@@ -157,7 +157,7 @@ Supply the driver once, on the app builder — required, or every tick records `
 ```ts
 export default defineApp<Env>()
     .shard((env) => env.SHARD)
-    .sourceClient((env, binding) => fromPostgresJs(postgres((env[binding] as { connectionString: string }).connectionString)))
+    .sourceClient((env, binding) => fromPostgresJs(postgres((env[binding] as { connectionString: string }).connectionString, { fetch_types: false, max: 5 })))
     .build();
 ```
 
@@ -176,14 +176,17 @@ Three things to know before you build on it:
 The `@lunora/hyperdrive/global` subpath is the opposite trade-off: Lunora **owns** the schema and a `.global()` table gets a real column-per-field layout on your Postgres/MySQL, with every write routed through the shared store core. Live queries stay reactive — identical to D1 — because the writer drives the same broadcast hook. Build the writer inside the Durable Object that hosts the `.global()` store and inject it as `globalDb`:
 
 ```ts
+import { fromPostgresJs } from "@lunora/hyperdrive";
 import { createPostgresGlobalCtxDb } from "@lunora/hyperdrive/global";
 import postgres from "postgres";
 
-// `sql` is a postgres.js client built from the HYPERDRIVE binding's connection string.
-const globalDb = createPostgresGlobalCtxDb({ query: (text, params) => sql.unsafe(text, params) }, { schema });
+const sql = postgres(env.HYPERDRIVE.connectionString, { fetch_types: false, max: 5 });
+const globalDb = createPostgresGlobalCtxDb(fromPostgresJs(sql), { schema });
 ```
 
-For MySQL use `createMysqlGlobalCtxDb` with a `mysql2/promise` pool created with `flags: ["FOUND_ROWS"]` — without `CLIENT_FOUND_ROWS` the affected-rows OCC guard sees changed (not matched) rows and raises spurious conflicts. Lower-level building blocks (`buildPgExec`, `buildMysqlExec`, `postgresDialect`, `mysqlDialect`, `createHyperdriveGlobalCtxDb`) are exported for custom wiring.
+For MySQL use `createMysqlGlobalCtxDb` with a `mysql2/promise` pool created with `disableEval: true` (required on Workers) and `flags: ["FOUND_ROWS"]` — without `CLIENT_FOUND_ROWS` the affected-rows OCC guard sees changed (not matched) rows and raises spurious conflicts. Lower-level building blocks (`buildPgExec`, `buildMysqlExec`, `postgresDialect`, `mysqlDialect`, `createHyperdriveGlobalCtxDb`) are exported for custom wiring.
+
+The Hyperdrive config behind `.global()` must have **query caching disabled** (`wrangler hyperdrive create … --caching-disabled`, or `wrangler hyperdrive update <id> --caching-disabled`). Hyperdrive caches reads for up to 75 s by default and writes don't invalidate them, so the store's OCC re-reads, change-log polls and live-query re-runs would see stale rows. `lunora deploy` sets this on the configs it creates when the schema has `.global({ backend: "hyperdrive" })` tables, and warns about an already-bound config that still caches (when Cloudflare API credentials are set).
 
 > This README covers the basics. For the full API and the determinism/realtime rationale, see the **[documentation](https://lunora.sh/docs/packages/hyperdrive)**.
 

package/dist/global.d.mts

@@ -21,10 +21,16 @@
  * **MySQL connections must enable `CLIENT_FOUND_ROWS`** (mysql2:
  * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
  * matched (not changed) rows — see {@link buildMysqlExec}.
+ *
+ * **The Hyperdrive config must have query caching disabled**
+ * (`wrangler hyperdrive create … --caching-disabled`). Hyperdrive caches reads by
+ * default and a write does not invalidate them, so OCC re-reads, change-log polls
+ * and live-query re-runs would read rows up to `max_age + stale_while_revalidate`
+ * old.
  */
-import { DatabaseWriterLike } from '@lunora/shard-engine';
-import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-B2JdXSms.mjs";
+import { SchemaLike, ImportConflictMode, CdcChange, DatabaseWriterLike } from '@lunora/shard-engine';
+import { SqlExec, SqlDialect, SqlCtxDbOptions, FacetGlobalColumnOptions, GlobalFacetResult, GlobalTableInfo, ReadGlobalTablePageOptions, GlobalTablePage, ExportRow, ImportResult } from '@lunora/sql-store';
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-Zm06MRhL.mjs";
 import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
 /**
  * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`
@@ -33,7 +39,7 @@ import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
  */
 type RowClient = SqlClient;
 /**
- * Minimal `mysql2/promise` connection/pool surface — `execute` resolves to
+ * Minimal `mysql2/promise` connection/pool surface — `query` resolves to
  * `[rows | ResultSetHeader, fields]`. Aliases {@link Mysql2Like} so the /global
  * entry's driver surface can never drift from the main entry's, widened with the
  * (optional, structural) shape {@link assertFoundRows}'s `CLIENT_FOUND_ROWS`
@@ -60,9 +66,9 @@ type RowClient = SqlClient;
  * typings, so spelling them out made a real `createPool(...)` fail to type-check
  * (TS2345, weak-type mismatch on `config`). {@link readMysqlClientFlags} reads
  * them through the internal `FlagProbeShape` instead, and a minimal test double
- * (only `execute`) resolves to "undeterminable" rather than a `TypeError`.
+ * (only `query`) resolves to "undeterminable" rather than a `TypeError`.
  */
-type Mysql2Execute = Mysql2Like & {
+type Mysql2Client = Mysql2Like & {
   config?: unknown;
   pool?: unknown;
 };
@@ -92,6 +98,9 @@ declare const buildPgExec: (client: RowClient) => SqlExec;
  * forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
  * for the store's affected-rows OCC guard.
  *
+ * Statements go over as text with client-side escaping, so the server must not
+ * run with `NO_BACKSLASH_ESCAPES` (see {@link Mysql2Like}).
+ *
  * **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
  * (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
  * counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
@@ -100,12 +109,12 @@ declare const buildPgExec: (client: RowClient) => SqlExec;
  *
  * `batch` dispatches every statement concurrently (`Promise.all`), same
  * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
- * single-statement `execute`, so this is "spread across a pool's connections"
+ * single-statement `query`, so this is "spread across a pool's connections"
  * rather than one wire-level multi-statement command; still non-atomic,
  * at-least-once, and unordered between elements, safe only for statements
  * with no cross-effect (what every current caller batches).
  */
-declare const buildMysqlExec: (connection: Mysql2Execute) => SqlExec;
+declare const buildMysqlExec: (connection: Mysql2Client) => SqlExec;
 /**
  * **Postgres** dialect. Differs from SQLite only in column types
  * (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
@@ -171,8 +180,77 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
  * D1 store options.
  */
 declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+/** Options for {@link exportHyperdriveGlobalRows}. */
+interface ExportHyperdriveGlobalRowsOptions {
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+  /** Table allowlist; empty or absent exports every `.global()` table. */
+  tables?: ReadonlyArray<string>;
+}
+/**
+ * The admin export's global plane on Hyperdrive: yield every requested
+ * `.global()` table's rows, keyset-paged. Provisions the schema's tables first,
+ * so a table that was never written exports as empty instead of failing.
+ */
+declare const exportHyperdriveGlobalRows: ({ engine, exec, schema, tables }: ExportHyperdriveGlobalRowsOptions) => AsyncGenerator<ExportRow, void, undefined>;
+/** Options for {@link importHyperdriveGlobalRows}. */
+interface ImportHyperdriveGlobalRowsOptions {
+  /** Append each insert to the global CDC log, like any other write — the app's own `cdc` setting. */
+  cdc: boolean;
+  /** Validate and report shape errors only; nothing is probed or written. */
+  dryRun?: boolean;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  /** `"replace"` overwrites a row whose `_id` already exists; `"skip"` (the default) counts it as a conflict. */
+  onConflict?: ImportConflictMode;
+  rows: ReadonlyArray<ExportRow>;
+  schema: SchemaLike;
+  startLine?: number;
+}
+/**
+ * The admin import's global plane on Hyperdrive: insert snapshot rows through
+ * the same store core `.global()` writes use. A row whose `_id` already exists
+ * is a conflict left unchanged, unless `onConflict` is `"replace"`.
+ */
+declare const importHyperdriveGlobalRows: ({ cdc, dryRun, engine, exec, onConflict, rows, schema, startLine }: ImportHyperdriveGlobalRowsOptions) => Promise<ImportResult>;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */
-declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+declare const createMysqlGlobalCtxDb: (connection: Mysql2Client, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
+/** The studio's global data browser over a Hyperdrive database — every table in the connection's schema, internal ones hidden. */
+interface HyperdriveGlobalIntrospector {
+  facetColumn: (options: FacetGlobalColumnOptions) => Promise<GlobalFacetResult>;
+  listTables: () => Promise<GlobalTableInfo[]>;
+  readTablePage: (options: ReadGlobalTablePageOptions) => Promise<GlobalTablePage>;
+}
+/** Build the studio's global-browser introspector for a Hyperdrive `.global()` store. */
+declare const createHyperdriveGlobalIntrospector: (engine: HyperdriveEngine, exec: SqlExec, schema: SchemaLike) => HyperdriveGlobalIntrospector;
+/**
+ * The admin CDC sync's global plane on Hyperdrive: a page of the global
+ * `__cdc_log` past `sinceSeq`. The log only exists once a CDC-enabled writer has
+ * run, so its absence is "nothing has changed yet" — an empty page that leaves
+ * the cursor where it was — not an error.
+ */
+declare const readHyperdriveGlobalCdc: (engine: HyperdriveEngine, exec: SqlExec, request: {
+  limit?: number;
+  now?: number;
+  sinceSeq: number;
+}) => Promise<{
+  changes: CdcChange[];
+  cursor: number;
+}>;
+/**
+ * The admin point-in-time apply's global plane on Hyperdrive: replay CDC changes
+ * in order through the store core (insert, falling back to replace). The writer
+ * carries the app's `cdc` setting so the replay appends to the global changelog
+ * like any other write. Returns the number replayed.
+ */
+declare const applyHyperdriveGlobalCdc: (options: {
+  cdc: boolean;
+  changes: ReadonlyArray<CdcChange>;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+}) => Promise<number>;
+export { CreateHyperdriveGlobalCtxDbOptions, ExportHyperdriveGlobalRowsOptions, HyperdriveEngine, HyperdriveGlobalIntrospector, ImportHyperdriveGlobalRowsOptions, type Mysql2Client, type PgVectorIndexOptions, type RowClient, applyHyperdriveGlobalCdc, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createHyperdriveGlobalIntrospector, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, exportHyperdriveGlobalRows, importHyperdriveGlobalRows, mysqlDialect, postgresDialect, readHyperdriveGlobalCdc };

package/dist/global.d.ts

@@ -21,10 +21,16 @@
  * **MySQL connections must enable `CLIENT_FOUND_ROWS`** (mysql2:
  * `createPool({ flags: ["FOUND_ROWS"] })`) so the affected-rows OCC guard sees
  * matched (not changed) rows — see {@link buildMysqlExec}.
+ *
+ * **The Hyperdrive config must have query caching disabled**
+ * (`wrangler hyperdrive create … --caching-disabled`). Hyperdrive caches reads by
+ * default and a write does not invalidate them, so OCC re-reads, change-log polls
+ * and live-query re-runs would read rows up to `max_age + stale_while_revalidate`
+ * old.
  */
-import { DatabaseWriterLike } from '@lunora/shard-engine';
-import { SqlExec, SqlDialect, SqlCtxDbOptions } from '@lunora/sql-store';
-import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-B2JdXSms.js";
+import { SchemaLike, ImportConflictMode, CdcChange, DatabaseWriterLike } from '@lunora/shard-engine';
+import { SqlExec, SqlDialect, SqlCtxDbOptions, FacetGlobalColumnOptions, GlobalFacetResult, GlobalTableInfo, ReadGlobalTablePageOptions, GlobalTablePage, ExportRow, ImportResult } from '@lunora/sql-store';
+import { M as Mysql2Like, S as SqlClient } from "./packem_shared/types.d-Zm06MRhL.js";
 import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
 /**
  * Minimal row-returning client (e.g. `@lunora/hyperdrive`'s `fromPostgresJs`/`fromNodePg`
@@ -33,7 +39,7 @@ import { VectorMetric, VectorizeIndexLike } from '@lunora/platform';
  */
 type RowClient = SqlClient;
 /**
- * Minimal `mysql2/promise` connection/pool surface — `execute` resolves to
+ * Minimal `mysql2/promise` connection/pool surface — `query` resolves to
  * `[rows | ResultSetHeader, fields]`. Aliases {@link Mysql2Like} so the /global
  * entry's driver surface can never drift from the main entry's, widened with the
  * (optional, structural) shape {@link assertFoundRows}'s `CLIENT_FOUND_ROWS`
@@ -60,9 +66,9 @@ type RowClient = SqlClient;
  * typings, so spelling them out made a real `createPool(...)` fail to type-check
  * (TS2345, weak-type mismatch on `config`). {@link readMysqlClientFlags} reads
  * them through the internal `FlagProbeShape` instead, and a minimal test double
- * (only `execute`) resolves to "undeterminable" rather than a `TypeError`.
+ * (only `query`) resolves to "undeterminable" rather than a `TypeError`.
  */
-type Mysql2Execute = Mysql2Like & {
+type Mysql2Client = Mysql2Like & {
   config?: unknown;
   pool?: unknown;
 };
@@ -92,6 +98,9 @@ declare const buildPgExec: (client: RowClient) => SqlExec;
  * forward verbatim. MySQL has no `RETURNING`, so `run` surfaces `affectedRows`
  * for the store's affected-rows OCC guard.
  *
+ * Statements go over as text with client-side escaping, so the server must not
+ * run with `NO_BACKSLASH_ESCAPES` (see {@link Mysql2Like}).
+ *
  * **The connection MUST be created with the `CLIENT_FOUND_ROWS` flag**
  * (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows`
  * counts *changed* rows, so an idempotent `patch`/`replace` that re-writes the
@@ -100,12 +109,12 @@ declare const buildPgExec: (client: RowClient) => SqlExec;
  *
  * `batch` dispatches every statement concurrently (`Promise.all`), same
  * rationale as {@link buildPgExec}'s `batch` — `Mysql2Like` only exposes a
- * single-statement `execute`, so this is "spread across a pool's connections"
+ * single-statement `query`, so this is "spread across a pool's connections"
  * rather than one wire-level multi-statement command; still non-atomic,
  * at-least-once, and unordered between elements, safe only for statements
  * with no cross-effect (what every current caller batches).
  */
-declare const buildMysqlExec: (connection: Mysql2Execute) => SqlExec;
+declare const buildMysqlExec: (connection: Mysql2Client) => SqlExec;
 /**
  * **Postgres** dialect. Differs from SQLite only in column types
  * (`DOUBLE PRECISION`/`BYTEA`/`BIGSERIAL`), the `information_schema` catalog
@@ -171,8 +180,77 @@ interface CreateHyperdriveGlobalCtxDbOptions extends Omit<SqlCtxDbOptions, "dial
  * D1 store options.
  */
 declare const createHyperdriveGlobalCtxDb: ({ engine, exec, ...rest }: CreateHyperdriveGlobalCtxDbOptions) => DatabaseWriterLike;
+/** Options for {@link exportHyperdriveGlobalRows}. */
+interface ExportHyperdriveGlobalRowsOptions {
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+  /** Table allowlist; empty or absent exports every `.global()` table. */
+  tables?: ReadonlyArray<string>;
+}
+/**
+ * The admin export's global plane on Hyperdrive: yield every requested
+ * `.global()` table's rows, keyset-paged. Provisions the schema's tables first,
+ * so a table that was never written exports as empty instead of failing.
+ */
+declare const exportHyperdriveGlobalRows: ({ engine, exec, schema, tables }: ExportHyperdriveGlobalRowsOptions) => AsyncGenerator<ExportRow, void, undefined>;
+/** Options for {@link importHyperdriveGlobalRows}. */
+interface ImportHyperdriveGlobalRowsOptions {
+  /** Append each insert to the global CDC log, like any other write — the app's own `cdc` setting. */
+  cdc: boolean;
+  /** Validate and report shape errors only; nothing is probed or written. */
+  dryRun?: boolean;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  /** `"replace"` overwrites a row whose `_id` already exists; `"skip"` (the default) counts it as a conflict. */
+  onConflict?: ImportConflictMode;
+  rows: ReadonlyArray<ExportRow>;
+  schema: SchemaLike;
+  startLine?: number;
+}
+/**
+ * The admin import's global plane on Hyperdrive: insert snapshot rows through
+ * the same store core `.global()` writes use. A row whose `_id` already exists
+ * is a conflict left unchanged, unless `onConflict` is `"replace"`.
+ */
+declare const importHyperdriveGlobalRows: ({ cdc, dryRun, engine, exec, onConflict, rows, schema, startLine }: ImportHyperdriveGlobalRowsOptions) => Promise<ImportResult>;
 /** Convenience: a **Postgres** `.global()` writer from a row-client (postgres.js/pg over Hyperdrive). */
 declare const createPostgresGlobalCtxDb: (client: RowClient, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
 /** Convenience: a **MySQL** `.global()` writer from a `mysql2/promise` connection/pool (created with `flags: ["FOUND_ROWS"]`). */
-declare const createMysqlGlobalCtxDb: (connection: Mysql2Execute, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
-export { CreateHyperdriveGlobalCtxDbOptions, HyperdriveEngine, type Mysql2Execute, type PgVectorIndexOptions, type RowClient, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, mysqlDialect, postgresDialect };
+declare const createMysqlGlobalCtxDb: (connection: Mysql2Client, options: Omit<CreateHyperdriveGlobalCtxDbOptions, "engine" | "exec">) => DatabaseWriterLike;
+/** The studio's global data browser over a Hyperdrive database — every table in the connection's schema, internal ones hidden. */
+interface HyperdriveGlobalIntrospector {
+  facetColumn: (options: FacetGlobalColumnOptions) => Promise<GlobalFacetResult>;
+  listTables: () => Promise<GlobalTableInfo[]>;
+  readTablePage: (options: ReadGlobalTablePageOptions) => Promise<GlobalTablePage>;
+}
+/** Build the studio's global-browser introspector for a Hyperdrive `.global()` store. */
+declare const createHyperdriveGlobalIntrospector: (engine: HyperdriveEngine, exec: SqlExec, schema: SchemaLike) => HyperdriveGlobalIntrospector;
+/**
+ * The admin CDC sync's global plane on Hyperdrive: a page of the global
+ * `__cdc_log` past `sinceSeq`. The log only exists once a CDC-enabled writer has
+ * run, so its absence is "nothing has changed yet" — an empty page that leaves
+ * the cursor where it was — not an error.
+ */
+declare const readHyperdriveGlobalCdc: (engine: HyperdriveEngine, exec: SqlExec, request: {
+  limit?: number;
+  now?: number;
+  sinceSeq: number;
+}) => Promise<{
+  changes: CdcChange[];
+  cursor: number;
+}>;
+/**
+ * The admin point-in-time apply's global plane on Hyperdrive: replay CDC changes
+ * in order through the store core (insert, falling back to replace). The writer
+ * carries the app's `cdc` setting so the replay appends to the global changelog
+ * like any other write. Returns the number replayed.
+ */
+declare const applyHyperdriveGlobalCdc: (options: {
+  cdc: boolean;
+  changes: ReadonlyArray<CdcChange>;
+  engine: HyperdriveEngine;
+  exec: SqlExec;
+  schema: SchemaLike;
+}) => Promise<number>;
+export { CreateHyperdriveGlobalCtxDbOptions, ExportHyperdriveGlobalRowsOptions, HyperdriveEngine, HyperdriveGlobalIntrospector, ImportHyperdriveGlobalRowsOptions, type Mysql2Client, type PgVectorIndexOptions, type RowClient, applyHyperdriveGlobalCdc, buildMysqlExec, buildPgExec, createHyperdriveGlobalCtxDb, createHyperdriveGlobalIntrospector, createMysqlGlobalCtxDb, createPgVectorIndex, createPostgresGlobalCtxDb, exportHyperdriveGlobalRows, importHyperdriveGlobalRows, mysqlDialect, postgresDialect, readHyperdriveGlobalCdc };

package/dist/global.mjs

@@ -1 +1 @@
-import{createSqlCtxDb as c}from"@lunora/sql-store";import{postgresDialect as l,mysqlDialect as s}from"./packem_shared/mysqlDialect-BS1Sz60B.mjs";import{buildMysqlExec as a,buildPgExec as i}from"./packem_shared/buildMysqlExec-CjkrA5JG.mjs";import{createPgVectorIndex as d}from"./packem_shared/createPgVectorIndex-CSNnG065.mjs";const r=({engine:e,exec:t,...o})=>c({...o,dialect:e==="postgres"?l:s,exec:t}),p=(e,t)=>r({...t,engine:"postgres",exec:i(e)}),g=(e,t)=>r({...t,engine:"mysql",exec:a(e)});export{a as buildMysqlExec,i as buildPgExec,r as createHyperdriveGlobalCtxDb,g as createMysqlGlobalCtxDb,d as createPgVectorIndex,p as createPostgresGlobalCtxDb,s as mysqlDialect,l as postgresDialect};
+import{applyCdcChanges as d,CDC_LOG_TABLE as b}from"@lunora/shard-engine";import{createSqlCtxDb as p,readSqlGlobalTablePage as g,listSqlGlobalTables as m,facetSqlGlobalColumn as y,exportSqlGlobalRows as C,importSqlGlobalRows as G,readSqlCdcChanges as x}from"@lunora/sql-store";import{postgresDialect as q,mysqlDialect as u}from"./packem_shared/mysqlDialect-BS1Sz60B.mjs";import{buildMysqlExec as f,buildPgExec as v}from"./packem_shared/buildMysqlExec-PqvV5h4p.mjs";import{createPgVectorIndex as A}from"./packem_shared/createPgVectorIndex-B2Wbzqns.mjs";const o=e=>e==="postgres"?q:u,c=({engine:e,exec:l,...r})=>p({...r,dialect:o(e),exec:l}),H=({engine:e,exec:l,schema:r,tables:t})=>C(l,r,o(e),t===void 0?{}:{tables:t}),P=({cdc:e,dryRun:l,engine:r,exec:t,onConflict:a,rows:s,schema:n,startLine:i})=>G(c({cdc:e,engine:r,exec:t,schema:n}),n,o(r),{dryRun:l===!0,exec:t,onConflict:a??"skip",rows:s,...i===void 0?{}:{startLine:i}}),R=(e,l)=>c({...l,engine:"postgres",exec:v(e)}),T=(e,l)=>c({...l,engine:"mysql",exec:f(e)}),E=(e,l,r)=>{const t=o(e);return{facetColumn:a=>y(l,r,t,a),listTables:()=>m(l,r,t),readTablePage:a=>g(l,r,t,a)}},I=async(e,l,r)=>{const t=o(e),{params:a,sql:s}=t.render(t.tableExists(b));return(await l.all(s,a)).length===0?{changes:[],cursor:r.sinceSeq}:x(l,r,t)},M=async e=>(await d(c({cdc:e.cdc,engine:e.engine,exec:e.exec,schema:e.schema}),e.changes),e.changes.length);export{M as applyHyperdriveGlobalCdc,f as buildMysqlExec,v as buildPgExec,c as createHyperdriveGlobalCtxDb,E as createHyperdriveGlobalIntrospector,T as createMysqlGlobalCtxDb,A as createPgVectorIndex,R as createPostgresGlobalCtxDb,H as exportHyperdriveGlobalRows,P as importHyperdriveGlobalRows,u as mysqlDialect,q as postgresDialect,I as readHyperdriveGlobalCdc};

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-B2JdXSms.mjs";
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-Zm06MRhL.mjs";
 /**
  * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
  * user-supplied SQL driver.
@@ -18,7 +18,11 @@ import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as S
  * // not per request. `ctx.sql` is emitted `readonly`; it is never assigned.
  * const app = defineApp<Env>()
  *     .shard((env) => env.SHARD)
- *     .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE).connectionString)))
+ *     .hyperdrive((env) => {
+ *         const { connectionString } = createHyperdrive(env.HYPERDRIVE);
+ *
+ *         return fromPostgresJs(postgres(connectionString, { fetch_types: false, max: 5 }));
+ *     })
  *     .build();
  *
  * // Then, inside an action (never a query/mutation):
@@ -45,6 +49,13 @@ declare const createHyperdrive: (binding: HyperdriveLike) => {
  * Uses the driver's `.unsafe(text, params)` escape hatch so the caller supplies
  * a plain SQL string with `$1, $2, …` placeholders and a positional params
  * array. postgres.js's `.unsafe` resolves to a row array.
+ *
+ * `prepare: true` because `.unsafe` defaults to `prepare: false`, which
+ * Cloudflare warns against: under Hyperdrive's transaction pooling unnamed
+ * statements can hang or fail intermittently, and each one costs a Describe
+ * round trip before it executes. A client built with `prepare: false` still
+ * wins. Prepared reads are cacheable by Hyperdrive, so a `.global()` store's
+ * config must have caching disabled (see `@lunora/hyperdrive/global`).
  */
 declare const fromPostgresJs: (client: PostgresJsLike) => SqlClient;
 /**
@@ -56,7 +67,7 @@ declare const fromNodePg: (client: NodePgLike) => SqlClient;
 /**
  * Wrap a `mysql2/promise` connection or pool as a {@link SqlClient}.
  *
- * Use `?` placeholders (MySQL positional syntax). `mysql2`'s `execute` resolves
+ * Use `?` placeholders (MySQL positional syntax). `mysql2`'s `query` resolves
  * to a `[rows, fields]` tuple; the adapter returns the first element. For a
  * non-`SELECT` (DML), `mysql2` yields a `ResultSetHeader` object rather than a
  * row array, so the adapter normalises that to `[]` — matching the empty-array

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-B2JdXSms.js";
+import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as SqlClient, N as NodePgLike, P as PostgresJsLike } from "./packem_shared/types.d-Zm06MRhL.js";
 /**
  * Surface a Cloudflare Hyperdrive binding as a connection ready to feed a
  * user-supplied SQL driver.
@@ -18,7 +18,11 @@ import { H as HyperdriveLike, a as HyperdriveConnection, M as Mysql2Like, S as S
  * // not per request. `ctx.sql` is emitted `readonly`; it is never assigned.
  * const app = defineApp<Env>()
  *     .shard((env) => env.SHARD)
- *     .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE).connectionString)))
+ *     .hyperdrive((env) => {
+ *         const { connectionString } = createHyperdrive(env.HYPERDRIVE);
+ *
+ *         return fromPostgresJs(postgres(connectionString, { fetch_types: false, max: 5 }));
+ *     })
  *     .build();
  *
  * // Then, inside an action (never a query/mutation):
@@ -45,6 +49,13 @@ declare const createHyperdrive: (binding: HyperdriveLike) => {
  * Uses the driver's `.unsafe(text, params)` escape hatch so the caller supplies
  * a plain SQL string with `$1, $2, …` placeholders and a positional params
  * array. postgres.js's `.unsafe` resolves to a row array.
+ *
+ * `prepare: true` because `.unsafe` defaults to `prepare: false`, which
+ * Cloudflare warns against: under Hyperdrive's transaction pooling unnamed
+ * statements can hang or fail intermittently, and each one costs a Describe
+ * round trip before it executes. A client built with `prepare: false` still
+ * wins. Prepared reads are cacheable by Hyperdrive, so a `.global()` store's
+ * config must have caching disabled (see `@lunora/hyperdrive/global`).
  */
 declare const fromPostgresJs: (client: PostgresJsLike) => SqlClient;
 /**
@@ -56,7 +67,7 @@ declare const fromNodePg: (client: NodePgLike) => SqlClient;
 /**
  * Wrap a `mysql2/promise` connection or pool as a {@link SqlClient}.
  *
- * Use `?` placeholders (MySQL positional syntax). `mysql2`'s `execute` resolves
+ * Use `?` placeholders (MySQL positional syntax). `mysql2`'s `query` resolves
  * to a `[rows, fields]` tuple; the adapter returns the first element. For a
  * non-`SELECT` (DML), `mysql2` yields a `ResultSetHeader` object rather than a
  * row array, so the adapter normalises that to `[]` — matching the empty-array

package/dist/index.mjs

@@ -1 +1 @@
-import{createHyperdrive as e,fromMysql2 as f,fromNodePg as m,fromPostgresJs as p}from"./packem_shared/createHyperdrive-BeXs5Dr6.mjs";import{projectSourceRow as t,pullSourceRows as c}from"./packem_shared/projectSourceRow-DN8ywPRl.mjs";export{e as createHyperdrive,f as fromMysql2,m as fromNodePg,p as fromPostgresJs,t as projectSourceRow,c as pullSourceRows};
+import{createHyperdrive as e,fromMysql2 as f,fromNodePg as m,fromPostgresJs as p}from"./packem_shared/createHyperdrive-DWZZ_3e2.mjs";import{projectSourceRow as t,pullSourceRows as c}from"./packem_shared/projectSourceRow-DN8ywPRl.mjs";export{e as createHyperdrive,f as fromMysql2,m as fromNodePg,p as fromPostgresJs,t as projectSourceRow,c as pullSourceRows};

package/dist/packem_shared/buildMysqlExec-PqvV5h4p.mjs

@@ -0,0 +1 @@
+import{LunoraError as n}from"@lunora/errors";import{t as o}from"./mysql-params-D4Ijlvo5.mjs";const i=2,s=new WeakSet,c=t=>{const e=t,r=e.config?.clientFlags;if(typeof r=="number")return r;const a=e.pool?.config?.connectionConfig?.clientFlags;return typeof a=="number"?a:void 0},l=t=>{const e=c(t);if(e===void 0){if(s.has(t))return;s.add(t),console.warn('@lunora/hyperdrive: could not determine whether this MySQL connection negotiated CLIENT_FOUND_ROWS (the driver exposes no flag introspection). If it was NOT created with the `CLIENT_FOUND_ROWS` flag (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`), an idempotent patch/replace that rewrites identical values may report 0 affectedRows and raise a spurious OCC ConflictError.');return}if((e&i)===0)throw new n("INTERNAL",'@lunora/hyperdrive: this MySQL connection was not created with the `CLIENT_FOUND_ROWS` flag (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows` counts changed (not matched) rows, so an idempotent patch/replace that rewrites identical values reports 0 and the OCC guard raises a spurious conflict.')},f=t=>({all:(e,r)=>t.query(e,r),batch:async e=>{await Promise.all(e.map(r=>t.query(r.sql,r.params)))},run:async(e,r)=>(await t.query(e,r),{rowsAffected:0})}),p=t=>(l(t),{all:async(e,r)=>{const[a]=await t.query(e,o(r));return Array.isArray(a)?a:[]},batch:async e=>{await Promise.all(e.map(r=>t.query(r.sql,o(r.params))))},run:async(e,r)=>{const[a]=await t.query(e,o(r));return{rowsAffected:a.affectedRows??0}}});export{p as buildMysqlExec,f as buildPgExec};

package/dist/packem_shared/createHyperdrive-DWZZ_3e2.mjs

@@ -0,0 +1 @@
+import{t as o}from"./mysql-params-D4Ijlvo5.mjs";const n=r=>({config:{database:r.database,host:r.host,password:r.password,port:r.port,user:r.user},connectionString:r.connectionString}),c=r=>({dbSystem:"postgresql",query:async(s,t=[])=>await r.unsafe(s,t,{prepare:!0})}),u=r=>({dbSystem:"postgresql",query:async(s,t=[])=>(await r.query(s,t)).rows}),y=r=>({dbSystem:"mysql",query:async(s,t=[])=>{const[e]=await r.query(s,o(t));return Array.isArray(e)?e:[]}});export{n as createHyperdrive,y as fromMysql2,u as fromNodePg,c as fromPostgresJs};

package/dist/packem_shared/createPgVectorIndex-B2Wbzqns.mjs

@@ -0,0 +1 @@
+const F=t=>/^[A-Z_]\w*$/i.test(t);const X=new Set(["42P06","42P07","23505","42710"]),J=t=>typeof t=="object"&&t!==null&&"code"in t&&typeof t.code=="string"&&X.has(t.code),P=5,j="__vec_",v="__ann_",b={cosine:{operator:"<=>",operatorClass:"vector_cosine_ops",score:t=>1-t},"dot-product":{operator:"<#>",operatorClass:"vector_ip_ops",score:t=>t},euclidean:{operator:"<->",operatorClass:"vector_l2_ops",score:t=>t}},U=63,A=U-j.length-v.length-Math.max(...Object.values(b).map(t=>t.operatorClass.length)),C="SELECT jsonb_array_elements_text($1::text::jsonb)",R=t=>`[${[...t].join(",")}]`,D=t=>{const c=Object.getPrototypeOf(t);return c===null||c===Object.prototype},L=t=>t.constructor?.name??"non-plain object",B=(t,c)=>{const o=(e,r)=>{throw new TypeError(`@lunora/hyperdrive: pgvector index "${c}" supports equality metadata filters only, but "${r}" ${e}. Pre-compute it into an equality-shaped metadata field, or keep this index on Vectorize.`)},E=(e,r)=>{(e===void 0||typeof e=="function"||typeof e=="symbol")&&o(`has a value at "${r}" that JSON cannot represent, which would widen the filter to match every row`,r),typeof e=="number"&&!Number.isFinite(e)&&o(`has a non-finite number at "${r}", which JSON turns into null`,r),typeof e=="bigint"&&o(`has a bigint at "${r}", which JSON cannot serialise`,r)},m=(e,r)=>{if(E(e,r),Array.isArray(e)){for(const[p,l]of e.entries())m(l,`${r}[${String(p)}]`);return}if(!(typeof e!="object"||e===null)){D(e)||o(`is a ${L(e)}, whose fields JSON does not preserve`,r);for(const[p,l]of Object.entries(e))p.startsWith("$")&&o("uses a comparison operator",r),m(l,`${r}.${p}`)}};D(t)||o(`is a ${L(t)}, whose fields JSON does not preserve`,"filter");for(const[e,r]of Object.entries(t))e.startsWith("$")&&o("uses a comparison operator",e),e.includes(".")&&o("uses Vectorize's dot-addressed nested syntax, which JSONB containment cannot express",e),m(r,e)},H=t=>{if(!F(t))throw new TypeError(`@lunora/hyperdrive: pgvector \`name\` must be a bare SQL identifier (letters, digits, underscore; not starting with a digit) — got "${t}"`);if(t.length>A)throw new TypeError(`@lunora/hyperdrive: pgvector \`name\` must be at most ${String(A)} characters — got "${t}" (${String(t.length)}). Postgres truncates identifiers at 63 bytes and this index derives longer names from it.`);return t},V=t=>{const{client:c,dimensions:o,metric:E="cosine",name:m}=t,e=`${j}${H(m)}`;if(!Object.hasOwn(b,E))throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" got an unknown metric "${E}" — expected cosine, euclidean, or dot-product`);const{operator:r,operatorClass:p,score:l}=b[E];if(!Number.isInteger(o)||o<=0)throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" needs a positive integer \`dimensions\` — got ${String(o)}`);if(o>2e3)throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" declares ${String(o)} dimensions, over the HNSW limit of ${String(2e3)}. Reduce the embedding width (Vectorize itself tops out at 1536), or keep this index on Vectorize.`);let O=0;const N=()=>(O+=1,`${e}:${String(O)}`);let T;const $=async()=>(T??=(async()=>{for(const n of["CREATE EXTENSION IF NOT EXISTS vector",`CREATE TABLE IF NOT EXISTS "${e}" (id text PRIMARY KEY, namespace text, embedding vector(${String(o)}) NOT NULL, metadata jsonb)`,`CREATE INDEX IF NOT EXISTS "${e}${v}${p}" ON "${e}" USING hnsw (embedding ${p})`,`CREATE INDEX IF NOT EXISTS "${e}__ns" ON "${e}" (namespace)`,`CREATE INDEX IF NOT EXISTS "${e}__meta" ON "${e}" USING gin (metadata)`])try{await c.query(n)}catch(a){if(!J(a))throw a}})().catch(n=>{throw T=void 0,n}),T),w=async(n,a)=>{if(n.length===0)return{mutationId:N()};await $();const s=[...new Map(n.map(i=>[i.id,i])).values()],g=[],u=i=>`$${String(g.push(i))}`,h=s.map(i=>`(${u(i.id)}, ${u(i.namespace??null)}, ${u(R(i.values))}::vector, ${u(i.metadata===void 0?null:JSON.stringify(i.metadata))}::text::jsonb)`);return await c.query(`INSERT INTO "${e}" (id, namespace, embedding, metadata) VALUES ${h.join(", ")} ${a}`,g),{mutationId:N()}};return{async deleteByIds(n){return n.length===0?{count:0,mutationId:N()}:(await $(),{count:(await c.query(`DELETE FROM "${e}" WHERE id IN (${C}) RETURNING id`,[JSON.stringify(n)])).length,mutationId:N()})},async describe(){await $();const[n]=await c.query(`SELECT count(*) AS count FROM "${e}"`);return{dimensions:o,vectorsCount:Number(n?.count??0)}},async getByIds(n){return n.length===0?[]:(await $(),(await c.query(`SELECT id, namespace, metadata, embedding::text AS embedding FROM "${e}" WHERE id IN (${C})`,[JSON.stringify(n)])).map(s=>({id:s.id,...s.metadata===null?{}:{metadata:s.metadata},...s.namespace===null?{}:{namespace:s.namespace},values:JSON.parse(s.embedding)})))},async insert(n){return w(n,"ON CONFLICT (id) DO NOTHING")},async query(n,a){const s=a?.topK??P;if(!Number.isInteger(s)||s<=0)throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" needs a positive integer \`topK\` — got ${String(s)}`);a?.filter!==void 0&&B(a.filter,m),await $();const g=a?.returnValues===!0,u=a?.returnMetadata??"none",h=u!=="none"&&u!==!1,i=[],f=d=>`$${String(i.push(d))}`,y=`embedding ${r} ${f(R(n))}::vector`,S=[];a?.namespace!==void 0&&S.push(`namespace = ${f(a.namespace)}`),a?.filter!==void 0&&Object.keys(a.filter).length>0&&S.push(`metadata @> ${f(JSON.stringify(a.filter))}::text::jsonb`);const I=["id","namespace",`${y} AS distance`];h&&I.push("metadata"),g&&I.push("embedding::text AS embedding");const M=S.length>0?`(SELECT * FROM "${e}" WHERE ${S.join(" AND ")})`:`"${e}"`,x=S.length>0?`WITH filtered AS MATERIALIZED ${M} SELECT ${I.join(", ")} FROM filtered ORDER BY ${y} LIMIT ${f(s)}`:`SELECT ${I.join(", ")} FROM "${e}" ORDER BY ${y} LIMIT ${f(s)}`,_=(await c.query(x,i)).map(d=>({id:d.id,...h&&d.metadata!==null&&d.metadata!==void 0?{metadata:d.metadata}:{},...d.namespace===null?{}:{namespace:d.namespace},score:l(Number(d.distance)),...g&&d.embedding!==void 0?{values:JSON.parse(d.embedding)}:{}}));return{count:_.length,matches:_}},async upsert(n){return w(n,"ON CONFLICT (id) DO UPDATE SET embedding = EXCLUDED.embedding, namespace = EXCLUDED.namespace, metadata = EXCLUDED.metadata")}}};export{V as createPgVectorIndex};

package/dist/packem_shared/mysql-params-D4Ijlvo5.mjs

@@ -0,0 +1 @@
+const n=t=>({toSqlString:()=>`'${t.replaceAll("\\","\\\\").replaceAll("'","''")}'`,toString:()=>t}),e=t=>t.map((r,i)=>{if(r===void 0)throw new TypeError(`@lunora/hyperdrive: MySQL bind parameter ${String(i+1)} is undefined`);return typeof r=="string"?n(r):r===null||typeof r!="object"||r instanceof Date||ArrayBuffer.isView(r)?r:r instanceof ArrayBuffer?new Uint8Array(r):n(JSON.stringify(r))});export{e as t};

package/dist/packem_shared/{types.d-B2JdXSms.d.ts → types.d-Zm06MRhL.d.mts}

@@ -125,24 +125,35 @@ interface NodePgLike {
  * direction, which is all bivariance asks for.
  */
 interface PostgresJsLike {
-  unsafe(this: void, text: string, params?: ReadonlyArray<unknown>): Promise<unknown>;
+  unsafe(this: void, text: string, params?: ReadonlyArray<unknown>, options?: {
+    prepare?: boolean;
+  }): Promise<unknown>;
 }
 /**
  * Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
- * `execute` resolves to a `[rows, fields]` tuple; the adapter takes the first
+ * `query` resolves to a `[rows, fields]` tuple; the adapter takes the first
  * element as the rows.
  *
+ * `query`, not `execute`: `execute` is a protocol-level prepared statement
+ * (`COM_STMT_PREPARE` + the binary protocol), which Hyperdrive does not support
+ * for MySQL. `query` interpolates the `?` placeholders client-side and sends
+ * plain text. Strings are quoted with `''` for a quote and `\\` for a
+ * backslash, so a server whose `sql_mode` includes `NO_BACKSLASH_ESCAPES` is
+ * unsupported: there a backslash is stored twice. No value can end its literal
+ * under either mode. mysql2 skips a `?` inside a quoted string or comment, but
+ * reads `??` as an identifier placeholder.
+ *
  * Method syntax, not an arrow property — see {@link PostgresJsLike} — but here
  * that is necessary and NOT sufficient, which is why `params` is `unknown`.
  *
- * mysql2 types its second argument as a single `ExecuteValues`: a union of
- * scalars, `ExecuteValues[]` and `{ [key: string]: ExecuteValues }`. Declared
+ * mysql2 types its second argument as a single `QueryValues`: a union of
+ * scalars, `QueryValues[]` and `{ [key: string]: QueryValues }`. Declared
  * `params?: ReadonlyArray<unknown>` this projection could never accept the
  * driver it projects — bivariance needs the two parameter types to relate in
  * ONE direction and they relate in neither (`readonly unknown[] | undefined` is
- * not an `ExecuteValues`, and a `string` is not an array).
+ * not a `QueryValues`, and a `string` is not an array).
  *
- * `unknown` is the narrowest supertype of `ExecuteValues` that does not restate
+ * `unknown` is the narrowest supertype of `QueryValues` that does not restate
  * mysql2's union here. Restating it would be the vacuous shim all over again —
  * a local copy that drifts from the package it mirrors and makes the gate pass
  * while a consumer fails.
@@ -154,6 +165,6 @@ interface PostgresJsLike {
  * values at runtime regardless.
  */
 interface Mysql2Like {
-  execute(this: void, text: string, params?: unknown): Promise<[unknown, unknown]>;
+  query(this: void, text: string, params?: unknown): Promise<[unknown, unknown]>;
 }
 export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };

package/dist/packem_shared/{types.d-B2JdXSms.d.mts → types.d-Zm06MRhL.d.ts}

@@ -125,24 +125,35 @@ interface NodePgLike {
  * direction, which is all bivariance asks for.
  */
 interface PostgresJsLike {
-  unsafe(this: void, text: string, params?: ReadonlyArray<unknown>): Promise<unknown>;
+  unsafe(this: void, text: string, params?: ReadonlyArray<unknown>, options?: {
+    prepare?: boolean;
+  }): Promise<unknown>;
 }
 /**
  * Structural projection of a `mysql2/promise` connection/pool. `mysql2`'s
- * `execute` resolves to a `[rows, fields]` tuple; the adapter takes the first
+ * `query` resolves to a `[rows, fields]` tuple; the adapter takes the first
  * element as the rows.
  *
+ * `query`, not `execute`: `execute` is a protocol-level prepared statement
+ * (`COM_STMT_PREPARE` + the binary protocol), which Hyperdrive does not support
+ * for MySQL. `query` interpolates the `?` placeholders client-side and sends
+ * plain text. Strings are quoted with `''` for a quote and `\\` for a
+ * backslash, so a server whose `sql_mode` includes `NO_BACKSLASH_ESCAPES` is
+ * unsupported: there a backslash is stored twice. No value can end its literal
+ * under either mode. mysql2 skips a `?` inside a quoted string or comment, but
+ * reads `??` as an identifier placeholder.
+ *
  * Method syntax, not an arrow property — see {@link PostgresJsLike} — but here
  * that is necessary and NOT sufficient, which is why `params` is `unknown`.
  *
- * mysql2 types its second argument as a single `ExecuteValues`: a union of
- * scalars, `ExecuteValues[]` and `{ [key: string]: ExecuteValues }`. Declared
+ * mysql2 types its second argument as a single `QueryValues`: a union of
+ * scalars, `QueryValues[]` and `{ [key: string]: QueryValues }`. Declared
  * `params?: ReadonlyArray<unknown>` this projection could never accept the
  * driver it projects — bivariance needs the two parameter types to relate in
  * ONE direction and they relate in neither (`readonly unknown[] | undefined` is
- * not an `ExecuteValues`, and a `string` is not an array).
+ * not a `QueryValues`, and a `string` is not an array).
  *
- * `unknown` is the narrowest supertype of `ExecuteValues` that does not restate
+ * `unknown` is the narrowest supertype of `QueryValues` that does not restate
  * mysql2's union here. Restating it would be the vacuous shim all over again —
  * a local copy that drifts from the package it mirrors and makes the gate pass
  * while a consumer fails.
@@ -154,6 +165,6 @@ interface PostgresJsLike {
  * values at runtime regardless.
  */
 interface Mysql2Like {
-  execute(this: void, text: string, params?: unknown): Promise<[unknown, unknown]>;
+  query(this: void, text: string, params?: unknown): Promise<[unknown, unknown]>;
 }
 export { HyperdriveLike as H, Mysql2Like as M, NodePgLike as N, PostgresJsLike as P, SqlClient as S, HyperdriveConnection as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/hyperdrive",
-  "version": "1.0.0-alpha.211",
+  "version": "1.0.0-alpha.213",
   "description": "Bring-your-own Postgres/MySQL for Lunora via Cloudflare Hyperdrive: a driver-agnostic, action-only ctx.sql",
   "keywords": [
     "cloudflare",
@@ -52,8 +52,8 @@
   "dependencies": {
     "@lunora/errors": ">=1.0.0-alpha.51 <2.0.0-0",
     "@lunora/platform": "1.0.0-alpha.75",
-    "@lunora/shard-engine": "1.0.0-alpha.165",
-    "@lunora/sql-store": "1.0.0-alpha.214",
+    "@lunora/shard-engine": "1.0.0-alpha.167",
+    "@lunora/sql-store": "1.0.0-alpha.216",
     "drizzle-orm": "1.0.0-rc.5"
   },
   "peerDependencies": {

package/dist/packem_shared/buildMysqlExec-CjkrA5JG.mjs

@@ -1 +0,0 @@
-import{LunoraError as s}from"@lunora/errors";const n=2,o=new WeakSet,i=t=>{const e=t,r=e.config?.clientFlags;if(typeof r=="number")return r;const a=e.pool?.config?.connectionConfig?.clientFlags;return typeof a=="number"?a:void 0},c=t=>{const e=i(t);if(e===void 0){if(o.has(t))return;o.add(t),console.warn('@lunora/hyperdrive: could not determine whether this MySQL connection negotiated CLIENT_FOUND_ROWS (the driver exposes no flag introspection). If it was NOT created with the `CLIENT_FOUND_ROWS` flag (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`), an idempotent patch/replace that rewrites identical values may report 0 affectedRows and raise a spurious OCC ConflictError.');return}if((e&n)===0)throw new s("INTERNAL",'@lunora/hyperdrive: this MySQL connection was not created with the `CLIENT_FOUND_ROWS` flag (mysql2: `createPool({ flags: ["FOUND_ROWS"] })`). Without it, `affectedRows` counts changed (not matched) rows, so an idempotent patch/replace that rewrites identical values reports 0 and the OCC guard raises a spurious conflict.')},u=t=>({all:(e,r)=>t.query(e,r),batch:async e=>{await Promise.all(e.map(r=>t.query(r.sql,r.params)))},run:async(e,r)=>(await t.query(e,r),{rowsAffected:0})}),d=t=>(c(t),{all:async(e,r)=>{const[a]=await t.execute(e,r);return Array.isArray(a)?a:[]},batch:async e=>{await Promise.all(e.map(r=>t.execute(r.sql,r.params)))},run:async(e,r)=>{const[a]=await t.execute(e,r);return{rowsAffected:a.affectedRows??0}}});export{d as buildMysqlExec,u as buildPgExec};

package/dist/packem_shared/createHyperdrive-BeXs5Dr6.mjs

@@ -1 +0,0 @@
-const o=r=>({config:{database:r.database,host:r.host,password:r.password,port:r.port,user:r.user},connectionString:r.connectionString}),a=r=>({dbSystem:"postgresql",query:async(s,t=[])=>await r.unsafe(s,t)}),c=r=>({dbSystem:"postgresql",query:async(s,t=[])=>(await r.query(s,t)).rows}),n=r=>({dbSystem:"mysql",query:async(s,t=[])=>{const[e]=await r.execute(s,t);return Array.isArray(e)?e:[]}});export{o as createHyperdrive,n as fromMysql2,c as fromNodePg,a as fromPostgresJs};

package/dist/packem_shared/createPgVectorIndex-CSNnG065.mjs

@@ -1 +0,0 @@
-const x=t=>/^[A-Z_]\w*$/i.test(t);const F=new Set(["42P06","42P07","23505","42710"]),X=t=>typeof t=="object"&&t!==null&&"code"in t&&typeof t.code=="string"&&F.has(t.code),P=5,v="__vec_",L="__ann_",y={cosine:{operator:"<=>",operatorClass:"vector_cosine_ops",score:t=>1-t},"dot-product":{operator:"<#>",operatorClass:"vector_ip_ops",score:t=>t},euclidean:{operator:"<->",operatorClass:"vector_l2_ops",score:t=>t}},J=63,A=J-v.length-L.length-Math.max(...Object.values(y).map(t=>t.operatorClass.length)),C=t=>`[${[...t].join(",")}]`,R=t=>{const c=Object.getPrototypeOf(t);return c===null||c===Object.prototype},D=t=>t.constructor?.name??"non-plain object",U=(t,c)=>{const o=(e,r)=>{throw new TypeError(`@lunora/hyperdrive: pgvector index "${c}" supports equality metadata filters only, but "${r}" ${e}. Pre-compute it into an equality-shaped metadata field, or keep this index on Vectorize.`)},l=(e,r)=>{(e===void 0||typeof e=="function"||typeof e=="symbol")&&o(`has a value at "${r}" that JSON cannot represent, which would widen the filter to match every row`,r),typeof e=="number"&&!Number.isFinite(e)&&o(`has a non-finite number at "${r}", which JSON turns into null`,r),typeof e=="bigint"&&o(`has a bigint at "${r}", which JSON cannot serialise`,r)},m=(e,r)=>{if(l(e,r),Array.isArray(e)){for(const[p,E]of e.entries())m(E,`${r}[${String(p)}]`);return}if(!(typeof e!="object"||e===null)){R(e)||o(`is a ${D(e)}, whose fields JSON does not preserve`,r);for(const[p,E]of Object.entries(e))p.startsWith("$")&&o("uses a comparison operator",r),m(E,`${r}.${p}`)}};R(t)||o(`is a ${D(t)}, whose fields JSON does not preserve`,"filter");for(const[e,r]of Object.entries(t))e.startsWith("$")&&o("uses a comparison operator",e),e.includes(".")&&o("uses Vectorize's dot-addressed nested syntax, which JSONB containment cannot express",e),m(r,e)},B=t=>{if(!x(t))throw new TypeError(`@lunora/hyperdrive: pgvector \`name\` must be a bare SQL identifier (letters, digits, underscore; not starting with a digit) — got "${t}"`);if(t.length>A)throw new TypeError(`@lunora/hyperdrive: pgvector \`name\` must be at most ${String(A)} characters — got "${t}" (${String(t.length)}). Postgres truncates identifiers at 63 bytes and this index derives longer names from it.`);return t},W=t=>{const{client:c,dimensions:o,metric:l="cosine",name:m}=t,e=`${v}${B(m)}`;if(!Object.hasOwn(y,l))throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" got an unknown metric "${l}" — expected cosine, euclidean, or dot-product`);const{operator:r,operatorClass:p,score:E}=y[l];if(!Number.isInteger(o)||o<=0)throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" needs a positive integer \`dimensions\` — got ${String(o)}`);if(o>2e3)throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" declares ${String(o)} dimensions, over the HNSW limit of ${String(2e3)}. Reduce the embedding width (Vectorize itself tops out at 1536), or keep this index on Vectorize.`);let O=0;const N=()=>(O+=1,`${e}:${String(O)}`);let T;const $=async()=>(T??=(async()=>{for(const n of["CREATE EXTENSION IF NOT EXISTS vector",`CREATE TABLE IF NOT EXISTS "${e}" (id text PRIMARY KEY, namespace text, embedding vector(${String(o)}) NOT NULL, metadata jsonb)`,`CREATE INDEX IF NOT EXISTS "${e}${L}${p}" ON "${e}" USING hnsw (embedding ${p})`,`CREATE INDEX IF NOT EXISTS "${e}__ns" ON "${e}" (namespace)`,`CREATE INDEX IF NOT EXISTS "${e}__meta" ON "${e}" USING gin (metadata)`])try{await c.query(n)}catch(a){if(!X(a))throw a}})().catch(n=>{throw T=void 0,n}),T),w=async(n,a)=>{if(n.length===0)return{mutationId:N()};await $();const s=[...new Map(n.map(i=>[i.id,i])).values()],g=[],u=i=>`$${String(g.push(i))}`,h=s.map(i=>`(${u(i.id)}, ${u(i.namespace??null)}, ${u(C(i.values))}::vector, ${u(i.metadata===void 0?null:JSON.stringify(i.metadata))}::jsonb)`);return await c.query(`INSERT INTO "${e}" (id, namespace, embedding, metadata) VALUES ${h.join(", ")} ${a}`,g),{mutationId:N()}};return{async deleteByIds(n){return n.length===0?{count:0,mutationId:N()}:(await $(),{count:(await c.query(`DELETE FROM "${e}" WHERE id = ANY($1::text[]) RETURNING id`,[[...n]])).length,mutationId:N()})},async describe(){await $();const[n]=await c.query(`SELECT count(*) AS count FROM "${e}"`);return{dimensions:o,vectorsCount:Number(n?.count??0)}},async getByIds(n){return n.length===0?[]:(await $(),(await c.query(`SELECT id, namespace, metadata, embedding::text AS embedding FROM "${e}" WHERE id = ANY($1::text[])`,[[...n]])).map(s=>({id:s.id,...s.metadata===null?{}:{metadata:s.metadata},...s.namespace===null?{}:{namespace:s.namespace},values:JSON.parse(s.embedding)})))},async insert(n){return w(n,"ON CONFLICT (id) DO NOTHING")},async query(n,a){const s=a?.topK??P;if(!Number.isInteger(s)||s<=0)throw new TypeError(`@lunora/hyperdrive: pgvector index "${m}" needs a positive integer \`topK\` — got ${String(s)}`);a?.filter!==void 0&&U(a.filter,m),await $();const g=a?.returnValues===!0,u=a?.returnMetadata??"none",h=u!=="none"&&u!==!1,i=[],f=d=>`$${String(i.push(d))}`,b=`embedding ${r} ${f(C(n))}::vector`,S=[];a?.namespace!==void 0&&S.push(`namespace = ${f(a.namespace)}`),a?.filter!==void 0&&Object.keys(a.filter).length>0&&S.push(`metadata @> ${f(JSON.stringify(a.filter))}::jsonb`);const I=["id","namespace",`${b} AS distance`];h&&I.push("metadata"),g&&I.push("embedding::text AS embedding");const M=S.length>0?`(SELECT * FROM "${e}" WHERE ${S.join(" AND ")})`:`"${e}"`,j=S.length>0?`WITH filtered AS MATERIALIZED ${M} SELECT ${I.join(", ")} FROM filtered ORDER BY ${b} LIMIT ${f(s)}`:`SELECT ${I.join(", ")} FROM "${e}" ORDER BY ${b} LIMIT ${f(s)}`,_=(await c.query(j,i)).map(d=>({id:d.id,...h&&d.metadata!==null&&d.metadata!==void 0?{metadata:d.metadata}:{},...d.namespace===null?{}:{namespace:d.namespace},score:E(Number(d.distance)),...g&&d.embedding!==void 0?{values:JSON.parse(d.embedding)}:{}}));return{count:_.length,matches:_}},async upsert(n){return w(n,"ON CONFLICT (id) DO UPDATE SET embedding = EXCLUDED.embedding, namespace = EXCLUDED.namespace, metadata = EXCLUDED.metadata")}}};export{W as createPgVectorIndex};