@sqldoc/db 0.0.3

package/package.json

@@ -0,0 +1,41 @@
+{
+  "type": "module",
+  "name": "@sqldoc/db",
+  "version": "0.0.3",
+  "description": "Atlas WASI integration for sqldoc -- schema types, database adapters, WASI runner",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "wasm",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test 'src/__tests__/**/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "build:wasm": "cd ../../../atlastest/atlas/cmd/atlas-wasi && GOOS=wasip1 GOARCH=wasm go build -o atlas.wasm . && cp atlas.wasm ../../../../sqldoc/packages/db/wasm/atlas.wasm",
+    "codegen:schema": "echo 'Types hand-crafted from atlas/sql/schema/schema.go -- see src/types.ts. tygo cannot handle Go interfaces (Attr, Type, Expr). Re-read schema.go and update src/types.ts manually when the Go source changes.'"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.4.0",
+    "@testcontainers/postgresql": "^11.13.0",
+    "mysql2": "^3.20.0",
+    "pg": "^8.13.0",
+    "picocolors": "catalog:",
+    "testcontainers": "^11.13.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.0",
+    "tsx": "^4.21.0",
+    "typescript": "catalog:",
+    "@sqldoc/test-utils": "workspace:*"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,152 @@
+/**
+ * Sync/async bridge for atlas_sql host function.
+ *
+ * Architecture:
+ * - Worker thread runs WASI module, calls atlas_sql synchronously
+ * - atlas_sql writes SQL request to shared buffer, signals main thread, blocks via Atomics.wait
+ * - Main thread receives request, runs async DB query, writes response, signals via Atomics.notify
+ *
+ * Control buffer layout (Int32Array over SharedArrayBuffer):
+ *   [0] = signal: 0=idle, 1=request_ready, 2=response_ready, 3=done
+ *   [1] = data length (request or response)
+ */
+
+// Signal constants
+export const SIGNAL_IDLE = 0
+export const SIGNAL_REQUEST = 1
+export const SIGNAL_RESPONSE = 2
+export const SIGNAL_DONE = 3
+
+/**
+ * Shared buffers passed between main and worker thread.
+ */
+export interface BridgeBuffers {
+  /** 8 bytes: signal (Int32) + data length (Int32) */
+  control: SharedArrayBuffer
+  /** Data exchange buffer (default 1MB, resizable) */
+  data: SharedArrayBuffer
+}
+
+/**
+ * Create shared buffers for bridge communication.
+ * @param dataSize Initial data buffer size in bytes (default 1MB)
+ */
+export function createBridgeBuffers(dataSize = 1024 * 1024): BridgeBuffers {
+  return {
+    control: new SharedArrayBuffer(8),
+    data: new SharedArrayBuffer(dataSize),
+  }
+}
+
+// ── Worker-side (synchronous) ───────────────────────────────────────
+
+/**
+ * Write a request to the shared buffer and block until a response is available.
+ * Called from the worker thread inside the atlas_sql host function.
+ *
+ * @returns Response JSON string
+ */
+export function bridgeRequest(buffers: BridgeBuffers, requestJson: string): string {
+  const control = new Int32Array(buffers.control)
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+
+  // Write request to data buffer
+  const encoded = encoder.encode(requestJson)
+  if (encoded.byteLength > buffers.data.byteLength) {
+    throw new Error(`Bridge request too large: ${encoded.byteLength} bytes > ${buffers.data.byteLength} buffer`)
+  }
+  new Uint8Array(buffers.data).set(encoded)
+
+  // Store length and signal request ready
+  Atomics.store(control, 1, encoded.byteLength)
+  Atomics.store(control, 0, SIGNAL_REQUEST)
+  Atomics.notify(control, 0)
+
+  // Block until response is ready (value changes from SIGNAL_REQUEST)
+  Atomics.wait(control, 0, SIGNAL_REQUEST)
+
+  // Read response
+  const signal = Atomics.load(control, 0)
+  if (signal === SIGNAL_DONE) {
+    throw new Error('Bridge terminated while waiting for response')
+  }
+
+  const respLen = Atomics.load(control, 1)
+  const respBytes = new Uint8Array(buffers.data, 0, respLen)
+  const response = decoder.decode(respBytes.slice())
+
+  // Reset signal to idle for next round-trip
+  Atomics.store(control, 0, SIGNAL_IDLE)
+
+  return response
+}
+
+// ── Main-thread side (asynchronous) ─────────────────────────────────
+
+/**
+ * Wait for the worker to post a request. Uses Atomics.waitAsync
+ * (non-blocking on the main thread).
+ *
+ * @returns The current signal value after waking
+ */
+export async function bridgeWaitForSignal(buffers: BridgeBuffers): Promise<number> {
+  const control = new Int32Array(buffers.control)
+
+  // If signal is already non-idle, return immediately
+  const current = Atomics.load(control, 0)
+  if (current !== SIGNAL_IDLE) {
+    return current
+  }
+
+  // Wait asynchronously for signal to change from IDLE
+  const result = Atomics.waitAsync(control, 0, SIGNAL_IDLE)
+  if (result.async) {
+    await result.value
+  }
+  return Atomics.load(control, 0)
+}
+
+/**
+ * Read the request JSON from the shared data buffer.
+ * Call after bridgeWaitForSignal returns SIGNAL_REQUEST.
+ */
+export function bridgeReadRequest(buffers: BridgeBuffers): string {
+  const control = new Int32Array(buffers.control)
+  const reqLen = Atomics.load(control, 1)
+  const reqBytes = new Uint8Array(buffers.data, 0, reqLen)
+  return new TextDecoder().decode(reqBytes.slice())
+}
+
+/**
+ * Write a response to the shared buffer and notify the worker.
+ */
+export function bridgeRespond(buffers: BridgeBuffers, responseJson: string): void {
+  const control = new Int32Array(buffers.control)
+  const encoded = new TextEncoder().encode(responseJson)
+
+  if (encoded.byteLength > buffers.data.byteLength) {
+    // Write an error response instead -- the data buffer is too small
+    const errorResp = JSON.stringify({
+      error: `Response too large: ${encoded.byteLength} bytes exceeds ${buffers.data.byteLength} byte buffer`,
+    })
+    const errorEncoded = new TextEncoder().encode(errorResp)
+    new Uint8Array(buffers.data).set(errorEncoded)
+    Atomics.store(control, 1, errorEncoded.byteLength)
+  } else {
+    new Uint8Array(buffers.data).set(encoded)
+    Atomics.store(control, 1, encoded.byteLength)
+  }
+
+  Atomics.store(control, 0, SIGNAL_RESPONSE)
+  Atomics.notify(control, 0)
+}
+
+/**
+ * Signal the worker that processing is done (no more commands).
+ */
+export function bridgeSignalDone(buffers: BridgeBuffers): void {
+  const control = new Int32Array(buffers.control)
+  Atomics.store(control, 0, SIGNAL_DONE)
+  Atomics.notify(control, 0)
+}

package/src/db/mysql-docker.ts

@@ -0,0 +1,54 @@
+/**
+ * MySQL Docker adapter using testcontainers GenericContainer.
+ * Uses log-based wait strategy (same as Postgres adapter) for Bun compatibility —
+ * MySqlContainer's built-in health check hangs in Bun's runtime.
+ */
+import { GenericContainer, Wait } from 'testcontainers'
+import { createMysqlAdapter } from './mysql.ts'
+import type { DatabaseAdapter } from './types.ts'
+
+/**
+ * Create a Docker-based MySQL DatabaseAdapter using testcontainers.
+ * Supports: docker://mysql:8, docker://mysql:8.0, docker://mariadb:10, etc.
+ */
+export async function createMysqlDockerAdapter(devUrl: string): Promise<DatabaseAdapter> {
+  const imageName = devUrl.slice('docker://'.length)
+
+  const container = await new GenericContainer(imageName)
+    .withEnvironment({
+      MYSQL_ROOT_PASSWORD: 'sqldoc',
+      MYSQL_DATABASE: 'sqldoc_dev',
+    })
+    .withExposedPorts(3306)
+    .withWaitStrategy(Wait.forLogMessage(/ready for connections.*port: 3306/, 2))
+    .start()
+
+  const host = container.getHost()
+  const port = container.getMappedPort(3306)
+  const connectionUri = `mysql://root:sqldoc@${host}:${port}/sqldoc_dev`
+
+  // Retry connection — container may need a moment after port is mapped
+  let mysqlAdapter: DatabaseAdapter | undefined
+  for (let i = 0; i < 10; i++) {
+    try {
+      mysqlAdapter = await createMysqlAdapter(connectionUri)
+      break
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+    }
+  }
+
+  if (!mysqlAdapter) {
+    await container.stop()
+    throw new Error(`Failed to connect to Docker MySQL at ${connectionUri}`)
+  }
+
+  return {
+    query: mysqlAdapter.query,
+    exec: mysqlAdapter.exec,
+    async close() {
+      await mysqlAdapter.close()
+      await container.stop()
+    },
+  }
+}

package/src/db/mysql.ts

@@ -0,0 +1,44 @@
+/**
+ * MySQL DatabaseAdapter using mysql2/promise.
+ * Single connection (no pooling) -- sufficient for schema inspection.
+ */
+import mysql from 'mysql2/promise'
+import type { DatabaseAdapter, ExecResult, QueryResult } from './types.ts'
+
+/**
+ * Normalize row values to types the Go database/sql driver can scan.
+ * mysql2 returns Date objects for datetime, Buffer for binary, BigInt for BIGINT.
+ */
+function normalizeValue(val: unknown): unknown {
+  if (val === null || val === undefined) return null
+  if (typeof val === 'bigint') return val.toString()
+  if (val instanceof Date) return val.toISOString()
+  if (Buffer.isBuffer(val)) return val.toString('hex')
+  if (typeof val === 'object') return JSON.stringify(val)
+  return val
+}
+
+/**
+ * Create a MySQL DatabaseAdapter connected to an existing MySQL instance.
+ * Uses mysql2/promise for async connection management.
+ */
+export async function createMysqlAdapter(connectionString: string): Promise<DatabaseAdapter> {
+  const connection = await mysql.createConnection(connectionString)
+
+  return {
+    async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+      const [rows, fields] = await connection.query({ sql, values: args, rowsAsArray: true })
+      return {
+        columns: (fields as mysql.FieldPacket[]).map((f) => f.name),
+        rows: (rows as unknown[][]).map((row) => (row as unknown[]).map(normalizeValue)),
+      }
+    },
+    async exec(sql: string, args?: unknown[]): Promise<ExecResult> {
+      const [result] = await connection.query(sql, args as any)
+      return { rowsAffected: (result as mysql.ResultSetHeader).affectedRows ?? 0 }
+    },
+    async close(): Promise<void> {
+      await connection.end()
+    },
+  }
+}

