@dotdo/postgres 0.1.2 → 0.1.3

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[]>
+}
+`

package/src/mcp/index.ts

@@ -0,0 +1,122 @@
+/**
+ * MCP Server Module for PostgresDO
+ *
+ * Provides MCP (Model Context Protocol) server implementation for PostgreSQL
+ * databases running in Cloudflare Durable Objects.
+ *
+ * ## Overview
+ *
+ * This module implements the three core MCP primitives:
+ *
+ * 1. **search** - Query the database with SQL, list tables, or get schema
+ * 2. **fetch** - Get a specific row by table/id or table schema
+ * 3. **do** - Execute code with the `pg` binding for full database access
+ *
+ * ## Usage
+ *
+ * @example Basic MCP server setup
+ * ```typescript
+ * import { createMCPServer } from '@dotdo/postgres/mcp'
+ * import { PostgresDO } from '@dotdo/postgres/worker'
+ *
+ * // In your worker
+ * const stub = env.POSTGRES_DO.get(doId) as DurableObjectStub<PostgresDO>
+ * const mcpServer = createMCPServer(stub, { databaseId: 'mydb' })
+ *
+ * // Mount routes
+ * app.route('/mcp', mcpServer.routes())
+ * ```
+ *
+ * @example With auth context from oauth.do JWT
+ * ```typescript
+ * const mcpServer = createMCPServer(stub, {
+ *   databaseId: 'mydb',
+ *   authContext: {
+ *     userId: user.id,
+ *     email: user.email,
+ *     scopes: ['read', 'write'],
+ *   },
+ * })
+ * ```
+ *
+ * @example Using tools directly
+ * ```typescript
+ * // Search for tables
+ * const result = await mcpServer.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'tools/call',
+ *   params: {
+ *     name: 'search',
+ *     arguments: { query: 'tables' }
+ *   }
+ * })
+ *
+ * // Fetch a row
+ * const row = await mcpServer.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 2,
+ *   method: 'tools/call',
+ *   params: {
+ *     name: 'fetch',
+ *     arguments: { resource: 'users/123' }
+ *   }
+ * })
+ *
+ * // Execute code
+ * const code = await mcpServer.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 3,
+ *   method: 'tools/call',
+ *   params: {
+ *     name: 'do',
+ *     arguments: {
+ *       code: `
+ *         const users = await pg.query('SELECT * FROM users LIMIT 5')
+ *         return users.rows
+ *       `
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @module mcp
+ */
+
+// Types
+export type {
+  QueryResult,
+  TableInfo,
+  ColumnInfo,
+  MCPSearchResult,
+  MCPFetchResult,
+  PGBinding,
+  PGTransaction,
+  ToolResponse,
+  SearchInput,
+  FetchInput,
+  DoInput,
+  MCPAuthContext,
+  MCPServerConfig,
+} from './types.js'
+
+// Binding
+export { createPGBinding, PG_BINDING_TYPES } from './binding.js'
+export type { QueryExecutor } from './binding.js'
+
+// Tools
+export {
+  searchTool,
+  fetchTool,
+  doTool,
+  getToolDefinitions,
+  createToolHandlers,
+  createSearchHandler,
+  createFetchHandler,
+  createDoHandler,
+} from './tools.js'
+export type { Tool } from './tools.js'
+
+// Server
+export { createMCPServer, createMCPRoutes } from './server.js'
+export type { MCPServer } from './server.js'