@dotdo/postgres 0.1.2 → 0.1.3

package/src/do/postgres.ts

@@ -0,0 +1,367 @@
+/**
+ * Postgres Durable Object
+ *
+ * A PostgreSQL database running in a Cloudflare Durable Object with:
+ * - DO SQLite for durable persistence (survives evictions)
+ * - PGLite for full PostgreSQL features (arrays, JSON, window functions, etc.)
+ * - Automatic sync between the two layers
+ *
+ * @example
+ * ```typescript
+ * import { sql, Postgres } from '@dotdo/postgres'
+ * export { Postgres }
+ *
+ * export default {
+ *   fetch: () => Response.json(await sql`SELECT * FROM posts`)
+ * }
+ * ```
+ */
+
+import { PGlite } from '@dotdo/pglite'
+
+// Types for DO SQLite (Cloudflare's built-in SQL storage)
+interface SqlStorage {
+  exec(query: string, ...bindings: unknown[]): SqlStorageCursor
+}
+
+interface SqlStorageCursor {
+  [Symbol.iterator](): Iterator<Record<string, SqlStorageValue>>
+  toArray(): Record<string, SqlStorageValue>[]
+  one(): Record<string, SqlStorageValue> | null
+  raw<T>(): T[][]
+  columnNames: string[]
+  rowsRead: number
+  rowsWritten: number
+}
+
+type SqlStorageValue = string | number | null | ArrayBuffer
+
+interface DurableObjectState {
+  storage: {
+    sql: SqlStorage
+    get<T>(key: string): Promise<T | undefined>
+    put<T>(key: string, value: T): Promise<void>
+    delete(key: string): Promise<boolean>
+  }
+  waitUntil(promise: Promise<unknown>): void
+  id: { toString(): string }
+}
+
+export interface PostgresEnv {
+  [key: string]: unknown
+}
+
+export interface QueryResult<T = Record<string, unknown>> {
+  rows: T[]
+  rowCount: number
+  fields?: { name: string; dataTypeID: number }[]
+}
+
+
+/**
+ * Postgres Durable Object
+ *
+ * Provides a full PostgreSQL database in each Durable Object instance.
+ * Data persists in DO SQLite and is loaded into PGLite on initialization.
+ */
+export class Postgres implements DurableObject {
+  private pglite: PGlite | null = null
+  private initPromise: Promise<void> | null = null
+  private initialized = false
+  private sql: SqlStorage
+
+  constructor(
+    private state: DurableObjectState,
+    _env: PostgresEnv
+  ) {
+    this.sql = state.storage.sql
+    this.initStorage()
+  }
+
+  /**
+   * Initialize DO SQLite schema for persistence
+   */
+  private initStorage(): void {
+    // Core metadata table
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS __pg_metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at TEXT DEFAULT (datetime('now'))
+      )
+    `)
+
+    // Table registry - tracks all tables and their schemas
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS __pg_tables (
+        name TEXT PRIMARY KEY,
+        schema TEXT NOT NULL,
+        created_at TEXT DEFAULT (datetime('now'))
+      )
+    `)
+
+    // Generic data storage - stores all table data as JSON
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS __pg_data (
+        table_name TEXT NOT NULL,
+        row_id TEXT NOT NULL,
+        data TEXT NOT NULL,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now')),
+        PRIMARY KEY (table_name, row_id)
+      )
+    `)
+
+    // Create index for faster queries
+    this.sql.exec(`
+      CREATE INDEX IF NOT EXISTS idx_pg_data_table ON __pg_data(table_name)
+    `)
+  }
+
+  /**
+   * Initialize PGLite and restore data from DO SQLite
+   */
+  private async init(): Promise<void> {
+    if (this.initialized && this.pglite) {
+      return
+    }
+
+    if (this.initPromise) {
+      return this.initPromise
+    }
+
+    this.initPromise = (async () => {
+      // Initialize PGLite (in-memory PostgreSQL)
+      this.pglite = new PGlite()
+      await this.pglite.waitReady
+
+      // Restore tables and data from DO SQLite
+      await this.restoreFromStorage()
+
+      this.initialized = true
+    })()
+
+    return this.initPromise
+  }
+
+  /**
+   * Restore all tables and data from DO SQLite into PGLite
+   */
+  private async restoreFromStorage(): Promise<void> {
+    if (!this.pglite) return
+
+    // Get all registered tables
+    const tables = [...this.sql.exec('SELECT name, schema FROM __pg_tables')]
+
+    for (const table of tables) {
+      const tableName = table.name as string
+      const schema = table.schema as string
+
+      // Create table in PGLite
+      try {
+        await this.pglite.exec(schema)
+      } catch (e) {
+        // Table might already exist, ignore
+      }
+
+      // Restore data for this table
+      const rows = [...this.sql.exec(
+        'SELECT row_id, data FROM __pg_data WHERE table_name = ?',
+        tableName
+      )]
+
+      for (const row of rows) {
+        const data = JSON.parse(row.data as string)
+        const columns = Object.keys(data)
+        const values = columns.map(c => data[c])
+        const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ')
+
+        try {
+          await this.pglite.query(
+            `INSERT INTO ${tableName} (${columns.join(', ')}) VALUES (${placeholders}) ON CONFLICT DO NOTHING`,
+            values
+          )
+        } catch (e) {
+          // Row might already exist or schema mismatch, continue
+        }
+      }
+    }
+  }
+
+  /**
+   * Register a table schema for persistence
+   */
+  private registerTable(tableName: string, createStatement: string): void {
+    this.sql.exec(
+      'INSERT OR REPLACE INTO __pg_tables (name, schema) VALUES (?, ?)',
+      tableName,
+      createStatement
+    )
+  }
+
+  /**
+   * Persist a row to DO SQLite
+   */
+  private persistRow(tableName: string, rowId: string, data: Record<string, unknown>): void {
+    this.sql.exec(
+      `INSERT OR REPLACE INTO __pg_data (table_name, row_id, data, updated_at)
+       VALUES (?, ?, ?, datetime('now'))`,
+      tableName,
+      rowId,
+      JSON.stringify(data)
+    )
+  }
+
+  /**
+   * Delete a row from DO SQLite
+   */
+  private deleteRowFromStorage(tableName: string, rowId: string): void {
+    this.sql.exec(
+      'DELETE FROM __pg_data WHERE table_name = ? AND row_id = ?',
+      tableName,
+      rowId
+    )
+  }
+
+  /**
+   * Delete all rows from a table in DO SQLite
+   */
+  private deleteAllRowsFromStorage(tableName: string): void {
+    this.sql.exec(
+      'DELETE FROM __pg_data WHERE table_name = ?',
+      tableName
+    )
+  }
+
+  /**
+   * Execute a SQL query
+   */
+  async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>> {
+    await this.init()
+
+    if (!this.pglite) {
+      throw new Error('PGLite not initialized')
+    }
+
+    // Detect and handle DDL statements
+    const upperSql = sql.trim().toUpperCase()
+
+    if (upperSql.startsWith('CREATE TABLE')) {
+      // Extract table name and register for persistence
+      const match = sql.match(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i)
+      if (match) {
+        this.registerTable(match[1], sql)
+      }
+    }
+
+    // Execute on PGLite
+    const result = await this.pglite.query<T>(sql, params)
+
+    // Handle INSERT/UPDATE/DELETE - persist changes
+    if (upperSql.startsWith('INSERT') || upperSql.startsWith('UPDATE') || upperSql.startsWith('DELETE')) {
+      // Extract table name
+      let tableName: string | null = null
+
+      if (upperSql.startsWith('INSERT')) {
+        const match = sql.match(/INSERT\s+INTO\s+["']?(\w+)["']?/i)
+        tableName = match?.[1] || null
+      } else if (upperSql.startsWith('UPDATE')) {
+        const match = sql.match(/UPDATE\s+["']?(\w+)["']?/i)
+        tableName = match?.[1] || null
+      } else if (upperSql.startsWith('DELETE')) {
+        const match = sql.match(/DELETE\s+FROM\s+["']?(\w+)["']?/i)
+        tableName = match?.[1] || null
+      }
+
+      // For RETURNING clauses, persist the returned rows (INSERT/UPDATE)
+      if (tableName && (upperSql.startsWith('INSERT') || upperSql.startsWith('UPDATE'))) {
+        if (result.rows && result.rows.length > 0) {
+          for (const row of result.rows as Record<string, unknown>[]) {
+            const rowId = (row.id as string) || (row._id as string) || JSON.stringify(row)
+            this.persistRow(tableName, rowId, row)
+          }
+        }
+      }
+
+      // For DELETE with RETURNING, remove the deleted rows
+      if (tableName && upperSql.startsWith('DELETE')) {
+        if (result.rows && result.rows.length > 0) {
+          for (const row of result.rows as Record<string, unknown>[]) {
+            const rowId = (row.id as string) || (row._id as string) || JSON.stringify(row)
+            this.deleteRowFromStorage(tableName, rowId)
+          }
+        } else {
+          // DELETE without RETURNING - sync entire table
+          // This is expensive but ensures consistency
+          this.deleteAllRowsFromStorage(tableName)
+          // Re-persist all remaining rows
+          const allRows = await this.pglite!.query(`SELECT * FROM ${tableName}`)
+          for (const row of allRows.rows as Record<string, unknown>[]) {
+            const rowId = (row.id as string) || (row._id as string) || JSON.stringify(row)
+            this.persistRow(tableName, rowId, row)
+          }
+        }
+      }
+    }
+
+    return {
+      rows: result.rows as T[],
+      rowCount: result.rows?.length || 0,
+      fields: result.fields?.map(f => ({ name: f.name, dataTypeID: f.dataTypeID })),
+    }
+  }
+
+  /**
+   * Execute SQL without returning results
+   */
+  async exec(sql: string): Promise<void> {
+    await this.query(sql)
+  }
+
+  /**
+   * Handle HTTP requests to the Durable Object
+   */
+  async fetch(request: Request): Promise<Response> {
+    try {
+      await this.init()
+
+      const url = new URL(request.url)
+
+      // POST /query - Execute SQL
+      if (url.pathname === '/query' && request.method === 'POST') {
+        const body = await request.json() as { sql: string; params?: unknown[] }
+
+        if (!body.sql) {
+          return Response.json({ error: 'Missing sql' }, { status: 400 })
+        }
+
+        const result = await this.query(body.sql, body.params)
+        return Response.json(result)
+      }
+
+      // GET /health - Health check
+      if (url.pathname === '/health') {
+        return Response.json({
+          ok: true,
+          initialized: this.initialized,
+          id: this.state.id.toString(),
+        })
+      }
+
+      // GET /tables - List tables
+      if (url.pathname === '/tables') {
+        const tables = [...this.sql.exec('SELECT name FROM __pg_tables')]
+        return Response.json({ tables: tables.map(t => t.name) })
+      }
+
+      return Response.json({ error: 'Not found' }, { status: 404 })
+    } catch (error) {
+      return Response.json(
+        { error: error instanceof Error ? error.message : 'Unknown error' },
+        { status: 500 }
+      )
+    }
+  }
+}
+
+export default Postgres

package/src/do/sql.ts

@@ -0,0 +1,280 @@
+/**
+ * SQL Tagged Template & Database Client
+ *
+ * Execute PostgreSQL queries with a simple API.
+ * Automatically routes to the Postgres Durable Object using cloudflare:workers env.
+ *
+ * @example
+ * ```typescript
+ * import { sql, db } from '@dotdo/postgres'
+ *
+ * // Tagged template (safe from SQL injection)
+ * const posts = await sql`SELECT * FROM posts WHERE id = ${id}`
+ *
+ * // db.query for dynamic queries
+ * const result = await db.query('SELECT * FROM posts')
+ * ```
+ */
+
+export interface SqlConfig {
+  /** DO binding name (default: 'POSTGRES') */
+  binding?: string
+  /** DO instance name (default: 'default') */
+  instance?: string
+}
+
+export interface SqlResult<T = Record<string, unknown>> {
+  rows: T[]
+  rowCount: number
+  fields?: { name: string; dataTypeID: number }[]
+}
+
+type PostgresNamespace = {
+  idFromName(name: string): { toString(): string }
+  get(id: { toString(): string }): {
+    fetch(request: Request): Promise<Response>
+  }
+}
+
+type DOStub = {
+  fetch(request: Request): Promise<Response>
+}
+
+/**
+ * Build a parameterized SQL query from template literals
+ */
+function buildQuery(strings: TemplateStringsArray, values: unknown[]): { sql: string; params: unknown[] } {
+  let sql = ''
+  const params: unknown[] = []
+
+  for (let i = 0; i < strings.length; i++) {
+    sql += strings[i]
+    if (i < values.length) {
+      params.push(values[i])
+      sql += `$${params.length}`
+    }
+  }
+
+  return { sql, params }
+}
+
+// Cached env and stub
+let cachedEnv: Record<string, unknown> | null = null
+let cachedStub: DOStub | null = null
+
+async function getStub(config: SqlConfig = {}): Promise<DOStub> {
+  if (cachedStub) return cachedStub
+
+  if (!cachedEnv) {
+    try {
+      const mod = await import('cloudflare:workers')
+      cachedEnv = mod.env as Record<string, unknown>
+    } catch {
+      throw new Error(
+        'Could not import cloudflare:workers. ' +
+        'Ensure you are running in Cloudflare Workers with nodejs_compat.'
+      )
+    }
+  }
+
+  const binding = config.binding || 'POSTGRES'
+  const instance = config.instance || 'default'
+
+  const namespace = cachedEnv[binding] as PostgresNamespace | undefined
+  if (!namespace) {
+    throw new Error(`Postgres binding "${binding}" not found. Add it to wrangler.toml.`)
+  }
+
+  cachedStub = namespace.get(namespace.idFromName(instance))
+  return cachedStub
+}
+
+async function executeQuery<T>(sql: string, params?: unknown[]): Promise<SqlResult<T>> {
+  const stub = await getStub()
+
+  const response = await stub.fetch(new Request('http://do/query', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql, params }),
+  }))
+
+  if (!response.ok) {
+    const error = await response.json() as { error: string }
+    throw new Error(error.error || 'Query failed')
+  }
+
+  return response.json() as Promise<SqlResult<T>>
+}
+
+// =============================================================================
+// sql - Tagged Template API
+// =============================================================================
+
+/**
+ * SQL tagged template - safe parameterized queries
+ *
+ * @example
+ * ```typescript
+ * import { sql } from '@dotdo/postgres'
+ *
+ * const posts = await sql`SELECT * FROM posts`
+ * const post = await sql`SELECT * FROM posts WHERE id = ${id}`
+ * const newPost = await sql`INSERT INTO posts (title) VALUES (${title}) RETURNING *`
+ * ```
+ */
+export async function sql<T = Record<string, unknown>>(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): Promise<SqlResult<T>> {
+  const { sql: query, params } = buildQuery(strings, values)
+  return executeQuery<T>(query, params)
+}
+
+/**
+ * Execute raw SQL (use with caution - ensure input is sanitized)
+ */
+sql.unsafe = async function<T = Record<string, unknown>>(
+  query: string,
+  params?: unknown[]
+): Promise<SqlResult<T>> {
+  return executeQuery<T>(query, params)
+}
+
+// =============================================================================
+// db - Database Client API
+// =============================================================================
+
+/**
+ * Database client for programmatic access
+ *
+ * @example
+ * ```typescript
+ * import { db } from '@dotdo/postgres'
+ *
+ * const result = await db.query('SELECT * FROM posts')
+ * await db.exec('CREATE TABLE posts (id SERIAL PRIMARY KEY, title TEXT)')
+ * ```
+ */
+export const db = {
+  /**
+   * Execute a query and return results
+   */
+  async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<SqlResult<T>> {
+    return executeQuery<T>(sql, params)
+  },
+
+  /**
+   * Execute SQL without returning results (DDL, etc.)
+   */
+  async exec(sql: string): Promise<void> {
+    await executeQuery(sql)
+  },
+
+  /**
+   * Get raw access to the DO stub for advanced use cases
+   */
+  async getStub(): Promise<DOStub> {
+    return getStub()
+  },
+}
+
+// =============================================================================
+// Factory Functions (for custom binding/instance)
+// =============================================================================
+
+/**
+ * Create a sql function bound to a specific binding/instance
+ */
+export function createSql(env: Record<string, unknown>, config: SqlConfig = {}) {
+  const binding = config.binding || 'POSTGRES'
+  const instance = config.instance || 'default'
+
+  const namespace = env[binding] as PostgresNamespace | undefined
+  if (!namespace) {
+    throw new Error(`Postgres binding "${binding}" not found in env.`)
+  }
+
+  const stub = namespace.get(namespace.idFromName(instance))
+
+  async function boundSql<T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<SqlResult<T>> {
+    const { sql: query, params } = buildQuery(strings, values)
+
+    const response = await stub.fetch(new Request('http://do/query', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sql: query, params }),
+    }))
+
+    if (!response.ok) {
+      const error = await response.json() as { error: string }
+      throw new Error(error.error || 'Query failed')
+    }
+
+    return response.json() as Promise<SqlResult<T>>
+  }
+
+  boundSql.unsafe = async function<T = Record<string, unknown>>(
+    query: string,
+    params?: unknown[]
+  ): Promise<SqlResult<T>> {
+    const response = await stub.fetch(new Request('http://do/query', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sql: query, params }),
+    }))
+
+    if (!response.ok) {
+      const error = await response.json() as { error: string }
+      throw new Error(error.error || 'Query failed')
+    }
+
+    return response.json() as Promise<SqlResult<T>>
+  }
+
+  return boundSql
+}
+
+/**
+ * Create a db client bound to a specific binding/instance
+ */
+export function createDb(env: Record<string, unknown>, config: SqlConfig = {}) {
+  const binding = config.binding || 'POSTGRES'
+  const instance = config.instance || 'default'
+
+  const namespace = env[binding] as PostgresNamespace | undefined
+  if (!namespace) {
+    throw new Error(`Postgres binding "${binding}" not found in env.`)
+  }
+
+  const stub = namespace.get(namespace.idFromName(instance))
+
+  return {
+    async query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<SqlResult<T>> {
+      const response = await stub.fetch(new Request('http://do/query', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sql, params }),
+      }))
+
+      if (!response.ok) {
+        const error = await response.json() as { error: string }
+        throw new Error(error.error || 'Query failed')
+      }
+
+      return response.json() as Promise<SqlResult<T>>
+    },
+
+    async exec(sql: string): Promise<void> {
+      await this.query(sql)
+    },
+
+    getStub(): DOStub {
+      return stub
+    },
+  }
+}
+
+export default sql