package/src/db/pglite.ts

@@ -0,0 +1,77 @@
+import { PGlite } from '@electric-sql/pglite'
+import type { DatabaseAdapter, ExecResult, QueryResult } from './types.ts'
+
+/**
+ * Normalize a row value to a type the Go database/sql driver can scan.
+ */
+function normalizeValue(val: unknown): unknown {
+  if (val === null || val === undefined) return null
+  if (typeof val === 'bigint') return val.toString()
+  if (val instanceof Date) return val.toISOString()
+  if (typeof val === 'object') {
+    return JSON.stringify(val, (_k, v) => (typeof v === 'bigint' ? v.toString() : v))
+  }
+  return val
+}
+
+/**
+ * Dynamically load a pglite extension.
+ * Tries @electric-sql/pglite/contrib/{name} first (most extensions),
+ * then @electric-sql/pglite/{name} (built-in extensions like live).
+ * Returns the extension object or null if not available.
+ */
+async function loadPgliteExtension(name: string): Promise<any | null> {
+  // Try contrib first (most extensions live here)
+  try {
+    const mod = await import(`@electric-sql/pglite/contrib/${name}`)
+    return mod.default ?? mod[name] ?? mod
+  } catch {
+    /* not in contrib */
+  }
+
+  // Try top-level (built-in extensions like live, vector)
+  try {
+    const mod = await import(`@electric-sql/pglite/${name}`)
+    return mod.default ?? mod[name] ?? mod
+  } catch {
+    /* not available */
+  }
+
+  return null
+}
+
+/**
+ * Create a pglite-based DatabaseAdapter (in-memory, zero-config).
+ * Optionally loads extensions from @electric-sql/pglite/contrib.
+ */
+export async function createPgliteAdapter(extensions?: string[]): Promise<DatabaseAdapter> {
+  const extModules: Record<string, any> = {}
+  for (const ext of extensions ?? []) {
+    const mod = await loadPgliteExtension(ext)
+    if (mod) {
+      extModules[ext] = mod
+    }
+  }
+
+  const db = await PGlite.create({
+    extensions: Object.keys(extModules).length > 0 ? extModules : undefined,
+  })
+
+  return {
+    async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+      const result = await db.query(sql, args, { rowMode: 'array' })
+      return {
+        columns: result.fields.map((f: { name: string }) => f.name),
+        rows: (result.rows as unknown[][]).map((row) => row.map(normalizeValue)),
+      }
+    },
+    async exec(sql: string): Promise<ExecResult> {
+      const result = await db.exec(sql)
+      const last = result[result.length - 1]
+      return { rowsAffected: last?.affectedRows ?? 0 }
+    },
+    async close(): Promise<void> {
+      await db.close()
+    },
+  }
+}

