@sqldoc/db-neon-temporary 0.0.10

package/package.json

@@ -0,0 +1,26 @@
+{
+  "type": "module",
+  "name": "@sqldoc/db-neon-temporary",
+  "version": "0.0.10",
+  "description": "Neon ephemeral database adapter for sqldoc (creates temporary databases via neon-new)",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "package.json"
+  ],
+  "dependencies": {
+    "@neondatabase/serverless": "^1.0.0"
+  },
+  "devDependencies": {
+    "@sqldoc/db": "0.0.10",
+    "@sqldoc/test-utils": "0.0.1"
+  }
+}

package/src/__tests__/neon-temporary.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Integration test for @sqldoc/db-neon-temporary.
+ *
+ * Creates a real ephemeral Neon database via the Neon API.
+ * Only runs when TEST_NEON=true is set.
+ *
+ * Example: TEST_NEON=true bun test packages/db-neon-temporary/ --timeout 120000
+ */
+import { describe, expect, it } from '@sqldoc/test-utils'
+import plugin from '../index.ts'
+
+describe('neon-temporary adapter', () => {
+  if (process.env.TEST_NEON !== 'true') {
+    it('skipped: set TEST_NEON=true to run', () => {})
+    return
+  }
+
+  plugin.lockTimeoutMs = 5000
+
+  it('creates database, wipes schema, provides clean slate', async () => {
+    const adapter = await plugin.createAdapter('neon-temporary', { dialect: 'postgres', extensions: [] })
+    try {
+      // Schema should be empty after wipe
+      const result = await adapter.query(
+        "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'",
+      )
+      expect(result.rows).toHaveLength(0)
+
+      // Can create tables
+      await adapter.exec('CREATE TABLE test_neon (id serial PRIMARY KEY, name text)')
+      const tables = await adapter.query(
+        "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'",
+      )
+      expect(tables.rows).toHaveLength(1)
+    } finally {
+      await adapter.close()
+    }
+  })
+
+  it('reuses cached database on second call', async () => {
+    plugin.forceReuse = true
+    try {
+      const adapter = await plugin.createAdapter('neon-temporary', { dialect: 'postgres', extensions: [] })
+      try {
+        // Should connect without creating a new DB (reuses cache from previous test)
+        const result = await adapter.query('SELECT 1 as ok')
+        expect(result.rows[0][0]).toBe(1)
+      } finally {
+        await adapter.close()
+      }
+    } finally {
+      plugin.forceReuse = false
+    }
+  })
+
+  it('releases lock on close, allows next connection', async () => {
+    const adapter = await plugin.createAdapter('neon-temporary', { dialect: 'postgres', extensions: [] })
+    await adapter.close()
+
+    // Should be able to reconnect immediately (lock released)
+    const adapter2 = await plugin.createAdapter('neon-temporary', { dialect: 'postgres', extensions: [] })
+    try {
+      const result = await adapter2.query('SELECT 1 as ok')
+      expect(result.rows[0][0]).toBe(1)
+    } finally {
+      await adapter2.close()
+    }
+  })
+})

package/src/index.ts

