@dotdo/postgres 0.1.1 → 0.1.3

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

package/src/index.ts

@@ -1,48 +1,46 @@
 /**
  * @module @dotdo/postgres
  *
- * PostgreSQL server for Cloudflare Workers/DOs with PGLite WASM and tiered storage.
+ * PostgreSQL for Cloudflare Workers - Simple, Persistent, Powerful.
  *
- * This package provides a complete PostgreSQL-compatible database solution
- * optimized for Cloudflare's edge infrastructure:
- *
- * - **Worker Module**: PostgresDO Durable Object with HTTP/WebSocket APIs
- * - **PGLite Module**: Tiered storage system (Cache/DO/R2) for PGLite
- * - **Extensions Module**: PGLite extension management and pgvector support
- * - **Routing Module**: Intelligent query routing based on CPU cost estimation
- * - **Read-Only Module**: Security-focused read-only deployment mode
- * - **Middleware Module**: Rate limiting with sliding window and token bucket algorithms
- *
- * @example
+ * @example Minimal API
  * ```typescript
- * import {
- *   PostgresDO,
- *   createRoutes,
- *   WebSocketHandler,
- * } from '@dotdo/postgres'
- *
- * // Export the Durable Object
- * export { PostgresDO }
- *
- * // Create Hono routes
- * const app = new Hono()
- * app.route('/api/sql', createRoutes(env))
+ * import { sql, Postgres } from '@dotdo/postgres'
+ * export { Postgres }
  *
  * export default {
- *   fetch: app.fetch,
+ *   fetch: () => Response.json(await sql`SELECT * FROM posts`)
  * }
  * ```
  *
- * @example
+ * @example With Hono
  * ```typescript
- * // Use tiered storage for PGLite
- * import { createDOVFS, TieredVFS, CacheLayer } from '@dotdo/postgres/pglite'
+ * import { Hono } from 'hono'
+ * import { sql, Postgres } from '@dotdo/postgres'
+ * export { Postgres }
  *
- * const vfs = createDOVFS(ctx.storage)
- * const pglite = await PGlite.create({ vfs })
+ * const app = new Hono()
+ * app.get('/posts', c => sql`SELECT * FROM posts`.then(r => c.json(r)))
+ * app.get('/posts/:id', c => sql`SELECT * FROM posts WHERE id = ${c.req.param('id')}`.then(r => c.json(r)))
+ *
+ * export default app
  * ```
+ *
+ * The Postgres Durable Object provides:
+ * - Full PostgreSQL via PGLite WASM
+ * - Automatic persistence via DO SQLite
+ * - Safe parameterized queries via tagged templates
+ *
+ * For advanced features (tiered storage, migrations, observability), see submodules.
  */
 
+// ============================================================================
+// Core API - The Minimal Interface
+// ============================================================================
+
+export { sql, db, createSql, createDb, Postgres } from './do'
+export type { SqlConfig, SqlResult, PostgresEnv, QueryResult } from './do'
+
 // ============================================================================
 // Configuration Module - Centralized Constants
 // ============================================================================
@@ -210,3 +208,25 @@ export type {
   // Discriminated union
   DiscriminatedMessage,
 } from './types/utilities'
+
+// ============================================================================
+// Client Module - WebSocket client with rpc.do integration
+// ============================================================================
+
+export {
+  PostgresClient,
+  createPostgresClient,
+} from './client'
+
+export type {
+  PostgresClientConfig,
+  PostgresDORpcApi,
+  RpcQueryResult,
+  RpcBatchQuery,
+  RpcBatchResult,
+  RpcTransactionOptions,
+  TransactionApi,
+  ColumnInfo,
+  DatabaseStats,
+  ConnectionState,
+} from './client'

package/src/mcp/binding.ts

