@avidian/duckdb-bun 0.0.0-stage → 1.0.0

package/src/bindings/runtime/marshal.ts

@@ -0,0 +1,190 @@
+// Moving values across bun:ffi: strings, out slots, and the C structs the
+// contract exposes as plain objects (Date_, Interval, Decimal, ...), encoded and
+// decoded from the layouts generated from DuckDB's C API spec.
+import { CString, type Pointer, read, toArrayBuffer } from "bun:ffi";
+import { layouts } from "../generated/capi.ts";
+import { duckdb } from "./native.ts";
+
+export type LayoutName = keyof typeof layouts;
+type FieldType = string;
+
+const encoder = new TextEncoder();
+
+/** A NUL-terminated UTF-8 copy of `text`, for a C `const char *` argument. */
+export function cstr(text: string): Buffer {
+  return Buffer.from(`${text}\0`, "utf8");
+}
+
+/** UTF-8 bytes of `text` and their length, for a shim `(*const u8, usize)` argument. */
+export function utf8(text: string): { bytes: Uint8Array; length: number } {
+  const bytes = encoder.encode(text);
+  // bun:ffi rejects a pointer to an empty view, and the shim copies `length`
+  // bytes, so one padding byte is safe and keeps the pointer valid.
+  return { bytes: bytes.length === 0 ? new Uint8Array(1) : bytes, length: bytes.length };
+}
+
+/** Reads a NUL-terminated C string DuckDB owns. */
+export function readCString(pointer: Pointer | null): string | null {
+  return pointer === null ? null : new CString(pointer).toString();
+}
+
+/** Reads a C string DuckDB allocated for the caller, then frees it with duckdb_free. */
+export function takeCString(pointer: Pointer | null): string | null {
+  if (pointer === null) return null;
+  try {
+    return new CString(pointer).toString();
+  } finally {
+    duckdb.duckdb_free(pointer);
+  }
+}
+
+/** A pointer-sized out slot, such as the `duckdb_database *out` of duckdb_open. */
+export function slot(value: Pointer | null = null): BigUint64Array {
+  return new BigUint64Array([BigInt(value ?? 0)]);
+}
+
+export function slotValue(cell: BigUint64Array): Pointer | null {
+  const value = Number(cell[0]);
+  return value === 0 ? null : (value as Pointer);
+}
+
+/** A copy of `length` bytes at `pointer`, or an empty array for a null pointer. */
+export function copyBytes(pointer: Pointer | null, length: number): Uint8Array {
+  if (pointer === null || length === 0) return new Uint8Array(0);
+  return new Uint8Array(toArrayBuffer(pointer, 0, length).slice(0));
+}
+
+// --- structs ----------------------------------------------------------------------
+
+const BIGINT_FIELDS = new Set<FieldType>(["i64", "u64", "idx"]);
+const WIDE_INTEGERS = new Set<string>(["hugeint", "uhugeint"]);
+
+function readField(view: DataView, offset: number, type: FieldType): unknown {
+  switch (type) {
+    case "bool":
+      return view.getUint8(offset) !== 0;
+    case "i8":
+      return view.getInt8(offset);
+    case "u8":
+      return view.getUint8(offset);
+    case "i16":
+      return view.getInt16(offset, true);
+    case "u16":
+      return view.getUint16(offset, true);
+    case "i32":
+    case "TYPE":
+      return view.getInt32(offset, true);
+    case "u32":
+      return view.getUint32(offset, true);
+    case "i64":
+      return view.getBigInt64(offset, true);
+    case "u64":
+    case "idx":
+      return view.getBigUint64(offset, true);
+    case "f32":
+      return view.getFloat32(offset, true);
+    case "f64":
+      return view.getFloat64(offset, true);
+    case "ptr":
+      return Number(view.getBigUint64(offset, true));
+    default:
+      return decodeAt(type as LayoutName, view, offset);
+  }
+}
+
+function writeField(view: DataView, offset: number, type: FieldType, value: unknown): void {
+  switch (type) {
+    case "bool":
+      view.setUint8(offset, value ? 1 : 0);
+      return;
+    case "i8":
+      view.setInt8(offset, Number(value));
+      return;
+    case "u8":
+      view.setUint8(offset, Number(value));
+      return;
+    case "i16":
+      view.setInt16(offset, Number(value), true);
+      return;
+    case "u16":
+      view.setUint16(offset, Number(value), true);
+      return;
+    case "i32":
+    case "TYPE":
+      view.setInt32(offset, Number(value), true);
+      return;
+    case "u32":
+      view.setUint32(offset, Number(value), true);
+      return;
+    case "i64":
+      view.setBigInt64(offset, BigInt(value as bigint), true);
+      return;
+    case "u64":
+    case "idx":
+      view.setBigUint64(offset, BigInt(value as bigint), true);
+      return;
+    case "f32":
+      view.setFloat32(offset, Number(value), true);
+      return;
+    case "f64":
+      view.setFloat64(offset, Number(value), true);
+      return;
+    case "ptr":
+      view.setBigUint64(offset, BigInt(Number(value)), true);
+      return;
+    default:
+      encodeAt(type as LayoutName, view, offset, value);
+  }
+}
+
+function decodeAt(name: LayoutName, view: DataView, offset: number): unknown {
+  if (WIDE_INTEGERS.has(name)) {
+    const lower = view.getBigUint64(offset, true);
+    const upper = name === "hugeint" ? view.getBigInt64(offset + 8, true) : view.getBigUint64(offset + 8, true);
+    return (upper << 64n) | lower;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [field, spec] of Object.entries(layouts[name].fields)) {
+    out[field] = readField(view, offset + spec.offset, spec.type);
+  }
+  return out;
+}
+
+function encodeAt(name: LayoutName, view: DataView, offset: number, value: unknown): void {
+  if (WIDE_INTEGERS.has(name)) {
+    const wide = BigInt(value as bigint);
+    view.setBigUint64(offset, BigInt.asUintN(64, wide), true);
+    if (name === "hugeint") view.setBigInt64(offset + 8, BigInt.asIntN(64, wide >> 64n), true);
+    else view.setBigUint64(offset + 8, BigInt.asUintN(64, wide >> 64n), true);
+    return;
+  }
+  const fields = value as Record<string, unknown>;
+  for (const [field, spec] of Object.entries(layouts[name].fields)) {
+    writeField(view, offset + spec.offset, spec.type, fields[field]);
+  }
+}
+
+/** A zeroed buffer of the struct's C size, for an out parameter. */
+export function structBuffer(name: LayoutName): Uint8Array {
+  return new Uint8Array(layouts[name].size);
+}
+
+/** Encodes a contract object (or a bigint for hugeint/uhugeint) into the struct's C layout. */
+export function encode(name: LayoutName, value: unknown): Uint8Array {
+  const buffer = structBuffer(name);
+  encodeAt(name, new DataView(buffer.buffer), 0, value);
+  return buffer;
+}
+
+/** Decodes a struct from a buffer or from native memory into a contract object. */
+export function decode<T>(name: LayoutName, source: Uint8Array | Pointer): T {
+  const bytes = source instanceof Uint8Array ? source : new Uint8Array(toArrayBuffer(source, 0, layouts[name].size));
+  return decodeAt(name, new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), 0) as T;
+}
+
+/** True when the field type reads as a bigint, for callers that convert to number. */
+export function isBigIntField(type: FieldType): boolean {
+  return BIGINT_FIELDS.has(type);
+}
+
+export { read };