package/src/db/postgres-docker.ts

@@ -0,0 +1,91 @@
+import * as path from 'node:path'
+import { PostgreSqlContainer } from '@testcontainers/postgresql'
+import { GenericContainer, Wait } from 'testcontainers'
+import { createPostgresAdapter } from './postgres.ts'
+import type { DatabaseAdapter } from './types.ts'
+
+/**
+ * Create a Docker-based DatabaseAdapter using testcontainers.
+ * Spins up an ephemeral Postgres container, connects via pg, and
+ * automatically cleans up on close() (testcontainers + Ryuk handle
+ * orphan cleanup even on process crash).
+ *
+ * Supports:
+ *   docker://postgres:16        — official or custom image
+ *   dockerfile://path/to/file   — build from Dockerfile
+ */
+export async function createPostgresDockerAdapter(devUrl: string): Promise<DatabaseAdapter> {
+  if (devUrl.startsWith('dockerfile://')) {
+    return createFromDockerfile(devUrl.slice('dockerfile://'.length))
+  }
+
+  // docker://image:tag
+  const imageName = devUrl.slice('docker://'.length)
+  const container = await new PostgreSqlContainer(imageName)
+    .withDatabase('sqldoc_dev')
+    .withUsername('sqldoc')
+    .withPassword('sqldoc')
+    .withExposedPorts(5432)
+    .withWaitStrategy(Wait.forLogMessage('database system is ready to accept connections', 2))
+    .start()
+
+  const pgAdapter = await createPostgresAdapter(container.getConnectionUri())
+
+  return {
+    query: pgAdapter.query,
+    exec: pgAdapter.exec,
+    async close() {
+      await pgAdapter.close()
+      await container.stop()
+    },
+  }
+}
+
+async function createFromDockerfile(dockerfilePath: string): Promise<DatabaseAdapter> {
+  const absPath = path.resolve(dockerfilePath)
+  const dir = path.dirname(absPath)
+  const file = path.basename(absPath)
+
+  const image = await GenericContainer.fromDockerfile(dir, file).build()
+
+  const container = await image
+    .withEnvironment({
+      POSTGRES_DB: 'sqldoc_dev',
+      POSTGRES_USER: 'sqldoc',
+      POSTGRES_PASSWORD: 'sqldoc',
+    })
+    .withExposedPorts(5432)
+    .withWaitStrategy(Wait.forLogMessage('database system is ready to accept connections', 2))
+    .withStartupTimeout(30_000)
+    .start()
+
+  // Wait for postgres to accept connections
+  const host = container.getHost()
+  const port = container.getMappedPort(5432)
+  const connectionUri = `postgres://sqldoc:sqldoc@${host}:${port}/sqldoc_dev`
+
+  // Retry connection — container may need a moment after port is mapped
+  let pgAdapter: DatabaseAdapter | undefined
+  for (let i = 0; i < 10; i++) {
+    try {
+      pgAdapter = await createPostgresAdapter(connectionUri)
+      break
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+    }
+  }
+
+  if (!pgAdapter) {
+    await container.stop()
+    throw new Error(`Failed to connect to Docker Postgres at ${connectionUri}`)
+  }
+
+  return {
+    query: pgAdapter.query,
+    exec: pgAdapter.exec,
+    async close() {
+      await pgAdapter.close()
+      await container.stop()
+    },
+  }
+}