@@ -0,0 +1,236 @@
+/**
+ * PostgreSQL Binding for MCP Do Tool
+ *
+ * Creates the `pg` binding that is available in the sandboxed code execution
+ * environment. Wraps PostgresDO RPC calls in a clean API.
+ */
+
+import type {
+  PGBinding,
+  PGTransaction,
+  QueryResult,
+  TableInfo,
+  ColumnInfo,
+} from './types.js'
+
+/**
+ * Interface for the query executor (PostgresDO stub)
+ */
+export interface QueryExecutor {
+  rpcQuery(sql: string, params?: unknown[]): Promise<{
+    rows: Record<string, unknown>[]
+    fields: Array<{ name: string; dataTypeID: number }>
+    rowCount: number
+  }>
+  rpcBatchTransaction(
+    queries: Array<{ sql: string; params?: unknown[] }>
+  ): Promise<{
+    results: Array<{
+      rows: Record<string, unknown>[]
+      fields: Array<{ name: string; dataTypeID: number }>
+      rowCount: number
+    }>
+    success: boolean
+  }>
+}
+
+/**
+ * Create the pg binding for the do tool
+ *
+ * @param executor - Query executor (PostgresDO stub)
+ * @returns The pg binding object
+ */
+export function createPGBinding(executor: QueryExecutor): PGBinding {
+  return {
+    async query<T = Record<string, unknown>>(
+      sql: string,
+      params?: unknown[]
+    ): Promise<QueryResult<T>> {
+      const result = await executor.rpcQuery(sql, params)
+      return {
+        rows: result.rows as T[],
+        rowCount: result.rowCount,
+        fields: result.fields,
+      }
+    },
+
+    async execute(
+      sql: string,
+      params?: unknown[]
+    ): Promise<{ rowCount: number }> {
+      const result = await executor.rpcQuery(sql, params)
+      return { rowCount: result.rowCount }
+    },
+
+    async transaction<T>(fn: (tx: PGTransaction) => Promise<T>): Promise<T> {
+      // Execute BEGIN, run function with transaction context, execute COMMIT/ROLLBACK
+      await executor.rpcQuery('BEGIN')
+
+      try {
+        const result = await fn({
+          async query<R = Record<string, unknown>>(
+            sql: string,
+            params?: unknown[]
+          ): Promise<QueryResult<R>> {
+            const res = await executor.rpcQuery(sql, params)
+            return {
+              rows: res.rows as R[],
+              rowCount: res.rowCount,
+              fields: res.fields,
+            }
+          },
+          async execute(
+            sql: string,
+            params?: unknown[]
+          ): Promise<{ rowCount: number }> {
+            const res = await executor.rpcQuery(sql, params)
+            return { rowCount: res.rowCount }
+          },
+        })
+
+        await executor.rpcQuery('COMMIT')
+        return result
+      } catch (error) {
+        await executor.rpcQuery('ROLLBACK')
+        throw error
+      }
+    },
+
+    async tables(): Promise<TableInfo[]> {
+      const result = await executor.rpcQuery(`
+        SELECT
+          table_name as name,
+          table_schema as schema,
+          CASE table_type
+            WHEN 'BASE TABLE' THEN 'table'
+            WHEN 'VIEW' THEN 'view'
+            ELSE 'table'
+          END as type
+        FROM information_schema.tables
+        WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+        ORDER BY table_schema, table_name
+      `)
+
+      return result.rows.map((row) => ({
+        name: row.name as string,
+        schema: row.schema as string,
+        type: row.type as 'table' | 'view' | 'materialized_view',
+      }))
+    },
+
+    async schema(tableName: string): Promise<ColumnInfo[]> {
+      // Validate table name to prevent SQL injection
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(tableName)) {
+        throw new Error('Invalid table name')
+      }
+
+      const result = await executor.rpcQuery(
+        `
+        SELECT
+          c.column_name as name,
+          c.data_type as type,
+          c.is_nullable = 'YES' as nullable,
+          c.column_default as "default",
+          COALESCE(
+            (SELECT true FROM information_schema.key_column_usage kcu
+             JOIN information_schema.table_constraints tc
+               ON kcu.constraint_name = tc.constraint_name
+             WHERE tc.constraint_type = 'PRIMARY KEY'
+               AND kcu.table_name = c.table_name
+               AND kcu.column_name = c.column_name
+             LIMIT 1),
+            false
+          ) as "primaryKey"
+        FROM information_schema.columns c
+        WHERE c.table_name = $1
+          AND c.table_schema NOT IN ('pg_catalog', 'information_schema')
+        ORDER BY c.ordinal_position
+      `,
+        [tableName]
+      )
+
+      return result.rows.map((row) => ({
+        name: row.name as string,
+        type: row.type as string,
+        nullable: Boolean(row.nullable),
+        ...(row.default !== null && { default: row.default as string }),
+        primaryKey: Boolean(row.primaryKey),
+      }))
+    },
+  }
+}
+
+/**
+ * TypeScript type definitions for the pg binding
+ * Used by the do tool to provide type information to LLMs
+ */
+export const PG_BINDING_TYPES = `
+interface QueryResult<T = Record<string, unknown>> {
+  rows: T[]
+  rowCount: number
+  fields: Array<{ name: string; dataTypeID: number }>
+}
+
+interface TableInfo {
+  name: string
+  schema: string
+  type: 'table' | 'view' | 'materialized_view'
+}
+
+interface ColumnInfo {
+  name: string
+  type: string
+  nullable: boolean
+  default?: string
+  primaryKey: boolean
+}
+
+interface PGTransaction {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>
+  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>
+}
+
+declare const pg: {
+  /**
+   * Execute a SQL query with optional parameters
+   * @example
+   * const users = await pg.query('SELECT * FROM users WHERE age > $1', [18])
+   * console.log(users.rows)
+   */
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE)
+   * @example
+   * const result = await pg.execute('UPDATE users SET active = true WHERE id = $1', [1])
+   * console.log(result.rowCount)
+   */
+  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>
+
+  /**
+   * Execute multiple statements in a transaction
+   * @example
+   * await pg.transaction(async (tx) => {
+   *   await tx.execute('INSERT INTO orders (user_id) VALUES ($1)', [1])
+   *   await tx.execute('UPDATE users SET order_count = order_count + 1 WHERE id = $1', [1])
+   * })
+   */
+  transaction<T>(fn: (tx: PGTransaction) => Promise<T>): Promise<T>
+
+  /**
+   * List all tables in the database
+   * @example
+   * const tables = await pg.tables()
+   * tables.forEach(t => console.log(t.name))
+   */
+  tables(): Promise<TableInfo[]>
+
+  /**
+   * Get schema information for a table
+   * @example
+   * const columns = await pg.schema('users')
+   * columns.forEach(c => console.log(\`\${c.name}: \${c.type}\`))
+   */
+  schema(tableName: string): Promise<ColumnInfo[]>
+}
+`