singulio-postgres 1.1.0

package/README.md

@@ -0,0 +1,866 @@
+# @singulio/postgres
+
+High-performance PostgreSQL 18.x client for Bun with Row-Level Security (RLS), connection pooling, transactions, and pgvector support for AI/ML workloads.
+
+## Overview
+
+`@singulio/postgres` is a thin, type-safe wrapper around Bun's native `bun:postgres` driver that provides enterprise-grade features for modern PostgreSQL applications:
+
+- **Row-Level Security (RLS)**: Native multi-tenant isolation using PostgreSQL session GUCs
+- **Connection Pooling**: Configurable pooling with idle timeout and max lifetime management
+- **Transaction Support**: ACID transactions with auto-rollback, isolation levels, and savepoints
+- **pgvector Integration**: First-class support for AI/ML embeddings and similarity search
+- **Health Checks**: Kubernetes-ready readiness/liveness probes
+- **Zero Dependencies**: Leverages Bun's native PostgreSQL driver for maximum performance
+- **Full TypeScript**: Complete type safety with intelligent type inference
+
+## Features
+
+### Core Capabilities
+
+- **Simple Client API**: Easy-to-use query methods (query, queryOne, queryAll, execute)
+- **Connection Pooling**: Automatic connection lifecycle management with configurable limits
+- **RLS Helpers**: Multi-tenant data isolation with session-scoped context
+- **Transaction Management**: Nested transactions, savepoints, and configurable isolation levels
+- **Vector Operations**: Full pgvector support for embeddings, similarity search, and batch operations
+- **Health Monitoring**: Built-in health check endpoints for Kubernetes deployments
+- **Performance**: Native Bun driver with minimal overhead
+
+### Database Compatibility
+
+- PostgreSQL 18.x (recommended)
+- PostgreSQL 16+ with pgvector extension
+
+## Installation
+
+### npm
+
+```bash
+npm install @singulio/postgres
+```
+
+### yarn
+
+```bash
+yarn add @singulio/postgres
+```
+
+### bun
+
+```bash
+bun add @singulio/postgres
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { createClient } from '@singulio/postgres';
+
+// Create a client
+const client = createClient(process.env.DATABASE_URL);
+
+// Simple query
+const users = await client.queryAll('SELECT * FROM users WHERE active = $1', [true]);
+
+// Insert with returning
+const newUser = await client.queryOne(
+  'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
+  ['Alice', 'alice@example.com']
+);
+
+// Execute command (returns affected row count)
+const deleted = await client.execute('DELETE FROM users WHERE id = $1', [123]);
+
+console.log(`Deleted ${deleted} user(s)`);
+```
+
+### Connection Pooling
+
+```typescript
+import { createPool } from '@singulio/postgres';
+
+// Create and initialize pool
+const pool = await createPool({
+  connectionString: process.env.DATABASE_URL,
+  min: 5,           // Minimum connections
+  max: 20,          // Maximum connections
+  idleTimeout: 30000,     // Close idle connections after 30s
+  connectionTimeout: 5000, // Timeout acquiring connection
+  maxLifetime: 3600000,   // Recycle connections after 1 hour
+});
+
+// Query through pool
+const result = await pool.query('SELECT * FROM products WHERE price < $1', [100]);
+
+// Use exclusive connection for multiple queries
+const stats = await pool.withConnection(async (query) => {
+  const total = await query('SELECT COUNT(*) FROM orders');
+  const pending = await query('SELECT COUNT(*) FROM orders WHERE status = $1', ['pending']);
+  return { total: total.rows[0].count, pending: pending.rows[0].count };
+});
+
+// Get pool statistics
+const poolStats = pool.stats();
+console.log(`Pool: ${poolStats.active} active, ${poolStats.idle} idle, ${poolStats.pending} waiting`);
+
+// Close pool when done
+await pool.close();
+```
+
+### Row-Level Security (RLS)
+
+```typescript
+import { createClient, withTenant, createRLSClient } from '@singulio/postgres';
+
+const client = createClient(process.env.DATABASE_URL);
+
+// Execute queries within tenant context
+const tenantData = await withTenant(
+  { tenantId: 'tenant-abc', userId: 'user-123', isAdmin: false },
+  async () => {
+    // All queries here automatically filtered by tenant
+    return await client.queryAll('SELECT * FROM contacts');
+  }
+);
+
+// RLS-aware client
+const rlsClient = createRLSClient();
+
+// Query with explicit tenant context
+const orders = await rlsClient.queryAll(
+  { tenantId: 'tenant-xyz' },
+  'SELECT * FROM orders WHERE status = $1',
+  ['shipped']
+);
+
+// Admin bypass
+const allData = await rlsClient.queryAll(
+  { tenantId: 'tenant-xyz', isAdmin: true },
+  'SELECT * FROM sensitive_data'
+);
+```
+
+### Transactions
+
+```typescript
+import { transaction, serializableTransaction, savepoint } from '@singulio/postgres';
+
+// Basic transaction with auto-rollback
+await transaction(async (tx) => {
+  await tx.execute('UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, 1]);
+  await tx.execute('UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, 2]);
+  // Auto-commits on success, auto-rollbacks on error
+});
+
+// Serializable transaction for strong consistency
+await serializableTransaction(async (tx) => {
+  const inventory = await tx.queryOne('SELECT quantity FROM inventory WHERE sku = $1', ['ABC']);
+  if (inventory.quantity > 0) {
+    await tx.execute('UPDATE inventory SET quantity = quantity - 1 WHERE sku = $1', ['ABC']);
+    await tx.execute('INSERT INTO orders (sku, quantity) VALUES ($1, 1)', ['ABC']);
+  }
+});
+
+// Transaction with RLS context
+await transaction(
+  async (tx) => {
+    const contact = await tx.queryOne('SELECT * FROM contacts WHERE id = $1', [456]);
+    await tx.execute('UPDATE contacts SET last_viewed = NOW() WHERE id = $1', [456]);
+    return contact;
+  },
+  {
+    isolationLevel: 'REPEATABLE READ',
+    rlsContext: { tenantId: 'tenant-123' }
+  }
+);
+
+// Savepoints for nested rollback
+await transaction(async (tx) => {
+  await tx.execute('INSERT INTO logs (message) VALUES ($1)', ['Started']);
+
+  await savepoint('before_update');
+  try {
+    await tx.execute('UPDATE critical_table SET value = $1', [newValue]);
+  } catch (error) {
+    await rollbackToSavepoint('before_update');
+    // Continue transaction with fallback
+  }
+
+  await tx.execute('INSERT INTO logs (message) VALUES ($1)', ['Completed']);
+});
+```
+
+### Vector Search (pgvector)
+
+```typescript
+import {
+  ensureVectorExtension,
+  createVectorColumn,
+  createVectorIndex,
+  vectorSearch,
+  insertWithVector,
+  formatVector,
+} from '@singulio/postgres';
+
+// Setup pgvector extension
+await ensureVectorExtension();
+
+// Add vector column to existing table
+await createVectorColumn('documents', 'embedding', 1536); // OpenAI ada-002 dimension
+
+// Create HNSW index for fast similarity search
+await createVectorIndex('documents', 'embedding', 'hnsw', '<=>', {
+  m: 16,              // Max connections per layer
+  efConstruction: 64  // Build quality
+});
+
+// Insert document with embedding
+const embedding = [0.1, 0.2, 0.3, /* ... 1536 dimensions */];
+await insertWithVector(
+  'documents',
+  { title: 'AI Report', content: 'Lorem ipsum...' },
+  'embedding',
+  embedding
+);
+
+// Similarity search using cosine distance
+const queryEmbedding = [0.15, 0.25, 0.35, /* ... */];
+const results = await vectorSearch('documents', 'embedding', queryEmbedding, {
+  operator: '<=>',  // Cosine similarity
+  limit: 10,
+  threshold: 0.3,   // Max distance threshold
+  filter: 'created_at > $1',
+  filterParams: [new Date('2024-01-01')],
+});
+
+for (const doc of results.rows) {
+  console.log(`${doc.title} - similarity: ${1 - doc.distance}`);
+}
+
+// Batch insert with vectors
+await batchInsertWithVectors(
+  'documents',
+  ['title', 'content'],
+  'embedding',
+  [
+    { data: ['Doc 1', 'Content 1'], vector: embedding1 },
+    { data: ['Doc 2', 'Content 2'], vector: embedding2 },
+  ]
+);
+
+// Supported distance operators:
+// '<->' - L2 (Euclidean) distance
+// '<=>' - Cosine distance (1 - cosine similarity)
+// '<#>' - Inner product (negative)
+// '<+>' - L1 (Manhattan) distance
+```
+
+## API Reference
+
+### Client
+
+#### `createClient(config, logger?)`
+
+Creates a new PostgreSQL client.
+
+**Parameters:**
+- `config`: Connection string or `PostgresConfig` object
+- `logger`: Optional logger instance (matches `@singulio/logger` interface)
+
+**Returns:** `PostgresClient`
+
+#### PostgresClient Methods
+
+##### `query<T>(queryText, params?): Promise<QueryResult<T>>`
+
+Execute a SQL query with parameters.
+
+##### `queryOne<T>(queryText, params?): Promise<T | null>`
+
+Execute query and return first row or null.
+
+##### `queryAll<T>(queryText, params?): Promise<T[]>`
+
+Execute query and return all rows.
+
+##### `execute(queryText, params?): Promise<number>`
+
+Execute command and return affected row count.
+
+##### `ping(): Promise<boolean>`
+
+Check database connectivity.
+
+##### `version(): Promise<string>`
+
+Get PostgreSQL server version.
+
+##### `close(): Promise<void>`
+
+Close client connection.
+
+### Pool
+
+#### `createPool(config, logger?): Promise<PostgresPool>`
+
+Create and initialize a connection pool.
+
+**Parameters:**
+- `config`: `PoolConfig` object with connection and pool settings
+- `logger`: Optional logger instance
+
+**Returns:** `Promise<PostgresPool>`
+
+#### PostgresPool Methods
+
+##### `initialize(): Promise<void>`
+
+Initialize pool with minimum connections (called automatically by `createPool`).
+
+##### `query<T>(queryText, params?): Promise<QueryResult<T>>`
+
+Execute query using pooled connection.
+
+##### `withConnection<T>(fn): Promise<T>`
+
+Execute function with exclusive connection.
+
+**Example:**
+```typescript
+const result = await pool.withConnection(async (query) => {
+  const r1 = await query('SELECT ...');
+  const r2 = await query('UPDATE ...');
+  return { r1, r2 };
+});
+```
+
+##### `stats(): PoolStats`
+
+Get current pool statistics (total, idle, active, pending).
+
+##### `close(): Promise<void>`
+
+Close pool and all connections.
+
+### Row-Level Security
+
+#### `setRLSContext(context): Promise<void>`
+
+Set RLS context variables for current session.
+
+**Parameters:**
+- `context.tenantId`: Tenant identifier (required)
+- `context.userId`: User identifier (optional)
+- `context.isAdmin`: Admin flag (optional, default: false)
+- `context.extraGUCs`: Additional session variables (optional)
+
+#### `clearRLSContext(): Promise<void>`
+
+Clear RLS context variables.
+
+#### `getRLSContext(): Promise<RLSContext | null>`
+
+Get current RLS context.
+
+#### `withTenant<T>(context, fn): Promise<T>`
+
+Execute function with RLS context, auto-cleanup.
+
+#### `queryWithTenant<T>(context, queryText, params?): Promise<QueryResult<T>>`
+
+Execute single query with RLS context.
+
+#### `createRLSClient(logger?): RLSClient`
+
+Create RLS-aware client wrapper.
+
+**RLSClient Methods:**
+- `query<T>(context, queryText, params?): Promise<QueryResult<T>>`
+- `queryOne<T>(context, queryText, params?): Promise<T | null>`
+- `queryAll<T>(context, queryText, params?): Promise<T[]>`
+- `withTenant<T>(context, fn): Promise<T>`
+
+### Transactions
+
+#### `transaction<T>(fn, options?, logger?): Promise<T>`
+
+Execute function within transaction with auto-commit/rollback.
+
+**Parameters:**
+- `fn`: Function receiving `TransactionQuery` interface
+- `options.isolationLevel`: 'READ UNCOMMITTED' | 'READ COMMITTED' | 'REPEATABLE READ' | 'SERIALIZABLE'
+- `options.readOnly`: Read-only transaction (default: false)
+- `options.deferrable`: Deferrable (requires SERIALIZABLE + readOnly)
+- `options.rlsContext`: RLS context to apply
+- `logger`: Optional logger
+
+**TransactionQuery Methods:**
+- `query<T>(queryText, params?): Promise<QueryResult<T>>`
+- `queryOne<T>(queryText, params?): Promise<T | null>`
+- `queryAll<T>(queryText, params?): Promise<T[]>`
+- `execute(queryText, params?): Promise<number>`
+
+#### `serializableTransaction<T>(fn, rlsContext?, logger?): Promise<T>`
+
+Execute with SERIALIZABLE isolation level.
+
+#### `readOnlyTransaction<T>(fn, rlsContext?, logger?): Promise<T>`
+
+Execute read-only transaction (optimized for reporting).
+
+#### `savepoint(name): Promise<void>`
+
+Create savepoint within transaction.
+
+#### `rollbackToSavepoint(name): Promise<void>`
+
+Rollback to savepoint.
+
+#### `releaseSavepoint(name): Promise<void>`
+
+Release savepoint.
+
+### Vector (pgvector)
+
+#### `ensureVectorExtension(): Promise<void>`
+
+Install pgvector extension if not exists.
+
+#### `createVectorColumn(table, column, dimensions): Promise<void>`
+
+Add vector column to table.
+
+#### `createVectorIndex(table, column, indexType, operator, options?): Promise<void>`
+
+Create vector index for similarity search.
+
+**Parameters:**
+- `indexType`: 'hnsw' | 'ivfflat'
+- `operator`: '<->' | '<=>' | '<#>' | '<+>'
+- `options.m`: HNSW max connections (default: 16)
+- `options.efConstruction`: HNSW build quality (default: 64)
+- `options.lists`: IVFFlat lists (default: 100)
+
+#### `vectorSearch<T>(table, column, queryVector, options?): Promise<QueryResult<T & { distance }>>`
+
+Search for similar vectors.
+
+**Options:**
+- `operator`: Distance operator (default: '<->')
+- `limit`: Max results (default: 10)
+- `threshold`: Max distance threshold
+- `filter`: Additional WHERE clause
+- `filterParams`: Filter parameters
+
+#### `insertWithVector(table, data, vectorColumn, vector): Promise<QueryResult>`
+
+Insert row with vector.
+
+#### `updateVector(table, idColumn, idValue, vectorColumn, vector): Promise<QueryResult>`
+
+Update vector for existing row.
+
+#### `batchInsertWithVectors(table, columns, vectorColumn, rows): Promise<QueryResult>`
+
+Batch insert rows with vectors.
+
+**Parameters:**
+- `rows`: Array of `{ data: unknown[], vector: Vector }`
+
+#### Vector Utilities
+
+- `formatVector(vector): string` - Format for PostgreSQL
+- `parseVector(value): number[] | null` - Parse from PostgreSQL
+- `vectorDimension(vector): number` - Get dimension count
+- `normalizeVector(vector): number[]` - Normalize to unit length
+- `getDistanceOperator(op): string` - Get operator SQL
+- `getDistanceOperatorName(op): string` - Get human-readable name
+
+### Health Checks
+
+#### `healthCheck(logger?): Promise<HealthCheckResult>`
+
+Simple connectivity check.
+
+#### `healthCheckWithPool(pool, logger?): Promise<HealthCheckResult>`
+
+Health check with pool statistics.
+
+#### `deepHealthCheck(logger?): Promise<HealthCheckResult>`
+
+Deep check verifying read/write capability.
+
+#### `getVersion(): Promise<string>`
+
+Get PostgreSQL version.
+
+#### `isInRecovery(): Promise<boolean>`
+
+Check if database is in recovery mode (replica).
+
+#### `getDatabaseSize(dbName?): Promise<string>`
+
+Get database size (human-readable).
+
+#### `getConnectionCount(): Promise<{ active, idle, total, maxConnections }>`
+
+Get connection statistics.
+
+#### `createHealthHandler(pool?): (req: Request) => Promise<Response>`
+
+Create HTTP health check handler for Bun.serve.
+
+**Endpoints:**
+- `/health`, `/healthz` - Simple health check
+- `/ready`, `/readyz` - Deep health check
+
+**Example:**
+```typescript
+import { createPool, createHealthHandler } from '@singulio/postgres';
+
+const pool = await createPool({ connectionString: process.env.DATABASE_URL });
+const healthHandler = createHealthHandler(pool);
+
+Bun.serve({
+  port: 3000,
+  fetch: healthHandler,
+});
+```
+
+## Configuration
+
+### PostgresConfig
+
+```typescript
+interface PostgresConfig {
+  connectionString?: string;        // Full connection URL
+  host?: string;                    // Default: 'localhost'
+  port?: number;                    // Default: 5432
+  database?: string;                // Default: 'postgres'
+  user?: string;                    // Default: 'postgres'
+  password?: string;                // Default: ''
+  ssl?: boolean | 'require' | 'prefer' | 'disable';
+  applicationName?: string;         // For pg_stat_activity
+}
+```
+
+### PoolConfig
+
+Extends `PostgresConfig` with:
+
+```typescript
+interface PoolConfig extends PostgresConfig {
+  min?: number;              // Minimum connections (default: 2)
+  max?: number;              // Maximum connections (default: 20)
+  idleTimeout?: number;      // Idle timeout ms (default: 30000)
+  connectionTimeout?: number; // Acquire timeout ms (default: 10000)
+  maxLifetime?: number;      // Max lifetime ms (default: 3600000)
+}
+```
+
+### RLSContext
+
+```typescript
+interface RLSContext {
+  tenantId: string;                    // Required tenant ID
+  userId?: string;                     // Optional user ID
+  isAdmin?: boolean;                   // Admin bypass flag
+  extraGUCs?: Record<string, string>;  // Additional session vars
+}
+```
+
+### Environment Variables
+
+```bash
+# Connection string format
+DATABASE_URL="postgres://user:password@localhost:5432/mydb"
+
+# Or individual components
+PGHOST="localhost"
+PGPORT="5432"
+PGDATABASE="mydb"
+PGUSER="postgres"
+PGPASSWORD="secret"
+PGSSLMODE="require"
+```
+
+## Cross-Platform Compatibility
+
+### Runtime Requirements
+
+- **Node.js**: >= 18.0.0
+- **Bun**: >= 1.0.0 (recommended for best performance)
+
+### Operating Systems
+
+- **Linux** (x64, arm64, arm, ia32)
+- **macOS** (x64, arm64)
+- **Windows** (x64, ia32, arm64)
+
+### PostgreSQL Versions
+
+- **PostgreSQL 18.x** (recommended)
+- PostgreSQL 16+ (with pgvector 0.5.0+ for vector features)
+
+### Architecture Support
+
+- **x64** (x86_64, amd64)
+- **arm64** (aarch64, Apple Silicon)
+- **ia32** (x86)
+- **arm** (armv7)
+
+### Best Practices
+
+1. **Use Bun Runtime**: This package is optimized for Bun's native PostgreSQL driver
+2. **Connection Pooling**: Always use pools in production for concurrent workloads
+3. **RLS Setup**: Enable RLS on tables before using RLS helpers:
+   ```sql
+   ALTER TABLE contacts ENABLE ROW LEVEL SECURITY;
+   CREATE POLICY tenant_isolation ON contacts
+     USING (tenant_ref = current_setting('app.tenant_ref')::uuid);
+   ```
+4. **Vector Indexes**: Create appropriate indexes based on your distance metric:
+   - HNSW for better recall and speed (recommended)
+   - IVFFlat for larger datasets with memory constraints
+5. **Health Checks**: Implement both `/health` (liveness) and `/ready` (readiness) endpoints
+6. **Error Handling**: Always wrap database operations in try-catch blocks
+7. **Parameterized Queries**: Never interpolate user input directly into SQL
+
+## Performance Tips
+
+1. **Connection Pooling**: Configure pool size based on CPU cores (typically 2-4x core count)
+2. **Vector Indexes**: Tune HNSW `m` and `efConstruction` parameters for your dataset
+3. **Batch Operations**: Use `batchInsertWithVectors` for bulk inserts
+4. **Read Replicas**: Use `readOnlyTransaction` for analytics on replicas
+5. **Transaction Isolation**: Use lowest isolation level that meets your consistency needs
+6. **Connection Lifetime**: Set `maxLifetime` to handle PostgreSQL connection limits
+
+## Examples
+
+### Multi-Tenant SaaS Application
+
+```typescript
+import { createPool, createRLSClient, transaction } from '@singulio/postgres';
+
+const pool = await createPool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+  applicationName: 'saas-api',
+});
+
+const rlsClient = createRLSClient();
+
+// API endpoint
+async function getContacts(tenantId: string, userId: string) {
+  return await rlsClient.queryAll(
+    { tenantId, userId },
+    'SELECT * FROM contacts ORDER BY created_at DESC'
+  );
+}
+
+// Create contact with audit log
+async function createContact(tenantId: string, userId: string, data: any) {
+  return await transaction(
+    async (tx) => {
+      const contact = await tx.queryOne(
+        'INSERT INTO contacts (name, email) VALUES ($1, $2) RETURNING *',
+        [data.name, data.email]
+      );
+
+      await tx.execute(
+        'INSERT INTO audit_logs (action, entity_id, user_id) VALUES ($1, $2, $3)',
+        ['contact.created', contact.id, userId]
+      );
+
+      return contact;
+    },
+    { rlsContext: { tenantId, userId } }
+  );
+}
+```
+
+### AI-Powered Document Search
+
+```typescript
+import { createClient, vectorSearch, insertWithVector } from '@singulio/postgres';
+import { embed } from './embeddings'; // Your embedding function
+
+const client = createClient(process.env.DATABASE_URL);
+
+// Index document
+async function indexDocument(title: string, content: string) {
+  const embedding = await embed(content);
+  return await insertWithVector(
+    'documents',
+    { title, content, indexed_at: new Date() },
+    'embedding',
+    embedding
+  );
+}
+
+// Semantic search
+async function searchDocuments(query: string, limit = 10) {
+  const queryEmbedding = await embed(query);
+
+  const results = await vectorSearch('documents', 'embedding', queryEmbedding, {
+    operator: '<=>',  // Cosine similarity
+    limit,
+    filter: 'published = true',
+  });
+
+  return results.rows.map(doc => ({
+    title: doc.title,
+    content: doc.content,
+    similarity: 1 - doc.distance, // Convert distance to similarity
+  }));
+}
+```
+
+### Kubernetes Health Checks
+
+```typescript
+import { createPool, createHealthHandler } from '@singulio/postgres';
+
+const pool = await createPool({
+  connectionString: process.env.DATABASE_URL,
+  min: 2,
+  max: 10,
+});
+
+const healthHandler = createHealthHandler(pool);
+
+Bun.serve({
+  port: 3000,
+  async fetch(req) {
+    // Health checks
+    const response = await healthHandler(req);
+    if (response.status !== 404) return response;
+
+    // Your application routes
+    return new Response('Not Found', { status: 404 });
+  },
+});
+```
+
+## Testing
+
+### Unit Tests
+
+```typescript
+import { createClient, transaction } from '@singulio/postgres';
+import { describe, it, expect, beforeAll, afterAll } from 'bun:test';
+
+describe('Database Operations', () => {
+  let client;
+
+  beforeAll(async () => {
+    client = createClient(process.env.TEST_DATABASE_URL);
+  });
+
+  afterAll(async () => {
+    await client.close();
+  });
+
+  it('should insert and retrieve user', async () => {
+    const user = await client.queryOne(
+      'INSERT INTO users (name) VALUES ($1) RETURNING *',
+      ['Test User']
+    );
+
+    expect(user.name).toBe('Test User');
+  });
+
+  it('should rollback on error', async () => {
+    await expect(async () => {
+      await transaction(async (tx) => {
+        await tx.execute('INSERT INTO users (name) VALUES ($1)', ['User 1']);
+        throw new Error('Rollback test');
+      });
+    }).toThrow();
+
+    // Verify rollback
+    const count = await client.queryOne('SELECT COUNT(*) FROM users WHERE name = $1', ['User 1']);
+    expect(count.count).toBe(0);
+  });
+});
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+```typescript
+// Test basic connectivity
+const client = createClient(process.env.DATABASE_URL);
+const canConnect = await client.ping();
+console.log('Connected:', canConnect);
+
+// Check version
+const version = await client.version();
+console.log('PostgreSQL version:', version);
+```
+
+### Pool Exhaustion
+
+```typescript
+// Monitor pool statistics
+const stats = pool.stats();
+if (stats.pending > 5) {
+  console.warn('Pool under pressure:', stats);
+}
+
+// Increase pool size or investigate slow queries
+```
+
+### RLS Not Working
+
+```sql
+-- Verify RLS is enabled
+SELECT tablename, rowsecurity
+FROM pg_tables
+WHERE schemaname = 'public';
+
+-- Check policies
+SELECT * FROM pg_policies WHERE tablename = 'your_table';
+
+-- Test current settings
+SELECT current_setting('app.tenant_ref', true);
+```
+
+### Vector Search Performance
+
+```sql
+-- Check index usage
+EXPLAIN ANALYZE
+SELECT * FROM documents
+ORDER BY embedding <=> '[...]'
+LIMIT 10;
+
+-- Should show "Index Scan using idx_documents_embedding_hnsw"
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or pull request.
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/singuliodev/postgres/issues
+- Documentation: https://github.com/singuliodev/postgres#readme
+
+## Related Packages
+
+- `@singulio/logger` - Structured logging (compatible Logger interface)
+- `@singulio/types` - Shared TypeScript types
+- `@singulio/validation` - Request/response validation
+
+---
+
+Built with Bun for maximum performance. Powered by PostgreSQL 18.