package/src/db/postgres.ts

@@ -0,0 +1,44 @@
+import { Client } from 'pg'
+import type { DatabaseAdapter, ExecResult, QueryResult } from './types.ts'
+
+/**
+ * Normalize row values to types the Go database/sql driver can scan.
+ * The WASI JSON protocol expects strings, numbers, booleans, and null.
+ */
+function normalizeValue(val: unknown): unknown {
+  if (val === null || val === undefined) return null
+  if (typeof val === 'bigint') return val.toString()
+  if (val instanceof Date) return val.toISOString()
+  if (Buffer.isBuffer(val)) return val.toString('hex')
+  if (typeof val === 'object') {
+    return JSON.stringify(val, (_k, v) => (typeof v === 'bigint' ? v.toString() : v))
+  }
+  return val
+}
+
+/**
+ * Create a postgres-based DatabaseAdapter using the pg library.
+ * Connects to an external Postgres instance via connection string.
+ */
+export async function createPostgresAdapter(connectionString: string): Promise<DatabaseAdapter> {
+  const client = new Client({ connectionString })
+  await client.connect()
+  return {
+    async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+      // Use rowMode: 'array' to get positional values, not name-keyed objects.
+      // This handles duplicate column names (e.g. multiple current_setting() calls).
+      const result = await client.query({ text: sql, values: args, rowMode: 'array' })
+      return {
+        columns: result.fields.map((f: { name: string }) => f.name),
+        rows: (result.rows as unknown[][]).map((row) => row.map(normalizeValue)),
+      }
+    },
+    async exec(sql: string): Promise<ExecResult> {
+      const result = await client.query(sql)
+      return { rowsAffected: result.rowCount ?? 0 }
+    },
+    async close(): Promise<void> {
+      await client.end()
+    },
+  }
+}