package/src/bindings/runtime/native.ts

@@ -0,0 +1,150 @@
+// Loads libduckdb and the Rust shim with bun:ffi. Every libduckdb C function the
+// binding calls goes through the shim's C++ exception boundary (native/ABI.md,
+// "C++ exceptions"): the shim hands over the address of a wrapper per function,
+// in the order of the tables generated from DuckDB's C API spec
+// (src/bindings/generated/capi.ts), and a call that caught a C++ exception throws
+// DuckDB's message as an Error. The shim's own exports follow native/ABI.md.
+import { CString, dlopen, type FFIFunction, FFIType, linkSymbols, type Pointer, toArrayBuffer } from "bun:ffi";
+import packageJson from "../../../package.json" with { type: "json" };
+import { nativePaths } from "../../library.ts";
+import { byValue, capi } from "../generated/capi.ts";
+import { exceptionMessage } from "./exception.ts";
+import { debug, flags } from "./flags.ts";
+
+/** The shim's exports from native/ABI.md, besides the generated by-value wrappers. */
+const shimAbi = {
+  dbs_init: { args: ["ptr", "ptr", "ptr"], returns: "i32" },
+  dbs_set_sync_call: { args: ["ptr"], returns: "void" },
+  dbs_context_close: { args: [], returns: "void" },
+  dbs_counters: { args: [], returns: "ptr" },
+  dbs_version: { args: [], returns: "cstring" },
+  dbs_capi_table: { args: ["ptr"], returns: "ptr" },
+  dbs_exception_flag: { args: [], returns: "ptr" },
+  dbs_take_exception: { args: [], returns: "ptr" },
+
+  dbs_job_open: { args: ["ptr", "usize", "bool", "ptr"], returns: "ptr" },
+  dbs_job_get_or_create_from_cache: { args: ["ptr", "ptr", "usize", "bool", "ptr"], returns: "ptr" },
+  dbs_job_connect: { args: ["ptr"], returns: "ptr" },
+  dbs_job_query: { args: ["ptr", "ptr", "usize"], returns: "ptr" },
+  dbs_job_prepare: { args: ["ptr", "ptr", "usize"], returns: "ptr" },
+  dbs_job_execute_prepared: { args: ["ptr"], returns: "ptr" },
+  dbs_job_execute_prepared_streaming: { args: ["ptr"], returns: "ptr" },
+  dbs_job_extract_statements: { args: ["ptr", "ptr", "usize"], returns: "ptr" },
+  dbs_job_prepare_extracted_statement: { args: ["ptr", "ptr", "u64"], returns: "ptr" },
+  dbs_job_execute_pending: { args: ["ptr"], returns: "ptr" },
+  dbs_job_fetch_chunk: { args: ["ptr"], returns: "ptr" },
+  dbs_job_failed: { args: ["ptr"], returns: "bool" },
+  dbs_job_error: { args: ["ptr"], returns: "ptr" },
+  dbs_job_out0: { args: ["ptr"], returns: "ptr" },
+  dbs_job_out1: { args: ["ptr"], returns: FFIType.u64_fast },
+  dbs_job_free: { args: ["ptr"], returns: "void" },
+
+  dbs_scalar_function_set_callbacks: { args: ["ptr", "u64", "bool", "bool"], returns: "void" },
+  dbs_table_function_set_callbacks: { args: ["ptr", "u64", "bool", "bool", "bool"], returns: "void" },
+  dbs_set_bind_data: { args: ["ptr", "u32", "u64"], returns: "void" },
+  dbs_get_bind_data: { args: ["ptr", "u32"], returns: FFIType.u64_fast },
+  dbs_set_init_data: { args: ["ptr", "u64"], returns: "void" },
+  dbs_get_init_data: { args: ["ptr"], returns: FFIType.u64_fast },
+  dbs_get_local_init_data: { args: ["ptr"], returns: FFIType.u64_fast },
+  dbs_scalar_init_set_state: { args: ["ptr", "u64"], returns: "void" },
+  dbs_scalar_get_state: { args: ["ptr"], returns: FFIType.u64_fast },
+  dbs_call_done: { args: ["ptr"], returns: "void" },
+
+  dbs_ring_record: { args: ["u32", "u32", "u64", "u64", "ptr", "usize"], returns: "void" },
+  dbs_install_crash_handler: { args: ["ptr", "usize"], returns: "i32" },
+  dbs_crash_for_test: { args: ["u32"], returns: "void" },
+} as const satisfies Record<string, FFIFunction>;
+
+const paths = nativePaths();
+
+// libduckdb first, by absolute path, so the shim's own dependency on it resolves
+// to this already-loaded image. The binding calls it only through the shim.
+const library = dlopen(paths.libPath, { duckdb_library_version: { args: [], returns: "ptr" } });
+const shimLibrary = dlopen(paths.shimPath, shimAbi).symbols;
+
+/** The wrappers' addresses, `capi` entries first, then `byValue` ones. */
+const addresses = (() => {
+  const count = new BigUint64Array(1);
+  const table = shimLibrary.dbs_capi_table(count) as Pointer;
+  const expected = Object.keys(capi).length + Object.keys(byValue).length;
+  if (Number(count[0]) !== expected) {
+    throw new Error(`The shim at ${paths.shimPath} has ${count[0]} C API wrappers; this binding needs ${expected}.`);
+  }
+  return new BigUint64Array(toArrayBuffer(table, 0, expected * 8));
+})();
+
+/** `table` with each function's wrapper address, starting at `offset` in the address table. */
+function located<T extends Record<string, FFIFunction>>(table: T, offset: number): T {
+  return Object.fromEntries(
+    Object.entries(table).map(([name, fn], i) => [name, { ...fn, ptr: addresses[offset + i] }]),
+  ) as T;
+}
+
+/** The calling JS thread's C++ exception flag, set by a wrapper that caught one. */
+const exceptionFlag = new Int32Array(toArrayBuffer(shimLibrary.dbs_exception_flag() as Pointer, 0, 4));
+const rawCapi = linkSymbols(located(capi, 0)).symbols;
+const rawByValue = linkSymbols(located(byValue, Object.keys(capi).length)).symbols;
+
+/** Throws the C++ exception the last call caught, with DuckDB's message for it. */
+function raise(): never {
+  const pointer = shimLibrary.dbs_take_exception() as Pointer | null;
+  let what: string | null = null;
+  if (pointer !== null) {
+    try {
+      what = new CString(pointer).toString();
+    } finally {
+      rawCapi.duckdb_free(pointer);
+    }
+  }
+  throw new Error(exceptionMessage(what));
+}
+
+/**
+ * `raw` with each function wrapped to throw, through `raise`, when the call set the
+ * calling thread's exception flag. One shared wrapper costs about a nanosecond a
+ * call over one generated per function, against about 20 for the call itself.
+ */
+function guarded<T extends Record<string, unknown>>(raw: T): T {
+  const out: Record<string, unknown> = {};
+  for (const [name, fn] of Object.entries(raw)) {
+    const call = fn as (...args: unknown[]) => unknown;
+    out[name] = (...args: unknown[]) => {
+      const result = call(...args);
+      if (exceptionFlag[0] !== 0) raise();
+      return result;
+    };
+  }
+  return out as T;
+}
+
+export const duckdb = guarded(rawCapi);
+export const shim = { ...guarded(rawByValue), ...shimLibrary };
+export const libraryPath = paths.libPath;
+export const shimPath = paths.shimPath;
+
+/** The versions a crash report and diagnostics() name. */
+export const versions = {
+  package: packageJson.version,
+  duckdb: new CString(library.symbols.duckdb_library_version() as Pointer).toString(),
+  bun: Bun.version,
+  shim: String(shim.dbs_version()),
+} as const;
+
+debug(`loaded libduckdb ${versions.duckdb} from ${libraryPath}, shim ${versions.shim} from ${shimPath}`);
+
+const CRASH_HANDLER_STATUS = ["installed", "failed: no alternate signal stack", "failed: sigaction"] as const;
+
+/** The fatal-signal handler's state: native/ABI.md "Diagnostics". */
+export const crashHandler: "disabled" | (typeof CRASH_HANDLER_STATUS)[number] = flags.crashHandler
+  ? installCrashHandler()
+  : "disabled";
+
+function installCrashHandler(): (typeof CRASH_HANDLER_STATUS)[number] {
+  const header = Buffer.from(
+    `package ${versions.package}, duckdb ${versions.duckdb}, bun ${versions.bun}, shim ${versions.shim}`,
+  );
+  const status = CRASH_HANDLER_STATUS[shim.dbs_install_crash_handler(header, header.length)] ?? "failed: sigaction";
+  // Queries work without the handler, so a failed install is not an error: diagnostics() reports it.
+  debug(`crash handler ${status}`);
+  return status;
+}

