@dotdo/postgres 0.1.1 → 0.1.3

package/src/client/types.ts

@@ -0,0 +1,211 @@
+/**
+ * Type definitions for the PostgresDO WebSocket client
+ *
+ * @module client/types
+ */
+
+import type { QueryResultRow, QueryField } from '../worker/types'
+
+/**
+ * Query result from PostgresDO RPC
+ */
+export interface RpcQueryResult<T extends QueryResultRow = QueryResultRow> {
+  rows: T[]
+  fields: QueryField[]
+  rowCount: number
+  durationMs: number
+}
+
+/**
+ * Batch query input
+ */
+export interface RpcBatchQuery {
+  sql: string
+  params?: unknown[]
+}
+
+/**
+ * Batch result from PostgresDO RPC
+ */
+export interface RpcBatchResult {
+  results: RpcQueryResult[]
+  durationMs: number
+}
+
+/**
+ * Transaction options for RPC
+ */
+export interface RpcTransactionOptions {
+  isolationLevel?: 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE'
+  readOnly?: boolean
+}
+
+/**
+ * Table column information
+ */
+export interface ColumnInfo {
+  column_name: string
+  data_type: string
+  is_nullable: boolean
+  column_default: string | null
+}
+
+/**
+ * Database statistics
+ */
+export interface DatabaseStats {
+  queryCount: number
+  totalDurationMs: number
+  avgDurationMs: number
+  lastQueryAt: Date | null
+  uptime: number
+  shutdownStatus: 'running' | 'draining' | 'shutdown'
+}
+
+/**
+ * PostgresDO RPC API interface
+ *
+ * This interface defines all the RPC methods available on PostgresDO.
+ * Used for type-safe client generation with rpc.do.
+ */
+export interface PostgresDORpcApi {
+  // Query methods
+  rpcQuery<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<RpcQueryResult<T>>
+
+  rpcQueryOne<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<T | null>
+
+  rpcQueryScalar<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>
+
+  rpcExecute(sql: string, params?: unknown[]): Promise<{ rowCount: number; durationMs: number }>
+
+  // Batch methods
+  rpcBatch(queries: RpcBatchQuery[]): Promise<RpcBatchResult>
+
+  rpcBatchTransaction(queries: RpcBatchQuery[]): Promise<RpcBatchResult>
+
+  // Transaction methods
+  rpcTransaction(options?: RpcTransactionOptions): Promise<TransactionApi>
+
+  // Utility methods
+  rpcPing(): Promise<{ ok: true; durationMs: number }>
+
+  rpcVersion(): Promise<string>
+
+  rpcListTables(): Promise<string[]>
+
+  rpcDescribeTable(tableName: string): Promise<ColumnInfo[]>
+
+  rpcGetStats(): Promise<DatabaseStats>
+}
+
+/**
+ * Transaction API returned by rpcTransaction
+ */
+export interface TransactionApi {
+  query<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<RpcQueryResult<T>>
+
+  queryOne<T extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<T | null>
+
+  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number; durationMs: number }>
+
+  commit(): Promise<void>
+
+  rollback(): Promise<void>
+}
+
+/**
+ * Client configuration options
+ */
+export interface PostgresClientConfig {
+  /**
+   * WebSocket URL for the PostgresDO endpoint
+   * @example 'wss://postgres.example.com/ws'
+   */
+  url: string
+
+  /**
+   * Authentication token or provider function
+   * Can be a static token string or an async function that returns a token
+   */
+  auth?: string | (() => string | null | Promise<string | null>)
+
+  /**
+   * Enable automatic reconnection on disconnect
+   * @default true
+   */
+  autoReconnect?: boolean
+
+  /**
+   * Maximum number of reconnection attempts
+   * @default Infinity
+   */
+  maxReconnectAttempts?: number
+
+  /**
+   * Initial backoff delay in ms for reconnection
+   * @default 1000
+   */
+  reconnectBackoff?: number
+
+  /**
+   * Maximum backoff delay in ms for reconnection
+   * @default 30000
+   */
+  maxReconnectBackoff?: number
+
+  /**
+   * Heartbeat interval in ms (0 to disable)
+   * @default 30000
+   */
+  heartbeatInterval?: number
+
+  /**
+   * Callback when connection is established
+   */
+  onConnect?: () => void
+
+  /**
+   * Callback when connection is lost
+   */
+  onDisconnect?: (reason: string) => void
+
+  /**
+   * Callback when attempting to reconnect
+   */
+  onReconnecting?: (attempt: number, maxAttempts: number) => void
+
+  /**
+   * Callback on any error
+   */
+  onError?: (error: Error) => void
+
+  /**
+   * Allow auth over insecure ws:// connections
+   * WARNING: Only for local development
+   * @default false
+   */
+  allowInsecureAuth?: boolean
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean
+}
+
+/**
+ * Connection state for the client
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'closed'

package/src/do/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Postgres Durable Object Module
+ *
+ * Minimal API for PostgreSQL in Cloudflare Workers.
+ *
+ * @example
+ * ```typescript
+ * import { sql, db, Postgres } from '@dotdo/postgres'
+ * export { Postgres }
+ *
+ * export default {
+ *   fetch: async () => Response.json(await sql`SELECT * FROM posts`)
+ * }
+ * ```
+ */
+
+export { Postgres, type PostgresEnv, type QueryResult } from './postgres'
+export { sql, db, createSql, createDb, type SqlConfig, type SqlResult } from './sql'

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