@bzync/nextsql 0.1.0 → 0.2.0

package/client-encryption.js

@@ -1,18 +1,20 @@
 'use strict';
 
-// Node-specific NSCE1 implementation. The dependency injection keeps this
+// Node-specific NSCE1/NSCE2 implementation. The dependency injection keeps this
 // module on the driver's single public NextSQLError/Kind surface.
-const { createCipheriv, createDecipheriv, randomBytes } = require('node:crypto');
+const { createCipheriv, createDecipheriv, hkdfSync, randomBytes, timingSafeEqual } = require('node:crypto');
 const fs = require('node:fs/promises');
 
 module.exports = function createClientEncryption(deps) {
   const { NextSQLError, Kind, encodeDecimalString, decodeDecimal, decodeNSJB, formatUUID, parseUUID } = deps;
   const PREFIX = 'NSCE1.';
+	const DETERMINISTIC_PREFIX = 'NSCE2.';
   const MAX_PLAINTEXT = 1 << 20;
   const MAX_KEY_ID = 64;
   const MAX_KEYS = 64;
   const NONCE_SIZE = 12;
   const TAG_SIZE = 16;
+  const DETERMINISTIC_KEY_INFO = Buffer.from('NextSQL NSCE2 AES-SIV v2', 'utf8');
 
   const FieldType = Object.freeze({
     UUID: Object.freeze({ kind: Kind.UUID, precision: 0, scale: 0, vecElem: 0 }),
@@ -334,18 +336,18 @@ module.exports = function createClientEncryption(deps) {
     return Buffer.concat([Buffer.from([tag]), u32(raw.length), raw]);
   }
 
-  function makeHeader(keyID, type, nonce) {
+  function makeHeader(keyID, type, nonce = null) {
     const id = Buffer.from(keyID, 'ascii');
-    const out = Buffer.alloc(3 + id.length + 6 + NONCE_SIZE);
-    out[0] = 1; out[1] = 1; out[2] = id.length; id.copy(out, 3);
+	const out = Buffer.alloc(3 + id.length + 6 + (nonce ? NONCE_SIZE : 0));
+	out[0] = nonce ? 1 : 2; out[1] = nonce ? 1 : 2; out[2] = id.length; id.copy(out, 3);
     const off = 3 + id.length;
     out[off] = type.kind; out.writeUInt16LE(type.precision, off + 1); out.writeUInt16LE(type.scale, off + 3); out[off + 5] = type.vecElem;
-    nonce.copy(out, off + 6);
+	if (nonce) nonce.copy(out, off + 6);
     return out;
   }
 
-  function aad(database, table, column, publicHeader) {
-    const parts = [Buffer.from(PREFIX, 'ascii')];
+  function aad(database, table, column, publicHeader, prefix = PREFIX) {
+	const parts = [Buffer.from(prefix, 'ascii')];
     for (const name of [database, table, column]) {
       const raw = validateName(name);
       parts.push(u16(raw.length), raw);
@@ -355,22 +357,65 @@ module.exports = function createClientEncryption(deps) {
   }
 
   function inspectField(ciphertext) {
-    if (typeof ciphertext !== 'string' || !ciphertext.startsWith(PREFIX)) fail('invalid_format', 'invalid client ciphertext prefix');
-    const enc = ciphertext.slice(PREFIX.length);
+	let prefix, version, suite, nonceSize, mode;
+	if (typeof ciphertext === 'string' && ciphertext.startsWith(PREFIX)) {
+	  prefix = PREFIX; version = 1; suite = 1; nonceSize = NONCE_SIZE; mode = 'randomized';
+	} else if (typeof ciphertext === 'string' && ciphertext.startsWith(DETERMINISTIC_PREFIX)) {
+	  prefix = DETERMINISTIC_PREFIX; version = 2; suite = 2; nonceSize = 0; mode = 'deterministic';
+	} else fail('invalid_format', 'invalid client ciphertext prefix');
+	const enc = ciphertext.slice(prefix.length);
     if (!enc || enc.length % 4 === 1 || !/^[A-Za-z0-9_-]+$/.test(enc) || enc.length > Math.ceil((MAX_PLAINTEXT + 101) * 4 / 3)) {
       fail('invalid_format', 'client ciphertext length out of range');
     }
     const body = Buffer.from(enc, 'base64url');
-    if (body.toString('base64url') !== enc || body.length < 38 || body[0] !== 1 || body[1] !== 1) fail('invalid_format', 'unsupported or truncated client ciphertext');
+	if (body.toString('base64url') !== enc || body.length < 3 + 1 + 6 + nonceSize + TAG_SIZE || body[0] !== version || body[1] !== suite) fail('invalid_format', 'unsupported or truncated client ciphertext');
     const n = body[2];
-    if (n < 1 || n > MAX_KEY_ID || body.length < 3 + n + 6 + NONCE_SIZE + TAG_SIZE) fail('invalid_format', 'invalid field key id length');
+	if (n < 1 || n > MAX_KEY_ID || body.length < 3 + n + 6 + nonceSize + TAG_SIZE) fail('invalid_format', 'invalid field key id length');
     const keyID = body.subarray(3, 3 + n).toString('ascii');
     if (!validKeyID(keyID)) fail('invalid_format', 'invalid field key id');
     const off = 3 + n;
     const type = normalizeType({ kind: body[off], precision: body.readUInt16LE(off + 1), scale: body.readUInt16LE(off + 3), vecElem: body[off + 5] }, 'invalid_format');
-    return { keyID, type, body, headerLength: off + 6 + NONCE_SIZE };
+	return { keyID, type, body, headerLength: off + 6 + nonceSize, mode, prefix };
   }
 
+	function aesBlock(key, block) {
+	  const cipher = createCipheriv('aes-128-ecb', key, null);
+	  cipher.setAutoPadding(false);
+	  return Buffer.concat([cipher.update(block), cipher.final()]);
+	}
+	function dbl(block) {
+	  const out = Buffer.alloc(16); let carry = 0;
+	  for (let i = 15; i >= 0; i--) { const b = block[i]; out[i] = ((b << 1) & 0xff) | carry; carry = b >>> 7; }
+	  if (carry) out[15] ^= 0x87;
+	  return out;
+	}
+	function xor16(a, b) { const out = Buffer.alloc(16); for (let i = 0; i < 16; i++) out[i] = a[i] ^ b[i]; return out; }
+	function cmac(key, msg) {
+	  const l = aesBlock(key, Buffer.alloc(16)); const k1 = dbl(l); const k2 = dbl(k1);
+	  const blocks = Math.max(1, Math.ceil(msg.length / 16)); let last = Buffer.alloc(16);
+	  if (msg.length && msg.length % 16 === 0) last = xor16(msg.subarray(msg.length - 16), k1);
+	  else { const rem = msg.length % 16; msg.copy(last, 0, msg.length - rem); last[rem] = 0x80; last = xor16(last, k2); }
+	  let y = Buffer.alloc(16);
+	  for (let i = 0; i < blocks - 1; i++) y = aesBlock(key, xor16(y, msg.subarray(i * 16, i * 16 + 16)));
+	  return aesBlock(key, xor16(y, last));
+	}
+	function s2v(key, vectors) {
+	  let d = cmac(key, Buffer.alloc(16));
+	  for (let i = 0; i < vectors.length - 1; i++) d = xor16(dbl(d), cmac(key, vectors[i]));
+	  const last = vectors[vectors.length - 1]; let t;
+	  if (last.length >= 16) { t = Buffer.from(last); const off = t.length - 16; for (let i = 0; i < 16; i++) t[off + i] ^= d[i]; }
+	  else { const padded = Buffer.alloc(16); last.copy(padded); padded[last.length] = 0x80; t = xor16(dbl(d), padded); }
+	  return cmac(key, t);
+	}
+	function sivCrypt(material, input, tag, decrypt) {
+	  const q = Buffer.from(tag); q[8] &= 0x7f; q[12] &= 0x7f;
+	  const cipher = decrypt ? createDecipheriv('aes-128-ctr', material.subarray(16), q) : createCipheriv('aes-128-ctr', material.subarray(16), q);
+	  return Buffer.concat([cipher.update(input), cipher.final()]);
+	}
+	function deterministicKey(material) {
+	  return Buffer.from(hkdfSync('sha256', material, Buffer.alloc(0), DETERMINISTIC_KEY_INFO, 32));
+	}
+
   async function encryptField(provider, database, table, column, type, value) {
     if (value === null || value === undefined) return null;
     if (!provider || typeof provider.currentFieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
@@ -395,7 +440,8 @@ module.exports = function createClientEncryption(deps) {
     const expected = normalizeType(expectedType);
     if (ciphertext === null || ciphertext === undefined) return null;
     if (!provider || typeof provider.fieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
-    const parsed = inspectField(ciphertext);
+	const parsed = inspectField(ciphertext);
+	if (parsed.mode !== 'randomized') fail('invalid_format', 'deterministic ciphertext requires decryptFieldDeterministic');
     if (!sameType(expected, parsed.type)) fail('invalid_format', 'encrypted logical type mismatch');
     let key;
     try { key = await provider.fieldKey(database, table, column, parsed.keyID); } catch { fail('crypto', 'field key unavailable or revoked'); }
@@ -415,6 +461,31 @@ module.exports = function createClientEncryption(deps) {
     }
   }
 
+	async function encryptFieldDeterministic(provider, database, table, column, type, value) {
+	  if (value === null || value === undefined) return null;
+	  if (!provider || typeof provider.currentFieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
+	  const t = normalizeType(type); const plain = encodeScalar(t, value);
+	  if (plain.length > MAX_PLAINTEXT) fail('exhausted', 'plaintext exceeds field limit');
+	  let key; try { key = await provider.currentFieldKey(database, table, column); } catch { fail('crypto', 'field key unavailable'); }
+	  const material = deterministicKey(keyMaterial(key)); const hdr = makeHeader(key.id, t);
+	  const associated = aad(database, table, column, hdr, DETERMINISTIC_PREFIX);
+	  const tag = s2v(material.subarray(0, 16), [associated, plain]);
+	  return DETERMINISTIC_PREFIX + Buffer.concat([hdr, tag, sivCrypt(material, plain, tag, false)]).toString('base64url');
+	}
+
+	async function decryptFieldDeterministic(provider, database, table, column, expectedType, ciphertext) {
+	  const expected = normalizeType(expectedType); if (ciphertext == null) return null;
+	  if (!provider || typeof provider.fieldKey !== 'function') fail('invalid_argument', 'field key provider is required');
+	  const parsed = inspectField(ciphertext);
+	  if (parsed.mode !== 'deterministic' || !sameType(expected, parsed.type)) fail('invalid_format', 'encrypted mode or logical type mismatch');
+	  let key; try { key = await provider.fieldKey(database, table, column, parsed.keyID); } catch { fail('crypto', 'field key unavailable or revoked'); }
+	  const material = deterministicKey(keyMaterial(key, parsed.keyID)); const tag = parsed.body.subarray(parsed.headerLength, parsed.headerLength + 16);
+	  const plain = sivCrypt(material, parsed.body.subarray(parsed.headerLength + 16), tag, true);
+	  const expectedTag = s2v(material.subarray(0, 16), [aad(database, table, column, parsed.body.subarray(0, parsed.headerLength), DETERMINISTIC_PREFIX), plain]);
+	  if (!timingSafeEqual(tag, expectedTag)) fail('crypto', 'ciphertext authentication failed');
+	  return decodeScalar(expected, plain);
+	}
+
   function generateFieldKey(id) {
     if (!validKeyID(id)) fail('invalid_argument', 'invalid field key id');
     return { id, material: randomBytes(32) };
@@ -630,5 +701,5 @@ module.exports = function createClientEncryption(deps) {
     }
   }
 
-  return { FieldType, MemoryFieldKeyring, FileFieldKeyring, decryptField, encryptField, generateFieldKey, inspectField };
+  return { FieldType, MemoryFieldKeyring, FileFieldKeyring, decryptField, decryptFieldDeterministic, encryptField, encryptFieldDeterministic, generateFieldKey, inspectField };
 };

package/nextsql.d.ts

@@ -1,10 +1,9 @@
-// Public TypeScript surface for the official NextSQL Node.js driver.
+// Shared TypeScript surface for the official Node.js and Bun NextSQL drivers.
+// Keys and passwords are never accepted in a URL.
 //
-// Self-contained COPY of drivers/js/types.d.ts. It must NOT import from ../js:
-// the package tarball contains only the files in package.json "files", so a
-// parent-directory import resolves to nothing for an installed consumer. The
-// parity test in the driver test suite fails if this drifts from the canonical
-// shared file.
+// drivers/node/nextsql.d.ts and drivers/bun/nextsql.d.ts are published copies
+// of this file (npm packs only in-package files); their parity tests fail if
+// they drift from this canonical source.
 
 export interface TLSOptions {
   /** PEM or DER trust material. */
@@ -31,9 +30,10 @@ export interface Config {
   /** Single-node entry point. Required for connect(); optional when nodes is set. */
   address?: string;
   database?: string;
-  /** Selects which hosted realm this connection targets (M2-2). Optional:
-   * an unset realm sends the exact pre-realm Hello and connects to the
-   * server's configured default. */
+  /** Reserved; must stay empty. Multi-realm hosting was removed — a
+   * deployment serves exactly one database, and a server rejects a Hello
+   * naming any other realm. The field remains only because the wire
+   * frame's trailing realm slot does. */
   realm?: string;
   user: string;
   password?: string;
@@ -51,6 +51,8 @@ export interface Config {
   readConsistency?: ReadConsistencyMode;
   /** Bounded-read staleness window in milliseconds. 0 selects the server default. */
   maxStalenessMs?: number;
+  /** Maximum number of prepared statements to cache per connection LRU. Default: 0 (disabled on raw connect; 50 in pool). */
+  statementCacheSize?: number;
 }
 
 export interface FieldKey {
@@ -212,6 +214,8 @@ export interface Conn {
   encryptField(table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
   /** Authenticate and decode an opaque NSCE1 STRING; null passes through. */
   decryptField(table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
+  encryptFieldDeterministic(table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
+  decryptFieldDeterministic(table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
 }
 
 /** Routing client over every node of a NextSQL HA cluster. */
@@ -236,6 +240,8 @@ export interface HelloOK {
   version: number;
   authMethod: number;
   secret: bigint;
+  /** Capability bits the server accepted from Hello.flags; 0 when none. */
+  flags: number;
 }
 
 export interface DecodeValue {
@@ -246,7 +252,14 @@ export interface DecodeValue {
 
 export declare class NextSQLError extends Error {
   readonly code: string;
-  constructor(code: string, message?: string);
+  /**
+   * Stable ERR_* name from docs/error-codes.md, present only on an error
+   * received over a connection that negotiated the public taxonomy and empty
+   * otherwise. `code` always carries the legacy class, so retry logic should
+   * keep reading that.
+   */
+  readonly publicCode: string;
+  constructor(code: string, message?: string, publicCode?: string);
 }
 
 export declare const Kind: {
@@ -318,15 +331,50 @@ export declare const Type: {
 
 export declare function connect(cfg: Config): Promise<Conn>;
 export declare function connectCluster(cfg: Config): Promise<Cluster>;
+
+export interface PoolOptions {
+  /** Minimum number of idle connections to maintain. Default: 1 */
+  min?: number;
+  /** Maximum number of connections in the pool. Default: 10 */
+  max?: number;
+  /** Maximum milliseconds to wait for a connection before timing out. Default: 30000 (30s) */
+  timeoutMs?: number;
+  /** Maximum idle milliseconds before an unused connection is retired. Default: 300000 (5m) */
+  idleTimeoutMs?: number;
+  /** Maximum number of prepared statements to cache per connection LRU. Default: 50. 0 disables. */
+  statementCacheSize?: number;
+}
+
+export declare class Pool {
+  constructor(config: Config, options?: PoolOptions);
+  readonly size: number;
+  readonly idleCount: number;
+  readonly inUseCount: number;
+  readonly isClosed: boolean;
+  acquire(): Promise<Conn>;
+  release(conn: Conn): Promise<void>;
+  withConnection<T>(fn: (conn: Conn) => Promise<T>): Promise<T>;
+  exec(sql: string, params?: unknown[]): Promise<Result>;
+  query(sql: string, params?: unknown[]): Promise<Result>;
+  close(): Promise<void>;
+}
+
+export declare function createPool(config: Config, options?: PoolOptions): Pool;
 export declare function generateFieldKey(id: string): FieldKey;
 export declare function inspectField(ciphertext: string): { keyID: string; type: FieldTypeDescriptor };
 export declare function encryptField(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
 export declare function decryptField(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
+export declare function encryptFieldDeterministic(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;
+export declare function decryptFieldDeterministic(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, ciphertext: string | null): Promise<unknown>;
 export declare function validateConfig(cfg: Config): void;
 export declare function isLoopback(addr: string): boolean;
 export declare function encodeParam(v: Param): Uint8Array;
 export declare function struct(fields: Array<[string, unknown]>): { __struct: Array<[string, unknown]> };
 export declare function decodeValue(buf: Uint8Array, off: number): DecodeValue;
+/** Hello.flags bit requesting cancellation instead of a session. */
+export declare const FlagCancel: number;
+/** Hello.flags bit requesting the stable ERR_* error taxonomy. */
+export declare const FlagPublicErrorCodes: number;
 export declare function encodeHello(h: Hello): Uint8Array;
 export declare function decodeHelloOK(b: Uint8Array): HelloOK;
 export declare function encodeDecimalString(s: string): Uint8Array;

package/nextsql.js

@@ -57,6 +57,12 @@ const STATUS_TTL_MS = 500;
 const AuthPassword = 1;
 const AuthPasswordKey = 2;
 const FlagCancel = 1;
+// FlagPublicErrorCodes asks the server for the stable ERR_* error taxonomy
+// (docs/error-codes.md). A server that does not implement it ignores the bit
+// and keeps the NSQL v1 error shape, which decodeError still reads, so setting
+// it is safe against any server version. The server echoes it in HelloOK.flags
+// when it was accepted.
+const FlagPublicErrorCodes = 2;
 const FlagNull = 0x01;
 
 const Kind = {
@@ -104,10 +110,16 @@ const MAX_STRUCT_FIELDS = 128;
 const MAX_COLLECTION_LEN = 1 << 20;
 
 class NextSQLError extends Error {
-  constructor(code, message) {
+  constructor(code, message, publicCode) {
     super(message || code);
     this.name = 'NextSQLError';
     this.code = code;
+    // publicCode is the stable ERR_* name the server sent, present only on
+    // an error received over a connection that negotiated the taxonomy and
+    // empty otherwise. code always carries the legacy class, so existing
+    // retry checks keep working and nothing should branch on publicCode
+    // being present.
+    this.publicCode = publicCode || '';
   }
 }
 
@@ -116,7 +128,9 @@ const {
   MemoryFieldKeyring,
   FileFieldKeyring,
   decryptField,
+  decryptFieldDeterministic,
   encryptField,
+  encryptFieldDeterministic,
   generateFieldKey,
   inspectField,
 } = require('./client-encryption')({
@@ -1279,10 +1293,19 @@ function encodeHello(h) {
 }
 
 function decodeHelloOK(b) {
-  if (b.length !== 11) {
+  if (b.length !== 11 && b.length !== 13) {
     throw new NextSQLError('protocol', 'bad hello-ok length');
   }
-  return { version: u16(b, 0), authMethod: b[2], secret: u64(b, 3) };
+  let flags = 0;
+  if (b.length === 13) {
+    flags = u16(b, 11);
+    // The server omits the field when it accepted no capability, so a
+    // present-but-zero field is a second encoding of the v1 hello-ok.
+    if (flags === 0) {
+      throw new NextSQLError('protocol', 'empty hello-ok flags');
+    }
+  }
+  return { version: u16(b, 0), authMethod: b[2], secret: u64(b, 3), flags };
 }
 
 function encodeAuth(password) {
@@ -1374,7 +1397,18 @@ function decodeDataBatch(b) {
 function decodeError(b) {
   const code = readU16String(b, 0, MAX_NAME);
   const msg = readU16String(b, code.next, MAX_NAME);
-  return new NextSQLError(code.value, msg.value);
+  // Optional trailing field, present only from a server that accepted
+  // FlagPublicErrorCodes. Its absence is normal — an older server ignores the
+  // request bit — so this must never be required.
+  let publicCode = '';
+  if (msg.next < b.length) {
+    const p = readU16String(b, msg.next, MAX_NAME);
+    if (p.value === '') {
+      throw new NextSQLError('protocol', 'empty public error code');
+    }
+    publicCode = p.value;
+  }
+  return new NextSQLError(code.value, msg.value, publicCode);
 }
 
 function decodeCommandComplete(b) {
@@ -1567,8 +1601,8 @@ function connectSocket(cfg) {
       if (cfg.tls.ca) {
         opts.ca = cfg.tls.ca;
       }
-      if (cfg.tls.rejectUnauthorized === false) {
-        opts.rejectUnauthorized = false;
+      if (typeof cfg.tls.rejectUnauthorized === 'boolean') {
+        opts.rejectUnauthorized = cfg.tls.rejectUnauthorized;
       }
       const sock = tls.connect(opts, () => resolve(sock));
       sock.on('error', onErr);
@@ -1724,11 +1758,15 @@ class Conn {
     this.wire = wire;
     this.secret = 0n;
     this.busy = false;
+    this.publicErrorCodes = false;
+    this.statementCacheSize = cfg?.statementCacheSize ?? 0;
+    this._stmtCache = this.statementCacheSize > 0 ? new Map() : null;
   }
 
   async handshake() {
     await this.wire.writeFrame(Type.Hello, encodeHello({
       version: VERSION,
+      flags: FlagPublicErrorCodes,
       database: this.cfg.database || '',
       user: this.cfg.user,
       realm: this.cfg.realm || '',
@@ -1739,6 +1777,9 @@ class Conn {
     }
     const ok = decodeHelloOK(msg.payload);
     this.secret = ok.secret;
+    // Diagnostic only: decodeError reads the field whenever it is present,
+    // so nothing depends on this having been echoed.
+    this.publicErrorCodes = (ok.flags & FlagPublicErrorCodes) !== 0;
     await this.wire.writeFrame(Type.Auth, encodeAuth(this.cfg.password || ''));
     msg = await this.wire.readFrame();
     if (msg.type !== Type.AuthOK) {
@@ -1865,6 +1906,30 @@ class Conn {
     if (this.busy) {
       throw new NextSQLError('conflict', 'connection is busy');
     }
+    if (this._stmtCache && params && params.length > 0) {
+      let stmt = this._stmtCache.get(sql);
+      if (stmt) {
+        this._stmtCache.delete(sql);
+        this._stmtCache.set(sql, stmt);
+      } else {
+        stmt = await this.prepare(sql);
+        if (this._stmtCache.size >= this.statementCacheSize) {
+          const oldestKey = this._stmtCache.keys().next().value;
+          const oldestStmt = this._stmtCache.get(oldestKey);
+          this._stmtCache.delete(oldestKey);
+          oldestStmt.close().catch(() => {});
+        }
+        this._stmtCache.set(sql, stmt);
+      }
+      try {
+        return await this._execute(stmt.id, params);
+      } catch (err) {
+        this._stmtCache.delete(sql);
+        stmt.close().catch(() => {});
+        throw err;
+      }
+    }
+
     this.busy = true;
     try {
       await this.wire.writeFrame(Type.Query, encodeQuery(sql, params || []));
@@ -1888,6 +1953,14 @@ class Conn {
     return decryptField(this.cfg.fieldKeys, this.cfg.database || '', table, column, type, ciphertext);
   }
 
+  async encryptFieldDeterministic(table, column, type, value) {
+    return encryptFieldDeterministic(this.cfg.fieldKeys, this.cfg.database || '', table, column, type, value);
+  }
+
+  async decryptFieldDeterministic(table, column, type, ciphertext) {
+    return decryptFieldDeterministic(this.cfg.fieldKeys, this.cfg.database || '', table, column, type, ciphertext);
+  }
+
   async prepare(sql) {
     if (!this.wire) {
       throw new NextSQLError('unavailable', 'connection closed');
@@ -1949,6 +2022,11 @@ class Conn {
   }
 
   async close() {
+    if (this._stmtCache) {
+      const stmts = [...this._stmtCache.values()];
+      this._stmtCache.clear();
+      await Promise.allSettled(stmts.map(s => s.close()));
+    }
     if (!this.wire) {
       return;
     }
@@ -2150,8 +2228,190 @@ async function connectCluster(cfg) {
   return new Cluster(cfg, conns);
 }
 
+class Pool {
+  constructor(cfg, options = {}) {
+    validateConfig(cfg);
+    const min = options.min ?? 1;
+    const max = options.max ?? 10;
+    const timeoutMs = options.timeoutMs ?? 30000;
+    const idleTimeoutMs = options.idleTimeoutMs ?? 300000;
+    const statementCacheSize = options.statementCacheSize ?? 50;
+
+    if (min < 0) throw new NextSQLError('invalid_argument', 'min must be >= 0');
+    if (max < 1) throw new NextSQLError('invalid_argument', 'max must be >= 1');
+    if (max < min) throw new NextSQLError('invalid_argument', 'max must be >= min');
+    if (statementCacheSize < 0) throw new NextSQLError('invalid_argument', 'statementCacheSize must be >= 0');
+
+    this._cfg = { ...cfg, statementCacheSize };
+    this._min = min;
+    this._max = max;
+    this._timeoutMs = timeoutMs;
+    this._idleTimeoutMs = idleTimeoutMs;
+    this._statementCacheSize = statementCacheSize;
+
+    this._idle = []; // [{ conn, lastUsed }]
+    this._inUse = new Set();
+    this._waiters = []; // [{ resolve, reject, timer }]
+    this._closed = false;
+  }
+
+  get size() {
+    return this._idle.length + this._inUse.size;
+  }
+
+  get idleCount() {
+    return this._idle.length;
+  }
+
+  get inUseCount() {
+    return this._inUse.size;
+  }
+
+  get isClosed() {
+    return this._closed;
+  }
+
+  async acquire() {
+    if (this._closed) {
+      throw new NextSQLError('unavailable', 'connection pool is closed');
+    }
+
+    const now = Date.now();
+    while (this._idle.length > 0) {
+      const item = this._idle.pop();
+      if (this._idleTimeoutMs > 0 && (now - item.lastUsed) > this._idleTimeoutMs) {
+        item.conn.close().catch(() => {});
+        continue;
+      }
+      if (item.conn.wire && item.conn.wire.closed) {
+        continue;
+      }
+      this._inUse.add(item.conn);
+      return item.conn;
+    }
+
+    if (this.size < this._max) {
+      const conn = await connect(this._cfg);
+      this._inUse.add(conn);
+      return conn;
+    }
+
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      if (this._timeoutMs > 0) {
+        timer = setTimeout(() => {
+          const idx = this._waiters.findIndex(w => w.resolve === resolve);
+          if (idx >= 0) {
+            this._waiters.splice(idx, 1);
+            reject(new NextSQLError('resource_exhausted', 'connection pool exhausted, wait timeout exceeded'));
+          }
+        }, this._timeoutMs);
+      }
+      this._waiters.push({ resolve, reject, timer });
+    });
+  }
+
+  async release(conn) {
+    if (!this._inUse.has(conn)) {
+      return;
+    }
+    this._inUse.delete(conn);
+
+    if (this._closed || (conn.wire && conn.wire.closed)) {
+      conn.close().catch(() => {});
+      this._drainWaiters();
+      return;
+    }
+
+    // Clean connection state: roll back uncommitted transaction
+    try {
+      await conn.exec('ROLLBACK');
+    } catch {
+      conn.close().catch(() => {});
+      this._drainWaiters();
+      return;
+    }
+
+    while (this._waiters.length > 0) {
+      const waiter = this._waiters.shift();
+      if (waiter.timer) clearTimeout(waiter.timer);
+      this._inUse.add(conn);
+      waiter.resolve(conn);
+      return;
+    }
+
+    this._idle.push({ conn, lastUsed: Date.now() });
+  }
+
+  _drainWaiters() {
+    if (this._closed) {
+      while (this._waiters.length > 0) {
+        const w = this._waiters.shift();
+        if (w.timer) clearTimeout(w.timer);
+        w.reject(new NextSQLError('unavailable', 'connection pool is closed'));
+      }
+      return;
+    }
+    if (this.size < this._max && this._waiters.length > 0) {
+      const waiter = this._waiters.shift();
+      if (waiter.timer) clearTimeout(waiter.timer);
+      connect(this._cfg).then(conn => {
+        this._inUse.add(conn);
+        waiter.resolve(conn);
+      }).catch(err => {
+        waiter.reject(err);
+      });
+    }
+  }
+
+  async withConnection(fn) {
+    const conn = await this.acquire();
+    try {
+      return await fn(conn);
+    } finally {
+      await this.release(conn);
+    }
+  }
+
+  async exec(sql, params) {
+    return this.withConnection(conn => conn.exec(sql, params));
+  }
+
+  async query(sql, params) {
+    return this.withConnection(async (conn) => {
+      const rows = await conn.query(sql, params);
+      return rows.collect();
+    });
+  }
+
+  async close() {
+    if (this._closed) return;
+    this._closed = true;
+
+    while (this._waiters.length > 0) {
+      const w = this._waiters.shift();
+      if (w.timer) clearTimeout(w.timer);
+      w.reject(new NextSQLError('unavailable', 'connection pool is closed'));
+    }
+
+    const conns = [...this._idle.map(item => item.conn), ...this._inUse];
+    this._idle = [];
+    this._inUse.clear();
+
+    await Promise.allSettled(conns.map(c => c.close()));
+  }
+}
+
+function createPool(cfg, options) {
+  return new Pool(cfg, options);
+}
+
 module.exports = {
   connect,
+  createPool,
+  Pool,
+  FlagCancel,
+  FlagPublicErrorCodes,
   connectCluster,
   Cluster,
   NextSQLError,
@@ -2181,7 +2441,9 @@ module.exports = {
   MemoryFieldKeyring,
   FileFieldKeyring,
   decryptField,
+  decryptFieldDeterministic,
   encryptField,
+  encryptFieldDeterministic,
   generateFieldKey,
   inspectField,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bzync/nextsql",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official NextSQL Node.js driver. Keys never go in URLs.",
   "license": "MIT",
   "main": "nextsql.js",