package/src/bindings/runtime/ring.ts

@@ -0,0 +1,54 @@
+// Records binding events into the shim's crash-forensics ring (native/ABI.md,
+// "Diagnostics"). Jobs record their own start and end in the shim; JavaScript
+// records the events that happen on the JS thread.
+import type { Pointer } from "bun:ffi";
+import { shim } from "./native.ts";
+
+/** Op codes from native/ABI.md. */
+export const RingOp = {
+  close: 32,
+  disconnect: 33,
+  destroyResult: 34,
+  destroyPending: 35,
+  destroyPrepared: 36,
+  interrupt: 37,
+  registerScalarFunction: 38,
+  registerTableFunction: 39,
+  appenderFlush: 40,
+  appenderClose: 41,
+  pendingExecuteTask: 42,
+} as const;
+
+/** The shim's jobs, in native/ABI.md table order; a job's op code is its position plus one. */
+const JOB_OPS = [
+  "open",
+  "get_or_create_from_cache",
+  "connect",
+  "query",
+  "prepare",
+  "execute_prepared",
+  "execute_prepared_streaming",
+  "extract_statements",
+  "prepare_extracted_statement",
+  "execute_pending",
+  "fetch_chunk",
+] as const;
+
+/** The ring op code of a job, by its contract function name; 0 for none. */
+export function jobOp(name: string): number {
+  return JOB_OPS.indexOf(name as (typeof JOB_OPS)[number]) + 1;
+}
+
+const STATE_EVENT = 4;
+const TEXT_MAX = 120;
+const encoder = new TextEncoder();
+const empty = new Uint8Array(1);
+
+/**
+ * Appends one event. `text` must already be redacted (see diagnostics.ts); it is
+ * truncated to the ring's 120 bytes.
+ */
+export function record(op: number, handle: Pointer | null, connectionId = 0, text?: string): void {
+  const bytes = text ? encoder.encode(text).subarray(0, TEXT_MAX) : empty;
+  shim.dbs_ring_record(op, STATE_EVENT, handle ?? 0, connectionId, bytes, text ? bytes.length : 0);
+}