@@ -0,0 +1,235 @@
+/**
+ * Neon ephemeral database adapter for sqldoc.
+ *
+ * Creates a temporary Neon database on first use, caches the connection
+ * URL in .sqldoc/neon-temporary.json, and reuses it for 72 hours.
+ *
+ * Uses @neondatabase/serverless for the connection (WebSocket transport,
+ * works in Node, Bun, and edge environments).
+ *
+ * On each run:
+ * 1. Load or create the database (cached for 72h)
+ * 2. Acquire advisory lock (blocks if another sqldoc process is using it)
+ * 3. Wipe all schemas (clean slate)
+ * 4. Release lock on close
+ *
+ * devUrl: just 'neon-temporary' (no URL needed)
+ */
+import { randomUUID } from 'node:crypto'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { Client } from '@neondatabase/serverless'
+import type { AdapterPluginContext, DatabaseAdapter, DatabaseAdapterPlugin, ExecResult, QueryResult } from '@sqldoc/db'
+import { normalizeValue } from '@sqldoc/db'
+
+const log = (msg: string) => console.error(`[neon-temporary] ${msg}`)
+
+/** Advisory lock key — "SqLD" in hex */
+const LOCK_KEY = 0x5371_4c44
+
+const NEON_API = 'https://neon.new/api/v1/database'
+const NEON_CLAIM = 'https://neon.new/database'
+const REFERRER = 'npm:neon-new|https://sqldoc.dev'
+const CACHE_FILE = 'neon-temporary.json'
+const MAX_AGE_MS = 72 * 60 * 60 * 1000
+
+interface CachedDb {
+  directUrl: string
+  poolerUrl: string
+  claimUrl: string
+  createdAt: string
+}
+
+// ── Cache ──────────────────────────────────────────────────────────
+
+function getCachePath(): string | null {
+  let dir = process.cwd()
+  while (true) {
+    const candidate = path.join(dir, '.sqldoc')
+    if (fs.existsSync(candidate)) return path.join(candidate, CACHE_FILE)
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function loadCache(): CachedDb | null {
+  const cachePath = getCachePath()
+  if (!cachePath || !fs.existsSync(cachePath)) return null
+  try {
+    const raw = JSON.parse(fs.readFileSync(cachePath, 'utf-8'))
+    if (
+      typeof raw?.directUrl !== 'string' ||
+      typeof raw?.poolerUrl !== 'string' ||
+      typeof raw?.claimUrl !== 'string' ||
+      typeof raw?.createdAt !== 'string'
+    ) {
+      log('cache invalid: missing required fields')
+      return null
+    }
+    const data: CachedDb = raw
+    const createdAtMs = new Date(data.createdAt).getTime()
+    if (Number.isNaN(createdAtMs)) {
+      log('cache invalid: bad createdAt timestamp')
+      return null
+    }
+    const age = Date.now() - createdAtMs
+    if (age > MAX_AGE_MS) {
+      log(`cache expired (${Math.round(age / 3600000)}h old)`)
+      return null
+    }
+    log(`reusing cached database (${Math.round(age / 60000)}m old)`)
+    return data
+  } catch {
+    return null
+  }
+}
+
+function saveCache(data: CachedDb): void {
+  const cachePath = getCachePath()
+  if (!cachePath) return
+  fs.writeFileSync(cachePath, `${JSON.stringify(data, null, 2)}\n`)
+  log(`cached to ${cachePath}`)
+}
+
+// ── Neon API ───────────────────────────────────────────────────────
+
+function toPooler(connString: string): string {
+  const url = new URL(connString)
+  if (url.hostname.includes('pooler')) return connString
+  const [first, ...rest] = url.hostname.split('.')
+  url.hostname = [`${first}-pooler`, ...rest].join('.')
+  return url.href
+}
+
+function toDirect(connString: string): string {
+  const url = new URL(connString)
+  if (!url.hostname.includes('pooler')) return connString
+  const [first, ...rest] = url.hostname.split('.')
+  url.hostname = [first.replace('-pooler', ''), ...rest].join('.')
+  return url.href
+}
+
+async function createNeonDatabase(): Promise<CachedDb> {
+  log('creating new Neon database...')
+
+  const dbId = randomUUID()
+  const createUrl = `${NEON_API}/${dbId}?referrer=${encodeURIComponent(REFERRER)}`
+
+  log(`POST ${createUrl}`)
+  const createRes = await fetch(createUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ enable_logical_replication: false }),
+  })
+  if (!createRes.ok) {
+    throw new Error(`Failed to create Neon database: ${createRes.status} ${createRes.statusText}`)
+  }
+
+  log(`GET ${NEON_API}/${dbId}`)
+  const dataRes = await fetch(`${NEON_API}/${dbId}`, {
+    headers: { 'Content-Type': 'application/json' },
+  })
+  if (!dataRes.ok) {
+    throw new Error(`Failed to fetch Neon database info: ${dataRes.status} ${dataRes.statusText}`)
+  }
+  const payload = (await dataRes.json()) as { connection_string?: string }
+  if (!payload.connection_string) {
+    throw new Error('Neon API response missing connection_string')
+  }
+  const { connection_string } = payload
+
+  const claimUrl = `${NEON_CLAIM}/${dbId}`
+  log(`database created, claim: ${claimUrl}`)
+
+  const data: CachedDb = {
+    directUrl: toDirect(connection_string),
+    poolerUrl: toPooler(connection_string),
+    claimUrl,
+    createdAt: new Date().toISOString(),
+  }
+  saveCache(data)
+  return data
+}
+
+async function getOrCreateDatabase(forceReuse: boolean): Promise<CachedDb> {
+  const cached = loadCache()
+  if (cached) return cached
+  if (forceReuse) throw new Error('neon-temporary: no cached database found (forceReuse=true)')
+  return createNeonDatabase()
+}
+
+// ── Plugin ─────────────────────────────────────────────────────────
+
+const plugin: DatabaseAdapterPlugin & { forceReuse: boolean; lockTimeoutMs: number } = {
+  apiVersion: 1,
+  name: 'neon-temporary',
+  schemes: ['neon-temporary'],
+  dialects: ['postgres'],
+  runtime: 'any',
+
+  /** Set to true for testing — throws instead of creating a new database */
+  forceReuse: false,
+
+  /** How long to wait for the advisory lock (ms). Default 60s. */
+  lockTimeoutMs: 60_000,
+
+  async createAdapter(_devUrl: string, _context: AdapterPluginContext): Promise<DatabaseAdapter> {
+    const { directUrl } = await getOrCreateDatabase(plugin.forceReuse)
+
+    const maskedUrl = new URL(directUrl)
+    maskedUrl.password = '***'
+    log(`connecting to ${maskedUrl.href}`)
+    const client = new Client(directUrl)
+    await client.connect()
+
+    const adapter: DatabaseAdapter = {
+      async query(sql: string, args?: unknown[]): Promise<QueryResult> {
+        const result = await client.query({ text: sql, values: args, rowMode: 'array' })
+        return {
+          columns: result.fields.map((f) => f.name),
+          rows: (result.rows as unknown[][]).map((row) => row.map((v) => normalizeValue(v))),
+        }
+      },
+      async exec(sql: string): Promise<ExecResult> {
+        const result = await client.query(sql)
+        return { rowsAffected: result.rowCount ?? 0 }
+      },
+      async close(): Promise<void> {
+        log('releasing lock...')
+        try {
+          await client.query(`SELECT pg_advisory_unlock(${LOCK_KEY})`)
+        } catch {
+          // Connection may already be closed — lock releases with session
+        }
+        await client.end()
+        log('closed')
+      },
+    }
+
+    try {
+      log('acquiring advisory lock...')
+      await adapter.exec(`SET lock_timeout = '${plugin.lockTimeoutMs}ms'`)
+      await adapter.exec(`SELECT pg_advisory_lock(${LOCK_KEY})`)
+      log('lock acquired, wiping schemas...')
+
+      // Drop ALL user schemas — previous runs may have created extras (e.g. kitchen-sink creates a, b, c, d)
+      const schemas = await adapter.query(
+        "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('information_schema', 'pg_catalog', 'pg_toast')",
+      )
+      for (const row of schemas.rows) {
+        const name = (row[0] as string).replace(/"/g, '""')
+        await adapter.exec(`DROP SCHEMA "${name}" CASCADE`)
+      }
+      await adapter.exec('CREATE SCHEMA public')
+      log('ready')
+    } catch (err) {
+      await adapter.close()
+      throw err
+    }
+
+    return adapter
+  },
+}
+
+export default plugin