@uniflowed/sql 0.34.0 → 0.36.0

package/index.js

@@ -16,8 +16,9 @@
 //     type. So an `int8` is a `bigint` under `pg` and under `postgres` alike,
 //     rather than whatever each driver's own parser decided.
 //   * **The parts of sqlc's semantics a driver does not have**: `sqlc.slice`
-//     expansion, `:copyfrom` as chunked multi-row inserts, `:batch*` in one
-//     transaction, and nested transactions as savepoints.
+//     expansion, `:copyfrom` (PostgreSQL `COPY` when the adapter can send it,
+//     otherwise chunked multi-row inserts), `:batch*` in one transaction, and
+//     nested transactions as savepoints.
 //   * **A synchronous path** for drivers that run a statement on the calling
 //     thread (`node:sqlite`, `better-sqlite3`, `bun:sqlite`). Generated code
 //     with `sync: true` calls it, so a transaction can stay inside `BEGIN`
@@ -65,12 +66,24 @@ export type QueryMode = "rows" | "exec";
  * `transaction` is absent where the platform has no interactive transactions
  * (Cloudflare D1). Inside a transaction it opens a savepoint.
  */
+/**
+ * Send one `COPY … FROM STDIN` payload and resolve to the number of rows the
+ * server accepted.
+ *
+ * Present on a PostgreSQL adapter that can speak `COPY`. Absent everywhere
+ * else, where `:copyfrom` stays a chunked `INSERT`. The payload is PostgreSQL
+ * text format: tab-separated fields, one row per line.
+ */
+export type CopyIn = (statement: string, payload: string) => Promise<number>;
+
 export type Queryable = {
   readonly engine: Engine,
   /** The most bound parameters one statement may carry; `:copyfrom` chunks under it. */
   readonly maxParams: number,
   query(text: string, params: $ReadOnlyArray<SqlParam>, mode: QueryMode): Promise<QueryResult>,
   readonly transaction?: <T>(body: (tx: Queryable) => Promise<T>) => Promise<T>,
+  /** PostgreSQL `COPY`, when this adapter can send one. */
+  readonly copy?: CopyIn,
   ...
 };
 
