@sqldoc/db 0.0.3

package/src/extensions.ts

@@ -0,0 +1,116 @@
+/**
+ * PostgreSQL extension detection and validation.
+ *
+ * Extracts CREATE EXTENSION names from SQL, validates against pglite
+ * or real Postgres, and provides helpful error messages.
+ */
+import { createRequire } from 'node:module'
+import pc from 'picocolors'
+
+/** Regex to extract extension names from CREATE EXTENSION statements */
+const CREATE_EXT_RE = /CREATE\s+EXTENSION\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|(\w[\w-]*))/gi
+
+/**
+ * Extract extension names from SQL strings.
+ * Handles both quoted and unquoted names, and hyphenated names like uuid-ossp.
+ */
+export function extractExtensions(
+  sqlFiles: string[],
+  filePaths?: string[],
+): { extensions: string[]; byFile: Map<string, string[]> } {
+  const all = new Set<string>()
+  const byFile = new Map<string, string[]>()
+  for (let i = 0; i < sqlFiles.length; i++) {
+    const sql = sqlFiles[i]
+    const file = filePaths?.[i] ?? `file${i}`
+    const lines = sql.split('\n')
+    for (const line of lines) {
+      // Skip commented-out lines
+      if (line.trimStart().startsWith('--')) continue
+      let match
+      CREATE_EXT_RE.lastIndex = 0
+      while ((match = CREATE_EXT_RE.exec(line)) !== null) {
+        const name = (match[1] ?? match[2]).toLowerCase().replace(/-/g, '_')
+        all.add(name)
+        const existing = byFile.get(name) ?? []
+        existing.push(file)
+        byFile.set(name, existing)
+      }
+    }
+  }
+  return { extensions: [...all], byFile }
+}
+
+/**
+ * Validate extensions for pglite by attempting to import them.
+ * Returns the list of extensions that are available.
+ * Throws with a pretty error if any are not available.
+ */
+export async function validatePgliteExtensions(requested: string[]): Promise<string[]> {
+  if (requested.length === 0) return []
+
+  // Resolve from this package's directory (pglite is a dep of @sqldoc/db)
+  const req = createRequire(import.meta.url)
+
+  const results: Array<{ name: string; available: boolean }> = []
+
+  for (const ext of requested) {
+    let found = false
+    try {
+      req.resolve(`@electric-sql/pglite/contrib/${ext}`)
+      found = true
+    } catch {}
+    if (!found)
+      try {
+        req.resolve(`@electric-sql/pglite/${ext}`)
+        found = true
+      } catch {}
+    results.push({ name: ext, available: found })
+  }
+
+  const unavailable = results.filter((r) => !r.available)
+  if (unavailable.length > 0) {
+    const lines = results.map((r) => (r.available ? pc.green(`  ✓ ${r.name}`) : pc.red(`  ✗ ${r.name}`)))
+
+    throw new Error(
+      `Some extensions are not available for the embedded postgres database:\n${lines.join('\n')}\n\n` +
+        `Use a Docker image with these extensions installed as devUrl:\n` +
+        `  ${pc.cyan('docker://<image>')}        — use an image that includes the extension\n` +
+        `  ${pc.cyan('dockerfile://path')}       — build a custom Dockerfile with the extension`,
+    )
+  }
+
+  return requested
+}
+
+/**
+ * Validate extensions against a real Postgres database.
+ * Queries pg_available_extensions to check availability.
+ */
+export async function validatePostgresExtensions(
+  requested: string[],
+  queryFn: (sql: string) => Promise<{ rows: unknown[][] }>,
+): Promise<void> {
+  if (requested.length === 0) return
+
+  const result = await queryFn(
+    'SELECT name FROM pg_available_extensions WHERE name = ANY(ARRAY[' +
+      requested.map((e) => `'${e}'`).join(',') +
+      '])',
+  )
+
+  const available = new Set(result.rows.map((r) => String(r[0])))
+
+  const missing = requested.filter((e) => !available.has(e))
+  if (missing.length > 0) {
+    const lines = requested.map((ext) => {
+      const ok = available.has(ext)
+      return ok ? pc.green(`  ✓ ${ext}`) : pc.red(`  ✗ ${ext}`)
+    })
+
+    throw new Error(
+      `Some required extensions are not available on this database:\n${lines.join('\n')}\n\n` +
+        `Install the missing extensions or use a Docker image that includes them.`,
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+// @sqldoc/db -- Atlas WASI integration for sqldoc
+// Schema types, database adapters, and WASI runner
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createMysqlAdapter } from './db/mysql.ts'
+import { createMysqlDockerAdapter } from './db/mysql-docker.ts'
+import { createPgliteAdapter } from './db/pglite.ts'
+import { createPostgresAdapter } from './db/postgres.ts'
+import { createPostgresDockerAdapter } from './db/postgres-docker.ts'
+import { createSqliteAdapter } from './db/sqlite.ts'
+import { validatePgliteExtensions, validatePostgresExtensions } from './extensions.ts'
+import { createAtlasRunner } from './runner.ts'
+
+export { createMysqlAdapter } from './db/mysql.ts'
+export { createMysqlDockerAdapter } from './db/mysql-docker.ts'
+export { createPgliteAdapter } from './db/pglite.ts'
+export { createPostgresAdapter } from './db/postgres.ts'
+export { createPostgresDockerAdapter } from './db/postgres-docker.ts'
+export { createSqliteAdapter } from './db/sqlite.ts'
+export type { DatabaseAdapter, ExecResult, QueryResult } from './db/types.ts'
+export { extractExtensions, validatePgliteExtensions, validatePostgresExtensions } from './extensions.ts'
+export type { AtlasRunner, AtlasRunnerOptions, DiffSource } from './runner.ts'
+export { createAtlasRunner } from './runner.ts'
+export * from './types.ts'
+
+export interface CreateRunnerConfig {
+  /** SQL dialect (required) */
+  dialect: 'postgres' | 'mysql' | 'sqlite'
+  /** Database connection URL. If omitted, uses dialect-specific default. */
+  devUrl?: string
+  /** Postgres extensions to load. Validated against the dev database; loaded automatically in PGlite. */
+  extensions?: string[]
+}
+
+/**
+ * Resolve the atlas.wasm binary.
+ * Binary mode: ATLAS_WASM_PATH env var set by binary entry point.
+ * Dev mode: walk up from current directory to find atlas.wasm.
+ */
+function resolveWasm(): string {
+  // Binary mode: WASM path set by binary entry point
+  if (process.env.ATLAS_WASM_PATH) {
+    return process.env.ATLAS_WASM_PATH
+  }
+
+  // Dev mode: walk up from current directory to find atlas.wasm
+  let dir = path.dirname(fileURLToPath(import.meta.url))
+  while (true) {
+    for (const candidate of [
+      path.join(dir, 'wasm', 'atlas.wasm'),
+      path.join(dir, '..', 'wasm', 'atlas.wasm'),
+      path.join(dir, 'node_modules', '@sqldoc', 'db', 'wasm', 'atlas.wasm'),
+      path.join(dir, 'packages', 'db', 'wasm', 'atlas.wasm'),
+    ]) {
+      if (fs.existsSync(candidate)) return candidate
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  throw new Error(
+    'atlas.wasm not found. Set ATLAS_WASM_PATH or build: cd atlas/cmd/atlas-wasi && GOOS=wasip1 GOARCH=wasm go build -o atlas.wasm .',
+  )
+}
+
+/** Return the default dev database URL for each dialect */
+function defaultDevUrl(dialect: 'postgres' | 'mysql' | 'sqlite'): string {
+  switch (dialect) {
+    case 'postgres':
+      return 'pglite'
+    case 'sqlite':
+      return ':memory:'
+    case 'mysql':
+      return 'docker://mysql:8'
+  }
+}
+
+/**
+ * Create an Atlas runner with sensible defaults.
+ * Resolves the wasm binary, detects extensions from SQL files,
+ * validates them, and creates the appropriate DB adapter.
+ */
+export async function createRunner(config: CreateRunnerConfig): Promise<import('./runner').AtlasRunner> {
+  const wasmPath = resolveWasm()
+  const dialect = config.dialect
+  const devUrl = config.devUrl ?? defaultDevUrl(dialect)
+
+  const extensions = dialect === 'postgres' ? (config.extensions ?? []) : []
+
+  let db: import('./db/types').DatabaseAdapter
+
+  if (dialect === 'sqlite') {
+    db = await createSqliteAdapter(devUrl)
+  } else if (dialect === 'mysql') {
+    if (devUrl.startsWith('docker://')) {
+      db = await createMysqlDockerAdapter(devUrl)
+    } else {
+      db = await createMysqlAdapter(devUrl)
+    }
+  } else {
+    // postgres (existing logic preserved exactly)
+    if (devUrl.startsWith('docker://') || devUrl.startsWith('dockerfile://')) {
+      db = await createPostgresDockerAdapter(devUrl)
+      if (extensions.length > 0) {
+        await validatePostgresExtensions(extensions, (sql) => db.query(sql))
+      }
+    } else if (devUrl.startsWith('postgres://') || devUrl.startsWith('postgresql://')) {
+      db = await createPostgresAdapter(devUrl)
+      if (extensions.length > 0) {
+        await validatePostgresExtensions(extensions, (sql) => db.query(sql))
+      }
+    } else {
+      // pglite (in-memory embedded postgres)
+      const validExtensions = extensions.length > 0 ? await validatePgliteExtensions(extensions) : []
+      db = await createPgliteAdapter(validExtensions.length > 0 ? validExtensions : undefined)
+    }
+  }
+
+  return createAtlasRunner({ wasmPath, db, dialect })
+}

package/src/runner.ts

@@ -0,0 +1,284 @@
+/**
+ * High-level Atlas runner API.
+ *
+ * Provides inspect() and diff() functions that:
+ * 1. Spawn a worker thread running the Atlas WASI module
+ * 2. Handle the SharedArrayBuffer bridge loop on the main thread
+ * 3. Execute SQL requests from the WASI module via the DatabaseAdapter
+ * 4. Return parsed AtlasResult
+ *
+ * The compiled WebAssembly.Module is cached across commands.
+ */
+
+import * as fs from 'node:fs'
+import { createRequire } from 'node:module'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Worker } from 'node:worker_threads'
+import {
+  type BridgeBuffers,
+  bridgeReadRequest,
+  bridgeRespond,
+  bridgeWaitForSignal,
+  createBridgeBuffers,
+  SIGNAL_DONE,
+  SIGNAL_REQUEST,
+} from './bridge.ts'
+import type { DatabaseAdapter } from './db/types.ts'
+import type { AtlasCommand, AtlasRename, AtlasResult } from './types.ts'
+
+export interface AtlasRunnerOptions {
+  /** Path to atlas.wasm binary */
+  wasmPath: string
+  /** Database adapter (pglite or pg) */
+  db: DatabaseAdapter
+  /** SQL dialect */
+  dialect: 'postgres' | 'mysql' | 'sqlite'
+}
+
+/** A diff source: SQL file contents (string[]) or a live database (DatabaseAdapter). */
+export type DiffSource = string[] | DatabaseAdapter
+
+export interface AtlasRunner {
+  /** Execute SQL files and return parsed schema with tags */
+  inspect(files: string[], options?: { schema?: string; fileNames?: string[] }): Promise<AtlasResult>
+
+  /** Compare two schema states. Each side can be SQL or a live database.
+   * Live databases are only inspected, never written to. */
+  diff(from: DiffSource, to: DiffSource, options?: { schema?: string; renames?: AtlasRename[] }): Promise<AtlasResult>
+
+  /** Clean up resources */
+  close(): Promise<void>
+}
+
+/**
+ * Resolve the path to the worker file (.js or .ts).
+ *
+ * Prefers compiled .js (production / Bun binary). Falls back to raw .ts
+ * for workspace development (vitest, tsx, Node --experimental-strip-types).
+ */
+function resolveWorkerPath(): { workerPath: string; execArgv: string[] } {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url))
+  const candidates = [
+    path.resolve(thisDir, 'worker.js'), // dist/worker.js (production)
+    path.resolve(thisDir, '../dist/worker.js'), // src/../dist/worker.js (legacy)
+    path.resolve(thisDir, 'worker.ts'), // src/worker.ts (raw .ts dev)
+  ]
+
+  const isBun = typeof (globalThis as any).Bun !== 'undefined'
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      if (candidate.endsWith('.ts') && !isBun) {
+        // Node 22.21+ runs .ts natively — no loader needed for workers
+        // Older Node needs tsx/cjs to register TypeScript transform
+        const [major, minor] = (process.versions?.node ?? '0.0').split('.').map(Number)
+        if (major > 22 || (major === 22 && minor >= 21)) {
+          return { workerPath: candidate, execArgv: [] }
+        }
+        const atlasRequire = createRequire(candidate)
+        const tsxCjs = atlasRequire.resolve('tsx/cjs')
+        return { workerPath: candidate, execArgv: ['--require', tsxCjs] }
+      }
+      return { workerPath: candidate, execArgv: [] }
+    }
+  }
+
+  throw new Error(`Cannot find worker file.\nLooked in:\n${candidates.map((c) => `  ${c}`).join('\n')}`)
+}
+
+/**
+ * Run a single Atlas command via a worker thread.
+ *
+ * Main thread bridge loop:
+ * 1. Wait for worker to signal a request via Atomics
+ * 2. Read SQL from shared buffer
+ * 3. Execute via DatabaseAdapter
+ * 4. Write response to shared buffer
+ * 5. Repeat until DONE signal
+ */
+async function runCommand(
+  wasmPath: string,
+  db: DatabaseAdapter,
+  command: AtlasCommand,
+  extraAdapters?: Record<string, DatabaseAdapter>,
+): Promise<AtlasResult> {
+  const buffers = createBridgeBuffers()
+  const stdinData = JSON.stringify(command)
+  const { workerPath, execArgv } = resolveWorkerPath()
+
+  return new Promise<AtlasResult>((resolve, reject) => {
+    const worker = new Worker(workerPath, {
+      workerData: {
+        wasmPath,
+        controlBuffer: buffers.control,
+        dataBuffer: buffers.data,
+        stdinData,
+      },
+      execArgv,
+    })
+
+    let settled = false
+
+    worker.on('message', (msg: { type: string; stdout?: string; error?: string }) => {
+      if (settled) return
+      settled = true
+
+      if (msg.type === 'error') {
+        reject(new Error(`Atlas worker error: ${msg.error}`))
+      } else if (msg.type === 'result') {
+        try {
+          const stdout = (msg.stdout ?? '').trim()
+          if (!stdout) {
+            resolve({})
+          } else {
+            resolve(JSON.parse(stdout))
+          }
+        } catch (_err: unknown) {
+          reject(new Error(`Failed to parse Atlas output: ${msg.stdout}`))
+        }
+      }
+    })
+
+    worker.on('error', (err) => {
+      if (settled) return
+      settled = true
+      reject(err)
+    })
+
+    worker.on('exit', (code) => {
+      if (settled) return
+      settled = true
+      if (code !== 0) {
+        reject(new Error(`Atlas worker exited with code ${code}`))
+      }
+    })
+
+    // Start the bridge loop (runs on main thread, async)
+    handleBridgeLoop(buffers, db, extraAdapters).catch((err) => {
+      if (!settled) {
+        settled = true
+        worker.terminate()
+        reject(err)
+      }
+    })
+  })
+}
+
+/**
+ * Main-thread bridge loop: handles atlas_sql requests from the worker.
+ * Runs until the worker signals DONE.
+ */
+async function handleBridgeLoop(
+  buffers: BridgeBuffers,
+  db: DatabaseAdapter,
+  extraAdapters?: Record<string, DatabaseAdapter>,
+): Promise<void> {
+  while (true) {
+    const signal = await bridgeWaitForSignal(buffers)
+
+    if (signal === SIGNAL_DONE) {
+      break
+    }
+
+    if (signal !== SIGNAL_REQUEST) {
+      // Unexpected signal -- wait again
+      // Reset to idle so bridgeWaitForSignal can poll again
+      const _control = new Int32Array(buffers.control)
+      // If it's RESPONSE, the worker hasn't reset yet. Wait briefly.
+      await new Promise((r) => setTimeout(r, 1))
+      continue
+    }
+
+    // Read SQL request from shared buffer
+    const reqJson = bridgeReadRequest(buffers)
+
+    let response: Record<string, unknown>
+    try {
+      const req = JSON.parse(reqJson) as { type: string; sql: string; args?: unknown[]; connection?: string }
+
+      // Route to the right adapter based on connection field
+      const adapter =
+        req.connection && req.connection !== 'dev' && extraAdapters?.[req.connection]
+          ? extraAdapters[req.connection]
+          : db
+
+      if (req.type === 'query') {
+        const result = await adapter.query(req.sql, req.args)
+        response = { columns: result.columns, rows: result.rows }
+      } else {
+        const result = await adapter.exec(req.sql, req.args)
+        response = { rows_affected: result.rowsAffected }
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err)
+      response = { error: message }
+    }
+
+    // Write response and notify worker (handle BigInt from pglite)
+    bridgeRespond(
+      buffers,
+      JSON.stringify(response, (_k, v) => (typeof v === 'bigint' ? v.toString() : v)),
+    )
+
+    // After responding, the worker will reset signal to IDLE.
+    // We need to wait for it to do so before calling bridgeWaitForSignal again.
+    // Small yield to allow worker to process.
+    await new Promise((r) => setTimeout(r, 0))
+  }
+}
+
+/**
+ * Create an AtlasRunner instance.
+ *
+ * The runner caches the compiled WebAssembly.Module (compiles atlas.wasm once).
+ * Each inspect/diff call spawns a worker thread that reuses the cached module.
+ */
+export async function createAtlasRunner(options: AtlasRunnerOptions): Promise<AtlasRunner> {
+  const { wasmPath, db, dialect } = options
+
+  // Verify wasm file exists
+  if (!fs.existsSync(wasmPath)) {
+    throw new Error(`Atlas WASM binary not found: ${wasmPath}`)
+  }
+
+  return {
+    async inspect(files: string[], opts?: { schema?: string; fileNames?: string[] }): Promise<AtlasResult> {
+      const command: AtlasCommand = {
+        type: 'inspect',
+        dialect,
+        files,
+        fileNames: opts?.fileNames,
+        schema: opts?.schema,
+      }
+      return runCommand(wasmPath, db, command)
+    },
+
+    async diff(
+      from: DiffSource,
+      to: DiffSource,
+      opts?: { schema?: string; renames?: AtlasRename[] },
+    ): Promise<AtlasResult> {
+      const fromIsDb = !Array.isArray(from)
+      const toIsDb = !Array.isArray(to)
+      const command: AtlasCommand = {
+        type: 'diff',
+        dialect,
+        from: fromIsDb ? [] : from,
+        to: toIsDb ? [] : to,
+        schema: opts?.schema,
+        renames: opts?.renames,
+        fromConnection: fromIsDb ? 'from' : undefined,
+        toConnection: toIsDb ? 'to' : undefined,
+      }
+      const extraAdapters: Record<string, DatabaseAdapter> = {}
+      if (fromIsDb) extraAdapters.from = from as DatabaseAdapter
+      if (toIsDb) extraAdapters.to = to as DatabaseAdapter
+      return runCommand(wasmPath, db, command, extraAdapters)
+    },
+
+    async close(): Promise<void> {
+      await db.close()
+    },
+  }
+}