package/src/bindings/runtime/scope.ts

@@ -0,0 +1,133 @@
+// Native memory handed to JavaScript, and what a function callback hands out.
+//
+// Copies. The official binding returns vector data, validity masks and string
+// bytes with Napi::Buffer::NewOrCopy under NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+// (src/napi_setup.h), so each is a copy: writes reach the vector only through
+// copy_data_to_vector. Each copy is mapped to the handle that owns the memory it
+// came from, so get_data_from_pointer can follow a string pointer in the copy
+// only while that memory is alive, and a reachable copy keeps its vector, and
+// through the vector its data chunk, from being collected.
+//
+// Callback scopes. The info, data chunk and vector a function callback receives
+// are borrowed for the length of the call: DuckDB frees or reuses them once the
+// callback returns. A scope collects those handles and every handle derived from
+// them (a chunk's vectors, a vector's children), then invalidates them when the
+// callback returns, so a use after the callback throws instead of touching freed
+// memory.
+//
+// User data. JavaScript objects handed to DuckDB (bind data, init data, scalar
+// function state) cross as ids (native/ABI.md, "Function callbacks"); the
+// objects live here until the shim reports that DuckDB dropped the id.
+
+import { type Pointer, toArrayBuffer } from "bun:ffi";
+import { expectReferenceable } from "./convert.ts";
+import { allocateId, onRelease } from "./dispatch.ts";
+import { Handle } from "./handle.ts";
+
+// --- callback scopes ------------------------------------------------------------------
+
+const scopes = new WeakMap<object, CallbackScope>();
+
+export class CallbackScope {
+  readonly #handles: Handle[] = [];
+
+  /** Adds a handle that dies with the callback. */
+  adopt<T extends Handle>(handle: T): T {
+    this.#handles.push(handle);
+    scopes.set(handle, this);
+    return handle;
+  }
+
+  /** Invalidates every handle the callback was given or derived. */
+  close(): void {
+    for (const handle of this.#handles) handle.invalidate();
+    this.#handles.length = 0;
+  }
+}
+
+/**
+ * A handle derived from `owner` (a vector of a chunk, a child of a vector):
+ * when the owner belongs to a callback, the derived handle dies with it too.
+ */
+export function derived<T extends Handle>(owner: object, handle: T): T {
+  scopes.get(owner)?.adopt(handle);
+  return handle;
+}
+
+// --- copies of native memory ----------------------------------------------------------
+
+/** The handle that owns the memory each copy came from. */
+const owners = new WeakMap<ArrayBuffer, Handle>();
+
+/**
+ * A Buffer holding a copy of `length` bytes of native memory at `pointer`, owned
+ * by `owner`. A null pointer or a zero length gives an empty Buffer.
+ */
+export function nativeCopy(pointer: Pointer | number | null, length: number, owner: Handle | undefined): Buffer {
+  if (!pointer || length === 0) return Buffer.alloc(0);
+  const copy = Buffer.from(new Uint8Array(toArrayBuffer(pointer as Pointer, 0, length)));
+  if (owner !== undefined) owners.set(copy.buffer as ArrayBuffer, owner);
+  return copy;
+}
+
+/**
+ * The owner of the memory a copy came from, so a string pointer inside the copy
+ * can be followed. Throws when that memory is gone: its handle, or a handle it
+ * borrows from, was destroyed or belonged to a callback that has returned.
+ */
+export function liveOwnerOfBuffer(buffer: ArrayBuffer): Handle | undefined {
+  const owner = owners.get(buffer);
+  for (let handle: unknown = owner; handle instanceof Handle; handle = handle.owner) {
+    if (handle.ptr === null) throw new Error(`Invalid ${handle.kind} argument`);
+  }
+  return owner;
+}
+
+// --- user data ---------------------------------------------------------------------------
+
+const userData = new Map<number, unknown>();
+
+/** Stores `value` under a new id that is dropped when DuckDB releases it. */
+export function storeUserData(value: unknown): number {
+  expectReferenceable(value);
+  const id = allocateId();
+  userData.set(id, value);
+  onRelease(id, () => userData.delete(id));
+  return id;
+}
+
+/** The value stored under `id`, or undefined for 0 (none) or a released id. */
+export function userDataOf(id: number | bigint): unknown {
+  return userData.get(Number(id));
+}
+
+// --- running user callbacks ----------------------------------------------------------------
+
+/**
+ * The message DuckDB reports for a thrown value, as the official binding's
+ * Napi::Error::Message(): the value's "message" property when the value is an
+ * object and that property is a string, otherwise an empty message. A thrown
+ * string therefore fails the query with "Invalid Input Error: " and no text.
+ */
+export function messageOf(error: unknown): string {
+  if ((typeof error === "object" && error !== null) || typeof error === "function") {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === "string") return message;
+  }
+  return "";
+}
+
+/**
+ * Runs a user callback inside `scope`. A throw is reported through `setError`,
+ * as the official binding's DuckDBThreadCallbackDispatch does, and the scope is
+ * closed whatever happens.
+ */
+export function runInScope(scope: CallbackScope, run: () => void, setError: (message: string) => void): void {
+  try {
+    run();
+  } catch (error) {
+    setError(messageOf(error));
+  } finally {
+    scope.close();
+  }
+}