package/src/db/sqlite.ts

@@ -0,0 +1,104 @@
+/**
+ * SQLite DatabaseAdapter with runtime detection.
+ * Uses bun:sqlite when running in Bun, node:sqlite when running in Node.
+ * Both are synchronous APIs wrapped in async methods to match the DatabaseAdapter interface.
+ */
+import type { SQLInputValue } from 'node:sqlite'
+import type { DatabaseAdapter, ExecResult, QueryResult } from './types.ts'
+
+/**
+ * Normalize row values to types the Go database/sql driver can scan.
+ * SQLite returns integers for booleans, stores dates as strings or numbers.
+ */
+function normalizeValue(val: unknown): unknown {
+  if (val === null || val === undefined) return null
+  if (typeof val === 'bigint') return val.toString()
+  if (val instanceof Uint8Array || Buffer.isBuffer(val)) return Buffer.from(val).toString('hex')
+  if (typeof val === 'object') return JSON.stringify(val)
+  return val
+}
+
+/**
+ * Create a SQLite adapter using node:sqlite (Node.js 22.5+).
+ * Uses the built-in DatabaseSync — no native addon required.
+ */
+async function createNodeSqliteAdapter(filename: string): Promise<DatabaseAdapter> {
+  const { DatabaseSync } = await import('node:sqlite')
+  const db = new DatabaseSync(filename)
+
+  return {
+    async query(sql: string, args?: SQLInputValue[]): Promise<QueryResult> {
+      const stmt = db.prepare(sql)
+      const rows = args ? stmt.all(...args) : stmt.all()
+      if (rows.length === 0) {
+        return { columns: [], rows: [] }
+      }
+      const columns = Object.keys(rows[0])
+      return {
+        columns,
+        rows: rows.map((row: Record<string, unknown>) => columns.map((c) => normalizeValue(row[c]))),
+      }
+    },
+    async exec(sql: string, args?: SQLInputValue[]): Promise<ExecResult> {
+      if (args && args.length > 0) {
+        const result = db.prepare(sql).run(...args)
+        return { rowsAffected: Number(result.changes) }
+      }
+      db.exec(sql)
+      return { rowsAffected: 0 }
+    },
+    async close(): Promise<void> {
+      db.close()
+    },
+  }
+}
+
+/**
+ * Create a SQLite adapter using bun:sqlite (Bun runtime).
+ * Uses dynamic import since bun:sqlite is only available in Bun.1`
+ */
+async function createBunSqliteAdapter(filename: string): Promise<DatabaseAdapter> {
+  // @ts-expect-error -- bun:sqlite only exists in the Bun runtime; guarded by isBun check
+  const { Database } = await import('bun:sqlite')
+  const db = new Database(filename)
+
+  return {
+    async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+      const stmt = db.query(sql)
+      const columns = stmt.columnNames
+      const rows = args ? stmt.values(...args) : stmt.values()
+      return {
+        columns,
+        rows: (rows as unknown[][]).map((row) => row.map(normalizeValue)),
+      }
+    },
+    async exec(sql: string, args?: unknown[]): Promise<ExecResult> {
+      if (args && args.length > 0) {
+        const stmt = db.query(sql)
+        const result = stmt.run(...args)
+        return { rowsAffected: result.changes ?? 0 }
+      }
+      db.exec(sql)
+      return { rowsAffected: 0 }
+    },
+    async close(): Promise<void> {
+      db.close()
+    },
+  }
+}
+
+/**
+ * Create a SQLite DatabaseAdapter with runtime detection.
+ * Detects whether running in Bun or Node and uses the appropriate driver:
+ * - Bun: uses built-in bun:sqlite (zero dependencies)
+ * - Node: uses node:sqlite (built-in, Node 22.5+)
+ */
+export async function createSqliteAdapter(filename: string): Promise<DatabaseAdapter> {
+  const isBun = typeof (globalThis as any).Bun !== 'undefined'
+
+  if (isBun) {
+    return createBunSqliteAdapter(filename)
+  }
+
+  return createNodeSqliteAdapter(filename)
+}

package/src/db/types.ts

@@ -0,0 +1,26 @@
+/**
+ * DatabaseAdapter abstracts the database connection used by the Atlas WASI host.
+ * Both pglite (in-memory, zero-config) and pg (external Postgres) implement this.
+ */
+export interface DatabaseAdapter {
+  query(sql: string, args?: unknown[]): Promise<QueryResult>
+  exec(sql: string, args?: unknown[]): Promise<ExecResult>
+  close(): Promise<void>
+}
+
+/**
+ * Result of a SELECT-style query.
+ * Matches the WASI protocol Response shape for "query" requests.
+ */
+export interface QueryResult {
+  columns: string[]
+  rows: unknown[][]
+}
+
+/**
+ * Result of a DDL/DML execution.
+ * Matches the WASI protocol Response shape for "exec" requests.
+ */
+export interface ExecResult {
+  rowsAffected: number
+}