@@ -91,7 +104,7 @@ export type Queryable = {
  * body would deadlock the same way `await db.query` does inside `transaction`.
  */
 export type SyncQueryable = {
-  readonly engine: Engine,
+  readonly engine   : Engine,
   readonly maxParams: number,
   querySync(text: string, params: $ReadOnlyArray<SqlParam>, mode: QueryMode): QueryResult,
   readonly transactionSync?: <T>(body: (tx: SyncQueryable) => T) => T,
@@ -155,19 +168,19 @@ function explain(failure: SqlFailure, query: string | null): string {
   return (
     where +
     match (failure) {
-      {kind: "decode", expected: const expected, value: const value} =>
+      {kind: "decode", expected: const expected, value: const value}  =>
         `expected ${expected} from the database, got ${show(value)}`,
-      {kind: "encode", expected: const expected, value: const value} =>
+      {kind: "encode", expected: const expected, value: const value}  =>
         `expected ${expected} as a parameter, got ${show(value)}`,
       {kind: "shape", expected: const expected, actual: const actual} =>
         `the adapter returned ${actual} columns where the query has ${expected}; ` +
           "regenerate with `uf sqlc generate`, or check that the adapter returns rows as arrays",
-      {kind: "closed"} => "the transaction has already committed or rolled back",
-      {kind: "unsupported", feature: const feature} =>
+      {kind: "closed"}                                                => "the transaction has already committed or rolled back",
+      {kind: "unsupported", feature: const feature}                   =>
         `${feature} is not supported by this adapter`,
-      {kind: "params", width: const width, max: const max} =>
+      {kind: "params", width: const width, max: const max}            =>
         `a :copyfrom row binds ${width} parameters and this adapter allows ${max}`,
-      {kind: "row", index: const index, length: const length} =>
+      {kind: "row", index: const index, length: const length}         =>
         `a :copyfrom row has ${length} fields and the statement reads index ${index}`,
     }
   );
@@ -229,11 +242,11 @@ function allRows<T>(rows: $ReadOnlyArray<Row>, width: number, decode: (row: Row)
 
 /** `:one` — the first row, or `null`. */
 export async function one<T>(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
-  width: number,
+  width : number,
   decode: (row: Row) => T,
 ): Promise<T | null> {
   try {
@@ -246,11 +259,11 @@ export async function one<T>(
 
 /** `:one` on a [`SyncQueryable`]. */
 export function oneSync<T>(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
-  width: number,
+  width : number,
   decode: (row: Row) => T,
 ): T | null {
   try {
@@ -263,11 +276,11 @@ export function oneSync<T>(
 
 /** `:many` — every row. */
 export async function many<T>(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
-  width: number,
+  width : number,
   decode: (row: Row) => T,
 ): Promise<Array<T>> {
   try {
@@ -280,11 +293,11 @@ export async function many<T>(
 
 /** `:many` on a [`SyncQueryable`]. */
 export function manySync<T>(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
-  width: number,
+  width : number,
   decode: (row: Row) => T,
 ): Array<T> {
   try {
@@ -296,9 +309,9 @@ export function manySync<T>(
 }
 
 async function run(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): Promise<QueryResult> {
   try {
@@ -309,9 +322,9 @@ async function run(
 }
 
 function executed(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): QueryResult {
   try {
@@ -323,9 +336,9 @@ function executed(
 
 /** `:exec`. */
 export async function exec(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): Promise<void> {
   await run(db, name, text, params);
@@ -333,9 +346,9 @@ export async function exec(
 
 /** `:exec` on a [`SyncQueryable`]. */
 export function execSync(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): void {
   executed(db, name, text, params);
@@ -343,9 +356,9 @@ export function execSync(
 
 /** `:execrows` — how many rows the statement changed. */
 export async function execRows(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): Promise<number> {
   return (await run(db, name, text, params)).rowsAffected;
@@ -353,9 +366,9 @@ export async function execRows(
 
 /** `:execrows` on a [`SyncQueryable`]. */
 export function execRowsSync(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): number {
   return executed(db, name, text, params).rowsAffected;
@@ -369,9 +382,9 @@ export type ExecResult = {|
 
 /** `:execresult` — the affected-row count and, on MySQL and SQLite, the last id. */
 export async function execResult(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): Promise<ExecResult> {
   const { rowsAffected, lastInsertId } = await run(db, name, text, params);
@@ -380,9 +393,9 @@ export async function execResult(
 
 /** `:execresult` on a [`SyncQueryable`]. */
 export function execResultSync(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): ExecResult {
   const { rowsAffected, lastInsertId } = executed(db, name, text, params);
@@ -403,9 +416,9 @@ function insertedId(result: QueryResult, name: string): bigint {
  * `:one`, and this throws rather than resolve to a made-up zero.
  */
 export async function execLastId(
-  db: Queryable,
-  name: string,
-  text: string,
+  db    : Queryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): Promise<bigint> {
   return insertedId(await run(db, name, text, params), name);
@@ -413,9 +426,9 @@ export async function execLastId(
 
 /** `:execlastid` on a [`SyncQueryable`]. */
 export function execLastIdSync(
-  db: SyncQueryable,
-  name: string,
-  text: string,
+  db    : SyncQueryable,
+  name  : string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
 ): bigint {
   return insertedId(executed(db, name, text, params), name);
@@ -453,7 +466,7 @@ export function slice(values: $ReadOnlyArray<SqlParam>): Slice {
  * should match.
  */
 export function expand(
-  parts: $ReadOnlyArray<string>,
+  parts : $ReadOnlyArray<string>,
   values: $ReadOnlyArray<SqlParam | Slice>,
 ): {| readonly text: string, readonly params: $ReadOnlyArray<SqlParam> |} {
   const params: Array<SqlParam> = [];
@@ -485,20 +498,110 @@ export function expand(
  * `VALUES ($1, $2)` is `tuple: ["(", ", ", ")"]`, `refs: [0, 1]`.
  */
 export type CopyPlan = {|
-  readonly head: string,
+  readonly head : string,
   readonly tuple: $ReadOnlyArray<string>,
-  readonly refs: $ReadOnlyArray<number>,
-  readonly tail: string,
+  readonly refs : $ReadOnlyArray<number>,
+  readonly tail : string,
 |};
 
 /** The most rows one statement carries when a row has no parameters at all. */
 const COPY_ROWS_WITHOUT_PARAMS = 1000;
 
-function copyChunk(
-  engine: Engine,
+/**
+ * `COPY <table> (<columns>) FROM STDIN` for an `INSERT … VALUES` plan, or
+ * `null` when the plan is not that shape.
+ *
+ * sqlc only accepts `INSERT INTO t (…) VALUES (…)` for `:copyfrom`, and the
+ * generator puts the table and the column list in `head`. Anything else keeps
+ * the chunked `INSERT`, which is the path every engine can run.
+ */
+function copyStatement(plan: CopyPlan): string | null {
+  const prefix = "INSERT INTO ";
+  const suffix = " VALUES ";
+  if (!plan.head.startsWith(prefix) || !plan.head.endsWith(suffix)) {
+    return null;
+  }
+  const target = plan.head.slice(prefix.length, plan.head.length - suffix.length);
+  return `COPY ${target} FROM STDIN WITH (FORMAT text)`;
+}
+
+/** One field of PostgreSQL's text `COPY` format. */
+function copyField(value: SqlParam): string {
+  if (value === null) {
+    return "\\N";
+  }
+  return escapeCopyText(copyText(value));
+}
+
+function copyText(value: string | number | bigint | Uint8Array): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+  let hex = "\\x";
+  for (let i = 0; i < value.length; i += 1) {
+    hex += value[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+/** `\`, newline, carriage return and tab, the four escapes text `COPY` requires. */
+function escapeCopyText(text: string): string {
+  let out = "";
+  for (let i = 0; i < text.length; i += 1) {
+    const character = text[i];
+    if (character === "\\") {
+      out += "\\\\";
+    } else if (character === "\n") {
+      out += "\\n";
+    } else if (character === "\r") {
+      out += "\\r";
+    } else if (character === "\t") {
+      out += "\\t";
+    } else {
+      out += character;
+    }
+  }
+  return out;
+}
+
+/**
+ * Every row of a `:copyfrom` as one text-format payload.
+ *
+ * A short row throws before anything is sent, the same way the `INSERT` path
+ * does. A null field is `\N`. The payload ends each row with a newline, which
+ * is the row terminator `COPY` counts.
+ */
+function copyPayload(
   plan: CopyPlan,
-  chunk: $ReadOnlyArray<$ReadOnlyArray<SqlParam>>,
+  rows: $ReadOnlyArray<$ReadOnlyArray<SqlParam>>,
   name: string,
+): string {
+  const width = plan.refs.length;
+  let payload = "";
+  for (const row of rows) {
+    for (let i = 0; i < width; i += 1) {
+      const index = plan.refs[i];
+      if (index >= row.length) {
+        throw new SqlError({ kind: "row", index, length: row.length }, name);
+      }
+      if (i > 0) {
+        payload += "\t";
+      }
+      payload += copyField(row[index]);
+    }
+    payload += "\n";
+  }
+  return payload;
+}
+
+function copyChunk(
+  engine: Engine,
+  plan  : CopyPlan,
+  chunk : $ReadOnlyArray<$ReadOnlyArray<SqlParam>>,
+  name  : string,
 ): {| readonly text: string, readonly params: $ReadOnlyArray<SqlParam> |} {
   const width = plan.refs.length;
   const params: Array<SqlParam> = [];
@@ -528,15 +631,18 @@ function copyWidth(db: { readonly maxParams: number, ... }, plan: CopyPlan, name
 }
 
 /**
- * `:copyfrom` — insert every row, as few statements as `maxParams` allows.
+ * `:copyfrom` — insert every row.
  *
- * Inside one transaction when the `Queryable` can open one, so a failure in
- * the third chunk does not leave the first two behind: pgx's `CopyFrom` is one
- * `COPY`, and a caller of the generated function should not have to know it is
- * now several statements. Resolves to the number of rows inserted.
+ * A PostgreSQL adapter that implements `copy` receives one `COPY … FROM STDIN`
+ * in text format, which is one statement and so one success or one failure.
+ * Every other adapter, and a plan that is not an `INSERT … VALUES`, stays on
+ * chunked multi-row `INSERT`s. Those run inside one transaction when the
+ * `Queryable` can open one and the rows do not fit in a single statement, so
+ * a failure in the third chunk does not leave the first two behind. Resolves
+ * to the number of rows inserted.
  */
 export async function copyFrom(
-  db: Queryable,
+  db  : Queryable,
   name: string,
   plan: CopyPlan,
   rows: $ReadOnlyArray<$ReadOnlyArray<SqlParam>>,
@@ -544,6 +650,13 @@ export async function copyFrom(
   if (rows.length === 0) {
     return 0;
   }
+  const copy = db.copy;
+  if (db.engine === "postgresql" && typeof copy === "function") {
+    const statement = copyStatement(plan);
+    if (statement !== null) {
+      return copy(statement, copyPayload(plan, rows, name));
+    }
+  }
   const perStatement = copyWidth(db, plan, name);
   const insert = async (q: Queryable): Promise<number> => {
     let total = 0;
@@ -562,7 +675,7 @@ export async function copyFrom(
 
 /** `:copyfrom` on a [`SyncQueryable`]. */
 export function copyFromSync(
-  db: SyncQueryable,
+  db  : SyncQueryable,
   name: string,
   plan: CopyPlan,
   rows: $ReadOnlyArray<$ReadOnlyArray<SqlParam>>,
@@ -598,9 +711,9 @@ export function copyFromSync(
  * order without one, and the docs say so.
  */
 export async function batch<A, R>(
-  db: Queryable,
+  db   : Queryable,
   items: $ReadOnlyArray<A>,
-  body: (q: Queryable, item: A) => Promise<R>,
+  body : (q: Queryable, item: A) => Promise<R>,
 ): Promise<Array<R>> {
   const each = async (q: Queryable): Promise<Array<R>> => {
     const out: Array<R> = [];
@@ -623,9 +736,9 @@ export async function batch<A, R>(
  * items still run in order, on this thread.
  */
 export function batchSync<A, R>(
-  db: SyncQueryable,
+  db   : SyncQueryable,
   items: $ReadOnlyArray<A>,
-  body: (q: SyncQueryable, item: A) => R,
+  body : (q: SyncQueryable, item: A) => R,
 ): Array<R> {
   const each = (q: SyncQueryable): Array<R> => {
     const out: Array<R> = [];
@@ -646,27 +759,29 @@ export function batchSync<A, R>(
 
 /** How an adapter runs one statement on one connection. */
 export type Run = (
-  text: string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
-  mode: QueryMode,
+  mode  : QueryMode,
 ) => Promise<QueryResult>;
 
 /** [`Run`] for a driver that finishes the statement before returning. */
 export type RunSync = (
-  text: string,
+  text  : string,
   params: $ReadOnlyArray<SqlParam>,
-  mode: QueryMode,
+  mode  : QueryMode,
 ) => QueryResult;
 
 /** What [`transactionOn`] needs from an adapter. */
 export type Connection = {|
-  readonly engine: Engine,
+  readonly engine   : Engine,
   readonly maxParams: number,
-  readonly run: Run,
+  readonly run      : Run,
   /** Present when the driver can also run a statement on the calling thread. */
   readonly runSync?: RunSync,
   /** The statement that opens a transaction; `BEGIN` unless the adapter knows better. */
   readonly begin?: string,
+  /** PostgreSQL `COPY` on this connection, when the driver can send one. */
+  readonly copy?: CopyIn,
 |};
 
 /**
@@ -681,7 +796,7 @@ export type Connection = {|
  */
 export async function transactionOn<T>(
   connection: Connection,
-  body: (tx: Queryable) => Promise<T>,
+  body      : (tx: Queryable) => Promise<T>,
 ): Promise<T> {
   await connection.run(connection.begin ?? "BEGIN", [], "exec");
   return scoped(connection, 0, body, "COMMIT", "ROLLBACK");
@@ -689,10 +804,10 @@ export async function transactionOn<T>(
 
 async function scoped<T>(
   connection: Connection,
-  depth: number,
-  body: (tx: Queryable) => Promise<T>,
-  commit: string,
-  rollback: string,
+  depth     : number,
+  body      : (tx: Queryable) => Promise<T>,
+  commit    : string,
+  rollback  : string,
 ): Promise<T> {
   let open = true;
   const guarded: Run = (text, params, mode) => {
@@ -701,10 +816,17 @@ async function scoped<T>(
     }
     return connection.run(text, params, mode);
   };
+  const copy = connection.copy;
+  const guardedCopy: CopyIn | void =
+    copy === undefined
+      ? undefined
+      : (statement, payload) =>
+          open ? copy(statement, payload) : Promise.reject(new SqlError({ kind: "closed" }));
   const tx: Queryable = {
-    engine: connection.engine,
+    engine   : connection.engine,
     maxParams: connection.maxParams,
-    query: guarded,
+    query    : guarded,
+    ...(guardedCopy === undefined ? null : { copy: guardedCopy }),
     transaction: async <U>(inner: (tx: Queryable) => Promise<U>): Promise<U> => {
       const savepoint = `uf_sp_${depth + 1}`;
       await guarded(`SAVEPOINT ${savepoint}`, [], "exec");
@@ -773,12 +895,12 @@ export function transactionOnSync<T>(connection: Connection, body: (tx: SyncQuer
 }
 
 function scopedSync<T>(
-  runSync: RunSync,
+  runSync   : RunSync,
   connection: Connection,
-  depth: number,
-  body: (tx: SyncQueryable) => T,
-  commit: string,
-  rollback: string,
+  depth     : number,
+  body      : (tx: SyncQueryable) => T,
+  commit    : string,
+  rollback  : string,
 ): T {
   let open = true;
   const guarded: RunSync = (text, params, mode) => {
@@ -788,7 +910,7 @@ function scopedSync<T>(
     return runSync(text, params, mode);
   };
   const tx: SyncQueryable = {
-    engine: connection.engine,
+    engine   : connection.engine,
     maxParams: connection.maxParams,
     querySync: guarded,
     transactionSync: <U>(inner: (tx: SyncQueryable) => U): U => {
@@ -863,9 +985,9 @@ function connect(connection: Connection): Handle {
   const runSync = connection.runSync;
 
   const query = async (
-    text: string,
+    text  : string,
     params: $ReadOnlyArray<SqlParam>,
-    mode: QueryMode,
+    mode  : QueryMode,
   ): Promise<QueryResult> => {
     if (syncOpen) {
       unsupported("an asynchronous query while a synchronous transaction is open");
@@ -894,9 +1016,9 @@ function connect(connection: Connection): Handle {
     }
   };
   const querySync = (
-    text: string,
+    text  : string,
     params: $ReadOnlyArray<SqlParam>,
-    mode: QueryMode,
+    mode  : QueryMode,
   ): QueryResult => {
     const run =
       connection.runSync ?? unsupported("a synchronous query on an asynchronous connection");
@@ -910,6 +1032,19 @@ function connect(connection: Connection): Handle {
     }
     return run(text, params, mode);
   };
+  const rawCopy = connection.copy;
+  const copy =
+    rawCopy === undefined
+      ? undefined
+      : async (statement: string, payload: string): Promise<number> => {
+          if (syncOpen) {
+            unsupported("a COPY while a synchronous transaction is open");
+          }
+          while (gate !== null) {
+            await gate;
+          }
+          return rawCopy(statement, payload);
+        };
   const transactionSync = <T>(body: (tx: SyncQueryable) => T): T => {
     if (runSync == null) {
       unsupported("a synchronous transaction on an asynchronous connection");
@@ -930,12 +1065,13 @@ function connect(connection: Connection): Handle {
     }
   };
   return {
-    engine: connection.engine,
+    engine   : connection.engine,
     maxParams: connection.maxParams,
     query,
     transaction,
     querySync,
     transactionSync,
+    ...(copy === undefined ? null : { copy }),
   };
 }
 

package/internal/shared.js

@@ -161,9 +161,9 @@ export function bytesParam(expected: string, value: mixed): Uint8Array {
 
 /** One of an enum's labels. */
 export function label<T extends string>(
-  values: $ReadOnlyArray<T>,
+  values  : $ReadOnlyArray<T>,
   expected: string,
-  value: mixed,
+  value   : mixed,
 ): T {
   const index = typeof value === "string" ? values.findIndex((item) => item === value) : -1;
   if (index < 0) {
@@ -174,9 +174,9 @@ export function label<T extends string>(
 
 /** Encode one of an enum's labels, refusing a string that is not one. */
 export function labelParam<T extends string>(
-  values: $ReadOnlyArray<T>,
+  values  : $ReadOnlyArray<T>,
   expected: string,
-  value: mixed,
+  value   : mixed,
 ): T {
   const index = typeof value === "string" ? values.findIndex((item) => item === value) : -1;
   if (index < 0) {

package/internal/statements.js

@@ -13,7 +13,7 @@ export const DEFAULT_STATEMENT_CACHE = 256;
 
 export function statementCache<S>(
   prepare: (text: string) => S,
-  limit: number,
+  limit  : number,
 ): (text: string) => S {
   const cache: Map<string, S> = new Map();
   return (text) => {