package/src/bindings/runtime/trace.ts

@@ -0,0 +1,65 @@
+// Tracing of native calls: the "duckdb-bun:call" tracing channel, debug lines,
+// and the SQL text kept for crash reports, all with credentials redacted.
+import { tracingChannel } from "node:diagnostics_channel";
+import { debug, flags } from "./flags.ts";
+
+/** What a traced native call publishes as the tracing channel's context. */
+export interface CallContext {
+  /** The contract function, such as "query" or "connect". */
+  op: string;
+  /** The statement, redacted, only when DUCKDB_BUN_TRACE_SQL=1. */
+  sql?: string;
+  /** Set by the channel when the call resolves. */
+  result?: unknown;
+  /** Set by the channel when the call rejects. */
+  error?: unknown;
+}
+
+export const CALL_CHANNEL = "duckdb-bun:call";
+
+const channel = tracingChannel<object, CallContext>(CALL_CHANNEL);
+const subChannels = [channel.start, channel.end, channel.asyncStart, channel.asyncEnd, channel.error];
+
+// Statements that can carry credentials: CREATE SECRET, ATTACH with a
+// connection string, and settings or options that name a key, token or password.
+// Matched anywhere, also inside identifiers such as s3_secret_access_key; a false
+// match only redacts more.
+const SENSITIVE = /secret|attach|passw|token|credential|key_id|access_key|account_key|account_name|connection_string/i;
+
+// Single-quoted literals ('' escapes a quote; an unterminated one runs to the
+// end) and dollar-quoted strings.
+const LITERAL = /'(?:[^']|'')*(?:'|$)|\$([A-Za-z_]\w*)?\$[\s\S]*?(?:\$\1\$|$)/g;
+
+/** Replaces every string literal with '<redacted>' in a statement that can carry credentials. */
+export function redactSql(sql: string): string {
+  return SENSITIVE.test(sql) ? sql.replace(LITERAL, "'<redacted>'") : sql;
+}
+
+/** The context for one call; SQL is redacted and kept only when DUCKDB_BUN_TRACE_SQL=1. */
+export function callContext(op: string, sql?: string): CallContext {
+  return flags.traceSql && sql !== undefined ? { op, sql: redactSql(sql) } : { op };
+}
+
+/**
+ * Runs `call` inside the tracing channel when anything subscribes, and logs its
+ * outcome and duration when DUCKDB_BUN_DEBUG=1.
+ */
+export function traced<T>(context: CallContext, call: () => Promise<T>): Promise<T> {
+  const subscribed = subChannels.some((sub) => sub.hasSubscribers);
+  if (!subscribed && !flags.debug) return call();
+  const promise = subscribed ? channel.tracePromise(call, context) : call();
+  if (!flags.debug) return promise;
+  const started = performance.now();
+  const label = context.sql === undefined ? context.op : `${context.op} ${JSON.stringify(context.sql)}`;
+  const elapsed = () => `${(performance.now() - started).toFixed(2)}ms`;
+  return promise.then(
+    (value) => {
+      debug(`${label} ok ${elapsed()}`);
+      return value;
+    },
+    (error: unknown) => {
+      debug(`${label} error ${elapsed()}: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    },
+  );
+}

package/src/connection.ts

@@ -0,0 +1,35 @@
+import type { DuckDBConnection as OfficialConnection } from "../vendor/node-api/src/index.ts";
+import { asDuckDBError } from "./errors.ts";
+import { type Reader, readerFrom } from "./reader.ts";
+import { PreparedStatement } from "./statement.ts";
+
+/** A DuckDB connection. Drop-in for the @duckdb/node-api slice used downstream. */
+export class DuckDBConnection {
+  #connection: OfficialConnection;
+  #closed = false;
+
+  constructor(connection: OfficialConnection) {
+    this.#connection = connection;
+  }
+
+  /** Execute a statement and ignore any result rows. */
+  async run(sql: string): Promise<void> {
+    await asDuckDBError(() => this.#connection.run(sql));
+  }
+
+  /** Execute a query and read every row into a Reader. */
+  async runAndReadAll(sql: string): Promise<Reader> {
+    return readerFrom(await asDuckDBError(() => this.#connection.runAndReadAll(sql)));
+  }
+
+  /** Prepare a parameterized statement. */
+  async prepare(sql: string): Promise<PreparedStatement> {
+    return new PreparedStatement(await asDuckDBError(() => this.#connection.prepare(sql)));
+  }
+
+  closeSync(): void {
+    if (this.#closed) return;
+    this.#connection.closeSync();
+    this.#closed = true;
+  }
+}

package/src/database.ts

@@ -0,0 +1,27 @@
+import { DuckDBInstance as OfficialInstance } from "../vendor/node-api/src/index.ts";
+import { DuckDBConnection } from "./connection.ts";
+import { asDuckDBError } from "./errors.ts";
+
+/** A DuckDB database instance. Use `:memory:` for an ephemeral in-memory DB. */
+export class DuckDBInstance {
+  #instance: OfficialInstance;
+  #closed = false;
+
+  private constructor(instance: OfficialInstance) {
+    this.#instance = instance;
+  }
+
+  static async create(path = ":memory:"): Promise<DuckDBInstance> {
+    return new DuckDBInstance(await asDuckDBError(() => OfficialInstance.create(path)));
+  }
+
+  async connect(): Promise<DuckDBConnection> {
+    return new DuckDBConnection(await asDuckDBError(() => this.#instance.connect()));
+  }
+
+  closeSync(): void {
+    if (this.#closed) return;
+    this.#instance.closeSync();
+    this.#closed = true;
+  }
+}