singulio-postgres 1.1.0

package/src/health.ts

@@ -0,0 +1,226 @@
+/**
+ * @singulio/postgres - Health Check Utilities
+ * Kubernetes readiness/liveness probes for PostgreSQL
+ */
+
+import { sql } from 'bun';
+import type { HealthCheckResult, Logger } from './types.js';
+import type { PostgresPool } from './pool.js';
+
+/**
+ * Simple health check - verifies database connectivity
+ */
+export async function healthCheck(logger?: Logger): Promise<HealthCheckResult> {
+  const start = performance.now();
+
+  try {
+    const result = await sql`SELECT 1 as ok`;
+    const latencyMs = performance.now() - start;
+
+    const healthy = result.length > 0 && result[0].ok === 1;
+
+    logger?.debug('Health check completed', { healthy, latencyMs: latencyMs.toFixed(2) });
+
+    return {
+      healthy,
+      latencyMs,
+    };
+  } catch (error) {
+    const latencyMs = performance.now() - start;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    logger?.error('Health check failed', { error: errorMessage, latencyMs: latencyMs.toFixed(2) });
+
+    return {
+      healthy: false,
+      latencyMs,
+      error: errorMessage,
+    };
+  }
+}
+
+/**
+ * Extended health check with pool statistics
+ */
+export async function healthCheckWithPool(
+  pool: PostgresPool,
+  logger?: Logger
+): Promise<HealthCheckResult> {
+  const start = performance.now();
+
+  try {
+    // Query through pool
+    const result = await pool.query<{ ok: number }>('SELECT 1 as ok');
+    const latencyMs = performance.now() - start;
+
+    const healthy = result.rows.length > 0 && result.rows[0].ok === 1;
+    const poolStats = pool.stats();
+
+    logger?.debug('Pool health check completed', {
+      healthy,
+      latencyMs: latencyMs.toFixed(2),
+      ...poolStats,
+    });
+
+    return {
+      healthy,
+      latencyMs,
+      poolStats,
+    };
+  } catch (error) {
+    const latencyMs = performance.now() - start;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const poolStats = pool.stats();
+
+    logger?.error('Pool health check failed', {
+      error: errorMessage,
+      latencyMs: latencyMs.toFixed(2),
+      ...poolStats,
+    });
+
+    return {
+      healthy: false,
+      latencyMs,
+      poolStats,
+      error: errorMessage,
+    };
+  }
+}
+
+/**
+ * Deep health check - verifies database is accepting writes
+ */
+export async function deepHealthCheck(logger?: Logger): Promise<HealthCheckResult> {
+  const start = performance.now();
+
+  try {
+    // Check we can read and write
+    await sql`
+      CREATE TEMP TABLE IF NOT EXISTS _health_check (
+        id serial PRIMARY KEY,
+        ts timestamptz DEFAULT NOW()
+      )
+    `;
+
+    await sql`INSERT INTO _health_check DEFAULT VALUES`;
+    const result = await sql`SELECT COUNT(*) as count FROM _health_check`;
+    await sql`DROP TABLE IF EXISTS _health_check`;
+
+    const latencyMs = performance.now() - start;
+    const healthy = result.length > 0 && (result[0].count as number) > 0;
+
+    logger?.debug('Deep health check completed', {
+      healthy,
+      latencyMs: latencyMs.toFixed(2),
+    });
+
+    return {
+      healthy,
+      latencyMs,
+    };
+  } catch (error) {
+    const latencyMs = performance.now() - start;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    // Cleanup on error
+    try {
+      await sql`DROP TABLE IF EXISTS _health_check`;
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    logger?.error('Deep health check failed', {
+      error: errorMessage,
+      latencyMs: latencyMs.toFixed(2),
+    });
+
+    return {
+      healthy: false,
+      latencyMs,
+      error: errorMessage,
+    };
+  }
+}
+
+/**
+ * Check PostgreSQL version
+ */
+export async function getVersion(): Promise<string> {
+  const result = await sql`SELECT version()`;
+  return result[0]?.version ?? 'unknown';
+}
+
+/**
+ * Check if database is in recovery mode (replica)
+ */
+export async function isInRecovery(): Promise<boolean> {
+  const result = await sql`SELECT pg_is_in_recovery() as in_recovery`;
+  return result[0]?.in_recovery === true;
+}
+
+/**
+ * Get database size
+ */
+export async function getDatabaseSize(dbName?: string): Promise<string> {
+  const result = await sql.unsafe(
+    `SELECT pg_size_pretty(pg_database_size(${dbName ? '$1' : 'current_database()'}))::text as size`,
+    dbName ? [dbName] : []
+  );
+  return result[0]?.size ?? 'unknown';
+}
+
+/**
+ * Get connection count
+ */
+export async function getConnectionCount(): Promise<{
+  active: number;
+  idle: number;
+  total: number;
+  maxConnections: number;
+}> {
+  const result = await sql`
+    SELECT
+      COUNT(*) FILTER (WHERE state = 'active') as active,
+      COUNT(*) FILTER (WHERE state = 'idle') as idle,
+      COUNT(*) as total,
+      (SELECT setting::int FROM pg_settings WHERE name = 'max_connections') as max_connections
+    FROM pg_stat_activity
+    WHERE datname = current_database()
+  `;
+
+  return {
+    active: Number(result[0]?.active) || 0,
+    idle: Number(result[0]?.idle) || 0,
+    total: Number(result[0]?.total) || 0,
+    maxConnections: Number(result[0]?.max_connections) || 100,
+  };
+}
+
+/**
+ * Create an HTTP health check handler for Bun.serve
+ */
+export function createHealthHandler(pool?: PostgresPool) {
+  return async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+
+    if (url.pathname === '/health' || url.pathname === '/healthz') {
+      const result = pool ? await healthCheckWithPool(pool) : await healthCheck();
+
+      return new Response(JSON.stringify(result), {
+        status: result.healthy ? 200 : 503,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    if (url.pathname === '/ready' || url.pathname === '/readyz') {
+      const result = await deepHealthCheck();
+
+      return new Response(JSON.stringify(result), {
+        status: result.healthy ? 200 : 503,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    return new Response('Not Found', { status: 404 });
+  };
+}

package/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * @singulio/postgres
+ * PostgreSQL 18.x client for Bun with RLS, pooling, transactions, and pgvector support
+ *
+ * A thin wrapper around bun:postgres native client providing:
+ * - Connection pooling with configurable limits
+ * - Row-Level Security (RLS) helpers for multi-tenant isolation
+ * - Transaction support with auto-rollback
+ * - pgvector extension for AI/ML embeddings
+ * - Kubernetes health check utilities
+ *
+ * @example
+ * ```typescript
+ * import { createClient, createPool, withTenant, vectorSearch } from '@singulio/postgres';
+ *
+ * // Simple client
+ * const client = createClient(process.env.DATABASE_URL);
+ * const users = await client.queryAll('SELECT * FROM users');
+ *
+ * // With RLS tenant context
+ * const tenantData = await withTenant({ tenantId: 'tenant-123' }, async () => {
+ *   return client.queryAll('SELECT * FROM contacts'); // RLS filters by tenant
+ * });
+ *
+ * // Vector similarity search
+ * const similar = await vectorSearch('documents', 'embedding', queryVector, {
+ *   operator: '<=>',  // Cosine similarity
+ *   limit: 10,
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  PostgresConfig,
+  PoolConfig,
+  RLSContext,
+  QueryResult,
+  QueryRow,
+  FieldInfo,
+  IsolationLevel,
+  TransactionOptions,
+  HealthCheckResult,
+  PoolStats,
+  VectorDistanceOperator,
+  VectorIndexType,
+  VectorSearchOptions,
+  Logger,
+} from './types.js';
+
+// Client
+export { PostgresClient, createClient } from './client.js';
+
+// Pool
+export { PostgresPool, createPool } from './pool.js';
+
+// RLS
+export {
+  setRLSContext,
+  clearRLSContext,
+  getRLSContext,
+  withTenant,
+  queryWithTenant,
+  RLSClient,
+  createRLSClient,
+} from './rls.js';
+
+// Transactions
+export {
+  transaction,
+  serializableTransaction,
+  readOnlyTransaction,
+  savepoint,
+  rollbackToSavepoint,
+  releaseSavepoint,
+  type TransactionQuery,
+} from './transaction.js';
+
+// Vector (pgvector)
+export {
+  formatVector,
+  parseVector,
+  vectorDimension,
+  normalizeVector,
+  getDistanceOperator,
+  getDistanceOperatorName,
+  ensureVectorExtension,
+  createVectorColumn,
+  createVectorIndex,
+  vectorSearch,
+  insertWithVector,
+  updateVector,
+  batchInsertWithVectors,
+  type Vector,
+} from './vector.js';
+
+// Health
+export {
+  healthCheck,
+  healthCheckWithPool,
+  deepHealthCheck,
+  getVersion,
+  isInRecovery,
+  getDatabaseSize,
+  getConnectionCount,
+  createHealthHandler,
+} from './health.js';
+
+// Re-export bun:postgres sql for direct usage
+export { sql } from 'bun';

package/src/pool.ts

@@ -0,0 +1,268 @@
+/**
+ * @singulio/postgres - Connection Pool Manager
+ * Manages PostgreSQL connections with configurable pooling
+ *
+ * Note: Bun's native sql driver handles connection pooling internally.
+ * This module provides a higher-level API with explicit pool management
+ * for scenarios requiring fine-grained control.
+ */
+
+import { sql } from 'bun';
+import type { PoolConfig, PoolStats, QueryResult, QueryRow, Logger } from './types.js';
+
+interface PooledConnection {
+  id: number;
+  createdAt: number;
+  lastUsedAt: number;
+  inUse: boolean;
+}
+
+/** Internal pool config with required pool fields */
+interface InternalPoolConfig extends PoolConfig {
+  min: number;
+  max: number;
+  idleTimeout: number;
+  connectionTimeout: number;
+  maxLifetime: number;
+}
+
+/**
+ * Connection pool manager for PostgreSQL
+ */
+export class PostgresPool {
+  private config: InternalPoolConfig;
+  private logger?: Logger;
+  private connections: Map<number, PooledConnection> = new Map();
+  private nextId = 0;
+  private waitQueue: Array<{
+    resolve: (conn: PooledConnection) => void;
+    reject: (err: Error) => void;
+    timer: Timer;
+  }> = [];
+  private closed = false;
+  private idleCheckTimer?: Timer;
+
+  constructor(config: PoolConfig, logger?: Logger) {
+    this.config = {
+      min: 2,
+      max: 20,
+      idleTimeout: 30000,
+      connectionTimeout: 10000,
+      maxLifetime: 3600000,
+      ...config,
+    };
+    this.logger = logger;
+
+    // Start idle connection checker
+    this.idleCheckTimer = setInterval(() => this.checkIdleConnections(), 10000);
+  }
+
+  /**
+   * Initialize the pool with minimum connections
+   */
+  async initialize(): Promise<void> {
+    this.logger?.info('Initializing PostgreSQL pool', {
+      min: this.config.min,
+      max: this.config.max,
+    });
+
+    // Warm up minimum connections
+    for (let i = 0; i < this.config.min; i++) {
+      await this.createConnection();
+    }
+
+    this.logger?.info('PostgreSQL pool initialized', {
+      connections: this.connections.size,
+    });
+  }
+
+  private async createConnection(): Promise<PooledConnection> {
+    const conn: PooledConnection = {
+      id: this.nextId++,
+      createdAt: Date.now(),
+      lastUsedAt: Date.now(),
+      inUse: false,
+    };
+    this.connections.set(conn.id, conn);
+    return conn;
+  }
+
+  private async acquireConnection(): Promise<PooledConnection> {
+    // Find an idle connection
+    for (const conn of this.connections.values()) {
+      if (!conn.inUse) {
+        // Check if connection is too old
+        if (Date.now() - conn.createdAt > this.config.maxLifetime) {
+          await this.destroyConnection(conn);
+          continue;
+        }
+        conn.inUse = true;
+        conn.lastUsedAt = Date.now();
+        return conn;
+      }
+    }
+
+    // Create new connection if under max
+    if (this.connections.size < this.config.max) {
+      const conn = await this.createConnection();
+      conn.inUse = true;
+      return conn;
+    }
+
+    // Wait for a connection
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const idx = this.waitQueue.findIndex(w => w.resolve === resolve);
+        if (idx >= 0) this.waitQueue.splice(idx, 1);
+        reject(new Error(`Connection timeout after ${this.config.connectionTimeout}ms`));
+      }, this.config.connectionTimeout);
+
+      this.waitQueue.push({ resolve, reject, timer });
+    });
+  }
+
+  private releaseConnection(conn: PooledConnection): void {
+    conn.inUse = false;
+    conn.lastUsedAt = Date.now();
+
+    // Check waiting queue
+    if (this.waitQueue.length > 0) {
+      const waiter = this.waitQueue.shift()!;
+      clearTimeout(waiter.timer);
+      conn.inUse = true;
+      waiter.resolve(conn);
+    }
+  }
+
+  private async destroyConnection(conn: PooledConnection): Promise<void> {
+    this.connections.delete(conn.id);
+    this.logger?.debug('Connection destroyed', { id: conn.id });
+  }
+
+  private async checkIdleConnections(): Promise<void> {
+    if (this.closed) return;
+
+    const now = Date.now();
+    for (const conn of this.connections.values()) {
+      // Don't close if we're at minimum
+      if (this.connections.size <= this.config.min) break;
+
+      if (!conn.inUse && now - conn.lastUsedAt > this.config.idleTimeout) {
+        await this.destroyConnection(conn);
+      }
+    }
+  }
+
+  /**
+   * Execute a query using a pooled connection
+   */
+  async query<T = QueryRow>(queryText: string, params?: unknown[]): Promise<QueryResult<T>> {
+    if (this.closed) {
+      throw new Error('Pool is closed');
+    }
+
+    const conn = await this.acquireConnection();
+    const start = performance.now();
+
+    try {
+      const result = await sql.unsafe(queryText, params ?? []);
+      const latency = performance.now() - start;
+
+      this.logger?.debug('Pool query executed', {
+        connId: conn.id,
+        query: queryText.substring(0, 100),
+        rows: result.length,
+        latencyMs: latency.toFixed(2),
+      });
+
+      return {
+        rows: result as T[],
+        rowCount: result.length,
+      };
+    } finally {
+      this.releaseConnection(conn);
+    }
+  }
+
+  /**
+   * Execute with exclusive connection for multi-statement operations
+   */
+  async withConnection<T>(
+    fn: (query: (sql: string, params?: unknown[]) => Promise<QueryResult>) => Promise<T>
+  ): Promise<T> {
+    if (this.closed) {
+      throw new Error('Pool is closed');
+    }
+
+    const conn = await this.acquireConnection();
+
+    try {
+      return await fn(async (queryText: string, params?: unknown[]) => {
+        const result = await sql.unsafe(queryText, params ?? []);
+        return {
+          rows: result,
+          rowCount: result.length,
+        };
+      });
+    } finally {
+      this.releaseConnection(conn);
+    }
+  }
+
+  /**
+   * Get current pool statistics
+   */
+  stats(): PoolStats {
+    let idle = 0;
+    let active = 0;
+
+    for (const conn of this.connections.values()) {
+      if (conn.inUse) {
+        active++;
+      } else {
+        idle++;
+      }
+    }
+
+    return {
+      total: this.connections.size,
+      idle,
+      active,
+      pending: this.waitQueue.length,
+    };
+  }
+
+  /**
+   * Close the pool and all connections
+   */
+  async close(): Promise<void> {
+    this.closed = true;
+
+    if (this.idleCheckTimer) {
+      clearInterval(this.idleCheckTimer);
+    }
+
+    // Reject all waiting
+    for (const waiter of this.waitQueue) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error('Pool is closing'));
+    }
+    this.waitQueue = [];
+
+    // Destroy all connections
+    for (const conn of this.connections.values()) {
+      await this.destroyConnection(conn);
+    }
+
+    this.logger?.info('PostgreSQL pool closed');
+  }
+}
+
+/**
+ * Create and initialize a connection pool
+ */
+export async function createPool(config: PoolConfig, logger?: Logger): Promise<PostgresPool> {
+  const pool = new PostgresPool(config, logger);
+  await pool.initialize();
+  return pool;
+}