@coffre/db 0.14.4 → 0.15.0

package/src/database.ts

@@ -1,43 +1,31 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import {
-  createTableRelationsHelpers,
-  extractTablesRelationalConfig,
-  getTableName,
-  is,
-  Table,
-  type ExtractTablesWithRelations,
-  type RelationalSchemaConfig,
-} from 'drizzle-orm';
-import { NodePgDatabase, NodePgDriver } from 'drizzle-orm/node-postgres';
-import { PgDialect } from 'drizzle-orm/pg-core';
-import type pg from 'pg';
+import { getTableName, is, Table, type Assume, type RelationalSchemaConfig } from 'drizzle-orm';
+import { PgDatabase, PgDialect, type PgQueryResultHKT, type PgTransactionConfig } from 'drizzle-orm/pg-core';
+import { PostgresJsSession, PostgresJsTransaction } from 'drizzle-orm/postgres-js/session';
 
 import { trackCommits } from './commits.ts';
+import type { Row, RowList } from './postgres-js/index.ts';
+import { textTypes, type PostgresClient } from './postgres.ts';
 import * as schema from './schema.ts';
 
 export { schema };
+export type { PostgresClient } from './postgres.ts';
+
+/** What a hand-written statement answers on Postgres: its rows, with `count` and `command`. */
+export interface QueryResult extends PgQueryResultHKT {
+  type: RowList<Assume<this['row'], Row>[]>;
+}
 
 /**
  * A database, typed as Postgres whichever it is; see portable.ts for why
  * that holds. connect.ts opens one of each from a URL.
  */
-export type Database = NodePgDatabase<typeof schema>;
+export type Database = PgDatabase<QueryResult, typeof schema, NoRelations>;
 export type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0];
 /** Anything a read can run on: the database, or an open transaction. */
 export type Queryable = Database | Transaction;
 
-/**
- * What Drizzle needs from a connection pool. A `pg.Pool` fits, and so does the
- * per-invocation Hyperdrive pool, whose class name ends in `Pool` for the
- * same reason: that is how Drizzle knows to check out a client for a
- * transaction rather than run BEGIN on a shared connection.
- */
-export type PoolLike = pg.Pool | {
-  query: pg.Pool['query'];
-  connect: () => Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }>;
-};
-
 /**
  * A query made on the database from inside one of its own transactions,
  * rather than through the transaction. With one connection per call, as on
@@ -52,23 +40,28 @@ export class QueryOutsideTransaction extends Error {
   }
 }
 
-/** The transaction a flow of work runs inside, with the pool it holds, while it is open. */
-const inside = new AsyncLocalStorage<{ pool: PoolLike; open: boolean }>();
+/** The transaction a flow of work runs inside, with the client it holds, while it is open. */
+const inside = new AsyncLocalStorage<{ client: Client; open: boolean }>();
+
+/** What Drizzle asks of the client: a statement, or a transaction, which postgres.js runs on a connection it holds. */
+const ASKS = new Set<PropertyKey>(['unsafe', 'begin', 'reserve']);
 
 /**
- * `pool`, refusing a query or a transaction asked from inside a transaction
+ * `client`, refusing a query or a transaction asked from inside a transaction
  * it is already running. Work from any other flow, a concurrent request's,
  * or what the transaction left running once its work was done, goes on as before.
  */
-function guarded(pool: PoolLike): PoolLike {
-  return new Proxy(pool, {
+function guarded(client: Client): Client {
+  const refuse = (target: Client) => {
+    const open = inside.getStore();
+    if (open?.open === true && open.client === target) throw new QueryOutsideTransaction();
+  };
+  return new Proxy(client, {
     get(target, key) {
       const value: unknown = Reflect.get(target, key, target);
-      if (typeof value !== 'function') return value;
-      if (key !== 'query' && key !== 'connect') return value.bind(target);
+      if (typeof value !== 'function' || !ASKS.has(key)) return value;
       return (...args: unknown[]) => {
-        const open = inside.getStore();
-        if (open?.open === true && open.pool === target) throw new QueryOutsideTransaction();
+        refuse(target);
         return (value as (...args: unknown[]) => unknown).apply(target, args);
       };
     },
@@ -84,34 +77,57 @@ function brokenRule(error: unknown): QueryOutsideTransaction | undefined {
 }
 
 /**
- * What Drizzle makes of the schema, which `drizzle(pool, { schema })` works
- * out again from every table at each call: on Workers, a database is made
- * per call, and this was a fifth of a vault call's CPU. The schema never
- * changes, so it is worked out once per process or isolate, a settled value.
+ * Coffre runs no relational query (`db.query.*`), and Drizzle's work out of
+ * them, `extractTablesRelationalConfig` and a query builder per table for
+ * every database, was 4 to 11 ms of a cold isolate's CPU and 0.1 ms of each
+ * later call on Workers, where a database is made per call. So the database
+ * has none: `db.query` is empty, in type and at run time, and a `db.query.x`
+ * fails the typecheck. Only the tables stay, for `tablesOf`.
+ */
+type NoRelations = Record<never, never>;
+type Relational = RelationalSchemaConfig<NoRelations>;
+const relational: Relational = { fullSchema: schema, schema: {}, tableNamesMap: {} };
+
+/**
+ * Drizzle's session for postgres.js, but for a transaction's options, which
+ * go in its BEGIN, as node-postgres's session sends them, rather than in a
+ * SET TRANSACTION of their own: a round trip less for a snapshot read.
  */
-type Relational = RelationalSchemaConfig<ExtractTablesWithRelations<typeof schema>>;
-let relational: Relational | undefined;
-
-function relationalSchema(): Relational {
-  if (relational === undefined) {
-    const { tables, tableNamesMap } = extractTablesRelationalConfig(schema, createTableRelationsHelpers);
-    // Drizzle's own construct passes the same untyped tables on as these.
-    relational = { fullSchema: schema, schema: tables as Relational['schema'], tableNamesMap };
+class Session extends PostgresJsSession<PostgresClient, typeof schema, NoRelations> {
+  override transaction<T>(work: (tx: PostgresJsTransaction<typeof schema, NoRelations>) => Promise<T>, config?: PgTransactionConfig): Promise<T> {
+    const { dialect, schema: tables, options } = this as unknown as { dialect: PgDialect; schema: Relational; options: object };
+    return this.client.begin(config === undefined ? '' : transactionOptions(config), (client) =>
+      work(new PostgresJsTransaction(dialect, new PostgresJsSession(client, dialect, tables, options), tables))) as Promise<T>;
   }
-  return relational;
 }
 
-export function createDatabase(pool: PoolLike): Database {
-  // What `drizzle(pool, { schema })` builds, but for the schema's config, made once.
+/** What follows BEGIN for `config`, as Drizzle writes it for SET TRANSACTION. */
+function transactionOptions(config: PgTransactionConfig): string {
+  return [
+    config.isolationLevel === undefined ? null : `isolation level ${config.isolationLevel}`,
+    config.accessMode ?? null,
+    config.deferrable === undefined ? null : config.deferrable ? 'deferrable' : 'not deferrable',
+  ].filter((option) => option !== null).join(' ');
+}
+
+/**
+ * What a database runs on: a postgres.js client (`postgresClient`), or
+ * Workers' `HyperdrivePool`, which makes them. Drizzle asks it for
+ * statements (`unsafe`) and transactions (`begin`).
+ */
+export type Client = Pick<PostgresClient, 'unsafe' | 'begin'>;
+
+export function createDatabase(client: Client): Database {
+  // What `drizzle(client, { schema })` sets up, but with no relational queries.
+  if ('options' in client) textTypes(client as PostgresClient);
   const dialect = new PgDialect();
-  const config = relationalSchema();
-  const db: Database = new NodePgDatabase(dialect, new NodePgDriver(guarded(pool) as pg.Pool, dialect).createSession(config), config);
+  const db = new PgDatabase(dialect, new Session(guarded(client) as PostgresClient, dialect, relational), relational) as Database;
   // Each transaction's work runs knowing which one it is in, until that work is done. Not until
   // the COMMIT comes back: the transaction waits on nothing then, so what the work left running
   // may ask for a query, which waits for the transaction to end rather than for itself.
   const run = db.transaction.bind(db);
   db.transaction = (async (work, config) => {
-    const open = { pool, open: true };
+    const open = { client, open: true };
     try {
       return await run(
         (tx) =>

package/src/dialect.ts

@@ -11,7 +11,7 @@ import type { Queryable } from './database.ts';
  *                     Postgres                SQLite
  *   isolation         READ COMMITTED          one writer at a time
  *   lock a row        SELECT … FOR UPDATE     one writer at a time
- *   rows changed      rowCount                rowsAffected
+ *   rows changed      count                   rowsAffected
  *   duplicate key     SQLSTATE 23505          SQLITE_CONSTRAINT_UNIQUE
  *   clock             CURRENT_TIMESTAMP       strftime(…, 'now')
  *   clock, in ms      clock_timestamp()       unixepoch('subsec')
@@ -56,7 +56,7 @@ export function forUpdate<Query extends { for: (strength: 'update' | 'no key upd
  * are the query's own, unmapped.
  */
 export async function rowsOf<Row>(db: Queryable, query: SQL): Promise<Row[]> {
-  if (engineOf(db) === 'postgres') return (await (db as unknown as { execute(query: SQL): Promise<{ rows: Row[] }> }).execute(query)).rows;
+  if (engineOf(db) === 'postgres') return [...(await (db as unknown as { execute(query: SQL): Promise<Row[]> }).execute(query))];
   return (db as unknown as { all<R>(query: SQL): Promise<R[]> }).all<Row>(query);
 }
 
@@ -98,8 +98,8 @@ export function truth(condition: SQL): SQL<boolean> {
 
 /** How many rows an insert, update or delete touched. */
 export function changedRows(result: unknown): number {
-  const header = result as { rowCount?: number | null; rowsAffected?: number };
-  return header.rowCount ?? header.rowsAffected ?? 0;
+  const header = result as { count?: number | null; rowsAffected?: number };
+  return header.count ?? header.rowsAffected ?? 0;
 }
 
 const DUPLICATE_KEY = new Set(['23505', 'SQLITE_CONSTRAINT_UNIQUE', 'SQLITE_CONSTRAINT_PRIMARYKEY']);
@@ -114,16 +114,25 @@ export function isUniqueViolation(error: unknown): boolean {
   return false;
 }
 
-/** The network's codes for a server that is not there, and Postgres's for one that will not take the connection, or has none left (53300). */
-const UNREACHABLE = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE', '53300', '57P01', '57P02', '57P03']);
+/**
+ * The network's codes for a server that is not there, postgres.js's for a
+ * connection lost, cut short or never made, and Postgres's for one that will
+ * not take the connection, or has none left (53300).
+ */
+const UNREACHABLE = new Set([
+  'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE',
+  'CONNECTION_CLOSED', 'CONNECTION_DESTROYED', 'CONNECTION_ENDED', 'CONNECT_TIMEOUT',
+  '53300', '57P01', '57P02', '57P03',
+]);
 
-/** Hyperdrive's words for having no connection to give, beside pg's and Workers' for one lost. */
+/** Hyperdrive's words for having no connection to give, beside Workers' for one lost. */
 const UNREACHABLE_WORDS = /connection terminated|network connection lost|connect(ion)? timeout|open slot in the pool|acquire a connection from the pool|server connection attempt failed/i;
 
 /**
  * Whether a query failed because the database could not be reached or
  * dropped the connection: an outage, not an answer. Postgres's connection
- * exceptions are class 08; pg and Workers' sockets say so in words, and so
+ * exceptions are class 08; postgres.js says so in codes of its own, Workers'
+ * sockets in words, and so
  * does Hyperdrive when it has no connection to the database to give: every
  * one of its pool busy for 15 s ("Timed out while waiting for an open slot
  * in the pool", FATAL 58000; "Failed to acquire a connection from the

package/src/grants.ts

@@ -307,9 +307,9 @@ export async function reportStands(db: Queryable, principal: string, check: Auth
   return report === 'unreached' || typeof report !== 'string';
 }
 
-/** The newest access entry about `principal` that `check` finds the vault's own. */
-export function newestAccess(db: Queryable, principal: string, check: Authenticity): Promise<Newest> {
-  return newestAuthentic((limit, before) => accessEntriesAbout(db, principal, limit, before), check);
+/** The newest access entry about `principal` that `check` finds the vault's own; at or below `through`, if given. */
+export function newestAccess(db: Queryable, principal: string, check: Authenticity, through?: bigint): Promise<Newest> {
+  return newestAuthentic((limit, before) => accessEntriesAbout(db, principal, limit, before ?? (through === undefined ? undefined : through + 1n)), check);
 }
 
 /** Up to `limit` of the vault's allowed access entries about `principal` before `before` (the newest when undefined), newest first. */

package/src/hyperdrive.ts

@@ -1,7 +1,6 @@
-import pg from 'pg';
-
-import type { PoolLike } from './database.ts';
-import { postgresConnection } from './postgres.ts';
+import type { Client } from './database.ts';
+import { plainRead } from './postgres-js/index.ts';
+import { postgresClient, textTypes, type PostgresClient } from './postgres.ts';
 
 /** Postgres through a Hyperdrive binding: `postgres(env.HYPERDRIVE)`. */
 export type PostgresDatabase = { readonly engine: 'postgres'; readonly hyperdrive: { readonly connectionString: string } };
@@ -9,14 +8,24 @@ export type PostgresDatabase = { readonly engine: 'postgres'; readonly hyperdriv
 /** Postgres through Hyperdrive, the one database a Worker runs on, the app's and the vault's. */
 export function postgres(hyperdrive: { readonly connectionString: string }): PostgresDatabase {
   if (typeof hyperdrive?.connectionString !== 'string') {
-    throw new Error('postgres() takes the Hyperdrive binding, e.g. postgres(env.HYPERDRIVE)');
+    throw new Error('postgres() was given no Hyperdrive binding: one the code names (HYPERDRIVE, VAULT_HYPERDRIVE, HOT_HYPERDRIVE) is missing from its wrangler.jsonc, or bound under another name');
   }
   return { engine: 'postgres', hyperdrive };
 }
 
+/** A statement asked of the pool, sent at its turn once awaited or `execute`d, as postgres.js sends one. */
+type Statement = Promise<unknown> & { values(): Statement; execute(): Statement };
+
+/** A read asked while a group gathers (`groupReads`): sent with the others at its turn, and answered with its own rows. */
+type Gathered = { text: string; values: unknown[]; arrays: () => boolean; resolve: (rows: unknown) => void; reject: (error: unknown) => void };
+
+
+/** What the client refuses to write of a group, before anything of it is sent (`build`, postgres-js/connection.ts). */
+const UNSENT = new Set(['GROUP_UNTYPED', 'MAX_PARAMETERS_EXCEEDED', 'UNDEFINED_VALUE']);
+
 /**
- * node-postgres for one call on Workers, through Hyperdrive: one client,
- * connected on the first query, which every query and transaction of the
+ * postgres.js for one call on Workers, through Hyperdrive: one connection,
+ * opened by the first query, which every query and transaction of the
  * call takes its turn on.
  *
  * Hyperdrive keeps the pool to the database; a Worker's connections belong
@@ -25,134 +34,202 @@ export function postgres(hyperdrive: { readonly connectionString: string }): Pos
  * once was now and then cancelled as hung, with nothing left pending, and
  * every connection costs a round trip before the query can be sent.
  *
- * The turns keep a transaction whole: queries go to the client in the order
- * they are asked, a transaction holds it from BEGIN until it is released,
- * and a query asked meanwhile waits until then, so nothing runs inside a
- * transaction it is not part of. So code inside a transaction must query
- * through the transaction: a query on the database there would wait for the
- * transaction to end, which waits for it. Neither the vault nor the server
- * does.
+ * The turns keep a transaction whole: statements go to the connection in
+ * the order they are asked, each once the one before it has answered; a
+ * transaction holds the connection from BEGIN until it ends, and a query
+ * asked meanwhile waits until then, so nothing runs inside a transaction it
+ * is not part of. So code inside a transaction must query through the
+ * transaction: a query on the database there would wait for the transaction
+ * to end, which waits for it. Neither the vault nor the server does.
+ *
+ * With `groupReads`, the plain reads (`select …`, outside a transaction)
+ * asked while the pool waits for their turn, or in the same task, take it
+ * together, sent under one Sync (`group` in postgres-js/index.ts): on
+ * Hyperdrive, which sends a client's Syncs on one at a time, a round trip
+ * for them all, where each alone took one. They run as one implicit
+ * transaction, so if one fails they all do, with its error; each is a
+ * read, so none had anything to keep. Anything else asked meanwhile, a
+ * write or a transaction, closes the group, and goes after it: statements
+ * still go in the order they are asked.
  *
- * The class name must end in `Pool`: that is how Drizzle knows to check out
- * a client for each transaction.
+ * Closed by `end`, once what was asked has answered; asked again after, as
+ * a call's background work may, it opens a connection again. Unless `end`
+ * was given a time to close by and reached it: then the connection closes
+ * at once, failing what is still asked, and nothing opens it again. And
+ * `destroy` cuts it the same way, at any time.
  */
-export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
+export class HyperdrivePool implements Client {
   readonly #connectionString: string;
-  /** The client, connecting or connected; null before the first query, and once it has failed. */
-  #client: Promise<pg.Client> | null = null;
-  /** Whether a transaction holds the client. */
-  #held = false;
-  /** What waits for its turn, in the order it asked. */
-  readonly #waiting: (() => void)[] = [];
-  /** Queries and transactions asked and not done: waiting for the client, their turn, or an answer. */
+  /** How long the connection may sit idle before it closes, or undefined: closed by `end` alone. */
+  readonly #closeIdleMs: number | undefined;
+  /** The client, made by the first statement; null before it, and once `end` closed it. */
+  #client: PostgresClient | null = null;
+  /** The end of the last turn asked: the next one starts once it has. */
+  #tail: Promise<unknown> = Promise.resolve();
+  /** Turns asked and not done: waiting, or under way. */
   #busy = 0;
-  /** What waits for the client to be idle: `end`. */
+  /** What waits for every turn to be done: `end`. */
   readonly #idle: (() => void)[] = [];
-  /** How long the client may sit idle before it closes, or null: closed by `end` alone. */
-  readonly #closeIdleMs: number | null;
-  #idleTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Whether plain reads asked together go together (`groupReads`). */
+  readonly #groupReads: boolean;
+  /** The reads that will take the next group's turn, while it has not started: what a read asked now joins. */
+  #gathering: Gathered[] | null = null;
+  /** Closed at the time `end` was given, with turns still asked: none opens a connection again. */
+  #cut = false;
+  /** Set by `destroy`: every turn after it fails. */
+  #destroyed = false;
 
   /**
    * `closeIdleMs`: for what outlives a call, a Durable Object, which queries
-   * now and then: the client closes once it has been idle that long, and
-   * the next query connects again.
+   * now and then: the connection closes once it has been idle that long,
+   * and the next query connects again. `groupReads`: plain reads asked
+   * together go together, under one Sync.
    */
-  constructor(connectionString: string, options: { closeIdleMs?: number } = {}) {
+  constructor(connectionString: string, options: { closeIdleMs?: number; groupReads?: boolean } = {}) {
     if (connectionString.trim().length === 0) {
       throw new Error('Hyperdrive returned an empty connection string');
     }
     this.#connectionString = connectionString;
-    this.#closeIdleMs = options.closeIdleMs ?? null;
+    this.#closeIdleMs = options.closeIdleMs;
+    this.#groupReads = options.groupReads === true;
   }
 
-  readonly query: pg.Pool['query'] = (async (...args: unknown[]) => {
-    this.#busy += 1;
-    clearTimeout(this.#idleTimer);
-    try {
-      const client = await this.#connected();
-      return await new Promise((resolve, reject) => {
-        // Sent at its turn, at once: pg answers its queries in the order they are sent.
-        this.#turn(() => (client.query as (...queryArgs: unknown[]) => Promise<unknown>)(...args).then(resolve, reject));
-      });
-    } finally {
-      this.#done();
-    }
-  }) as pg.Pool['query'];
+  readonly unsafe = ((...args: Parameters<PostgresClient['unsafe']>) => {
+    let values = false;
+    let answer: Promise<unknown> | undefined;
+    const [text, parameters = [], options] = args;
+    /** Its turn, asked once: the first `then`, `catch`, `finally` or `execute` asks it. */
+    const asked = () =>
+      (answer ??= this.#groupReads && options === undefined && plainRead(text)
+        ? this.#gather({ text, values: parameters, arrays: () => values })
+        : this.#turn(() => {
+          const query = this.#connected().unsafe(...args);
+          return values ? query.values() : query;
+        }));
+    const statement = {
+      values: () => {
+        values = true;
+        return statement;
+      },
+      execute: () => {
+        void asked().catch(() => {});
+        return statement;
+      },
+      then: (resolve?: (value: unknown) => unknown, reject?: (error: unknown) => unknown) => asked().then(resolve, reject),
+      catch: (reject: (error: unknown) => unknown) => asked().catch(reject),
+      finally: (done: () => void) => asked().finally(done),
+      [Symbol.toStringTag]: 'Statement',
+    } as Statement;
+    return statement;
+  }) as unknown as PostgresClient['unsafe'];
 
-  /** The client, for a transaction: held from now until `release`. */
-  async connect(): Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }> {
-    this.#busy += 1;
-    clearTimeout(this.#idleTimer);
-    let client: pg.Client;
-    try {
-      client = await this.#connected();
-    } catch (error) {
-      this.#done();
-      throw error;
+  /** A transaction: its turn lasts until it has committed or rolled back. */
+  readonly begin = ((...args: unknown[]) =>
+    this.#turn(() => (this.#connected().begin as (...beginArgs: unknown[]) => Promise<unknown>)(...args))) as PostgresClient['begin'];
+
+  /**
+   * A read, in the group gathering for the next turn, or in a new one: it
+   * starts a task later, so that the reads asked with it join, and once
+   * the turns before it are done, which those asked while they ran join.
+   */
+  #gather(read: Omit<Gathered, 'resolve' | 'reject'>): Promise<unknown> {
+    let members = this.#gathering;
+    if (members === null) {
+      const gathered: Gathered[] = (members = []);
+      const asked = new Promise((resolve) => setTimeout(resolve, 0));
+      void this.#turn(async () => {
+        await asked;
+        if (this.#gathering === gathered) this.#gathering = null;
+        try {
+          const client = this.#connected();
+          const alone = async (member: Gathered) => {
+            const query = client.unsafe(member.text, member.values);
+            member.resolve(await (member.arrays() ? query.values() : query));
+          };
+          if (gathered.length === 1) return await alone(gathered[0]!);
+          try {
+            const answers = await client.group(gathered.map((member) => ({ query: member.text, parameters: member.values, arrays: member.arrays() })));
+            gathered.forEach((member, i) => member.resolve(answers[i]));
+          } catch (error) {
+            // A statement the client could not write, a value whose type only the server can say among them: nothing of
+            // the group went, and each goes alone, so that only that one fails, as it would have.
+            if (!UNSENT.has((error as { code?: unknown }).code as string)) throw error;
+            for (const member of gathered) await alone(member).catch(member.reject);
+          }
+        } catch (error) {
+          for (const member of gathered) member.reject(error);
+        }
+      });
+      // After its turn is asked, which closes any group gathering before it.
+      this.#gathering = gathered;
     }
-    await new Promise<void>((resolve) =>
-      this.#turn(() => {
-        this.#held = true;
-        resolve();
-      }),
-    );
-    let released = false;
-    return {
-      query: client.query.bind(client) as pg.PoolClient['query'],
-      release: () => {
-        if (released) return;
-        released = true;
-        this.#held = false;
-        this.#next();
-        this.#done();
-      },
-    };
+    return new Promise((resolve, reject) => members.push({ ...read, resolve, reject }));
   }
 
-  /** Close the client once nothing waits on it: what a Worker hands `waitUntil` when the call is done. */
-  async end(): Promise<void> {
-    clearTimeout(this.#idleTimer);
-    while (this.#busy > 0) {
-      await new Promise<void>((resolve) => this.#idle.push(resolve));
+  /**
+   * Close the connection once every turn asked is done: what a Worker hands `waitUntil` when the call is done. By
+   * `by` (ms since the epoch) at the latest, if given: then at once, what is still asked failing, the statement under
+   * way included, and none of it sent again. A use's call past its deadline, whose answer has gone, so lets go of
+   * Hyperdrive: what it asked and Hyperdrive had not sent goes with the connection (use.ts, `HELD_PAST_DEADLINE_MS`).
+   */
+  async end(by?: number): Promise<void> {
+    // A statement awaited just before reaches the pool a few promise steps later, through Drizzle's session: a task
+    // later, every one has taken its turn, and none opens a connection that this would leave open.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const reached = by === undefined ? null : new Promise<'cut'>((resolve) => (timer = setTimeout(() => resolve('cut'), Math.max(0, by - Date.now()))));
+    while (this.#busy > 0 && !this.#cut) {
+      const idle = new Promise<void>((resolve) => this.#idle.push(resolve));
+      if ((await (reached === null ? idle : Promise.race([idle, reached]))) === 'cut') this.#cut = true;
     }
+    clearTimeout(timer);
     const client = this.#client;
     this.#client = null;
-    if (client === null) return;
-    await client.then((connected) => connected.end()).catch(() => {});
+    await client?.end(this.#cut ? { timeout: 0 } : undefined).catch(() => {});
   }
 
-  /** Run `go` now if nothing holds the client or waits before it, otherwise at its turn. */
-  #turn(go: () => void): void {
-    if (!this.#held && this.#waiting.length === 0) go();
-    else this.#waiting.push(go);
+  /**
+   * The connection cut now, what it was asked failing at once, and every
+   * turn after refused: for what a host stopped waiting on, a connection
+   * gone dead or a connect that never answers (T169), so that whatever
+   * still awaits it fails rather than waits for good. Its statement may
+   * still run in the database.
+   */
+  destroy(): void {
+    this.#destroyed = true;
+    const client = this.#client;
+    this.#client = null;
+    void client?.end({ timeout: 0 }).catch(() => {});
   }
 
-  /** Give the next turns: queries until one is a transaction, which holds the client. */
-  #next(): void {
-    while (!this.#held && this.#waiting.length > 0) this.#waiting.shift()!();
+  /** `go` once every turn asked before it is done. Anything but a group's closes the group gathering: it goes after. */
+  #turn<T>(go: () => PromiseLike<T>): Promise<T> {
+    this.#gathering = null;
+    this.#busy += 1;
+    const answer = this.#tail.then(go);
+    this.#tail = answer.then(
+      () => this.#done(),
+      () => this.#done(),
+    );
+    return answer;
   }
 
-  /** One query or transaction done: once none is left, what waits for the client to be idle goes on. */
+  /** One turn done: once none is left, what waits for the pool to be idle goes on. */
   #done(): void {
     this.#busy -= 1;
-    if (this.#busy > 0) return;
-    for (const resolve of this.#idle.splice(0)) resolve();
-    if (this.#closeIdleMs !== null && this.#client !== null) this.#idleTimer = setTimeout(() => void this.end(), this.#closeIdleMs);
+    if (this.#busy === 0) for (const resolve of this.#idle.splice(0)) resolve();
   }
 
-  /** The call's client, connecting it the first time. One that fails is dropped: the next query connects again. */
-  #connected(): Promise<pg.Client> {
-    if (this.#client !== null) return this.#client;
-    const client = new pg.Client(postgresConnection(this.#connectionString));
-    const connecting: Promise<pg.Client> = client.connect().then(() => client);
-    const drop = () => {
-      if (this.#client === connecting) this.#client = null;
-    };
-    // A connection lost between queries: pg fails what was waiting on it, and the next query connects again.
-    client.on('error', drop);
-    client.on('end', drop);
-    connecting.catch(drop);
-    this.#client = connecting;
-    return connecting;
+  /** The call's client, made the first time. postgres.js opens its connection again when one is lost. */
+  #connected(): PostgresClient {
+    if (this.#destroyed) throw new Error('this connection was cut: its call stopped waiting on it');
+    if (this.#cut) throw new Error("the call's connection was closed at the time it was given (`end`): nothing more is sent");
+    this.#client ??= textTypes(postgresClient(this.#connectionString, {
+      max: 1,
+      idle_timeout: this.#closeIdleMs === undefined ? undefined : this.#closeIdleMs / 1000,
+      // No timer left to outlive the call: `end` closes the connection, or idling does.
+      max_lifetime: null,
+    }));
+    return this.#client;
   }
 }