@gl-life/gl-life-database 1.0.0

package/API.md

@@ -0,0 +1,1486 @@
+# @gl-life/gl-life-database API Reference
+
+**Version**: 1.0.0
+**Package**: `@gl-life/gl-life-database`
+**License**: Apache-2.0
+**Homepage**: https://gl.life
+
+## Table of Contents
+
+- [Core Types](#core-types)
+- [Connection Management](#connection-management)
+- [Query Builder](#query-builder)
+- [Transactions](#transactions)
+- [Multi-Tenancy](#multi-tenancy)
+- [Caching](#caching)
+- [Migrations](#migrations)
+- [CloudForge Adapters](#cloudforge-adapters)
+- [Error Handling](#error-handling)
+- [Usage Patterns](#usage-patterns)
+
+---
+
+## Core Types
+
+### Result<T, E>
+
+Functional error handling type from `@gl-life/gl-life-core`.
+
+```typescript
+type Result<T, E> = {
+  isOk(): boolean;
+  isErr(): boolean;
+  unwrap(): T;
+  unwrapErr(): E;
+  unwrapOr(defaultValue: T): T;
+  map<U>(fn: (value: T) => U): Result<U, E>;
+  mapErr<F>(fn: (error: E) => F): Result<T, F>;
+};
+```
+
+**Usage**:
+```typescript
+const result: Result<User[], DatabaseError> = await queryUsers();
+if (result.isOk()) {
+  const users = result.unwrap();
+} else {
+  const error = result.unwrapErr();
+}
+```
+
+### Option<T>
+
+Optional value type from `@gl-life/gl-life-core`.
+
+```typescript
+type Option<T> = {
+  isSome(): boolean;
+  isNone(): boolean;
+  unwrap(): T;
+  unwrapOr(defaultValue: T): T;
+  map<U>(fn: (value: T) => U): Option<U>;
+};
+```
+
+---
+
+## Connection Management
+
+### ConnectionManager
+
+Manages database connections with pooling support.
+
+#### Constructor
+
+```typescript
+class ConnectionManager {
+  constructor(logger: Logger);
+}
+```
+
+**Parameters**:
+- `logger: Logger` - Logger instance from `@gl-life/gl-life-core`
+
+#### Methods
+
+##### connect()
+
+```typescript
+connect(config: DatabaseConfig): Promise<Result<DatabaseConnection, ConnectionError>>
+```
+
+**Parameters**:
+```typescript
+interface DatabaseConfig {
+  type: 'sqlite' | 'postgres' | 'mysql' | 'd1';
+  filename?: string;        // SQLite only
+  host?: string;            // Network databases
+  port?: number;            // Network databases
+  database?: string;        // Network databases
+  username?: string;        // Network databases
+  password?: string;        // Network databases
+  poolSize?: number;        // Connection pool size (default: 10)
+  timeout?: number;         // Connection timeout in ms (default: 30000)
+}
+```
+
+**Returns**: `Result<DatabaseConnection, ConnectionError>`
+
+**Example**:
+```typescript
+const manager = new ConnectionManager(logger);
+const result = await manager.connect({
+  type: 'sqlite',
+  filename: './database.db'
+});
+
+if (result.isOk()) {
+  const connection = result.unwrap();
+}
+```
+
+##### disconnect()
+
+```typescript
+disconnect(): Promise<Result<void, ConnectionError>>
+```
+
+Closes all connections in the pool.
+
+##### getConnection()
+
+```typescript
+getConnection(): Result<DatabaseConnection, ConnectionError>
+```
+
+Returns an available connection from the pool.
+
+---
+
+## Query Builder
+
+### TypeSafeQueryBuilder
+
+Fluent API for building type-safe SQL queries.
+
+#### Constructor
+
+```typescript
+class TypeSafeQueryBuilder<T = any> {
+  constructor(
+    tableName: string,
+    metaDataService: MetaDataService | null,
+    logger: Logger
+  );
+}
+```
+
+**Parameters**:
+- `tableName: string` - Target table name
+- `metaDataService: MetaDataService | null` - Optional metadata service for schema validation
+- `logger: Logger` - Logger instance
+
+#### Methods
+
+##### select()
+
+```typescript
+select(columns: string[]): TypeSafeQueryBuilder<T>
+```
+
+Specify columns to SELECT.
+
+**Example**:
+```typescript
+builder.select(['id', 'name', 'email'])
+```
+
+##### where()
+
+```typescript
+where(
+  field: string,
+  operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN',
+  value: any
+): TypeSafeQueryBuilder<T>
+```
+
+Add WHERE condition.
+
+**Example**:
+```typescript
+builder.where('status', '=', 'active')
+      .where('age', '>', 18)
+```
+
+##### orWhere()
+
+```typescript
+orWhere(
+  field: string,
+  operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN',
+  value: any
+): TypeSafeQueryBuilder<T>
+```
+
+Add OR WHERE condition.
+
+##### whereIn()
+
+```typescript
+whereIn(field: string, values: any[]): TypeSafeQueryBuilder<T>
+```
+
+Add WHERE IN condition.
+
+**Example**:
+```typescript
+builder.whereIn('status', ['active', 'pending', 'verified'])
+```
+
+##### join()
+
+```typescript
+join(
+  table: string,
+  leftColumn: string,
+  operator: '=' | '!=' | '>' | '<',
+  rightColumn: string,
+  joinType?: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL'
+): TypeSafeQueryBuilder<T>
+```
+
+Add JOIN clause.
+
+**Example**:
+```typescript
+builder.join('posts', 'posts.user_id', '=', 'users.id')
+```
+
+##### orderBy()
+
+```typescript
+orderBy(column: string, direction: 'ASC' | 'DESC'): TypeSafeQueryBuilder<T>
+```
+
+Add ORDER BY clause.
+
+##### groupBy()
+
+```typescript
+groupBy(column: string): TypeSafeQueryBuilder<T>
+```
+
+Add GROUP BY clause.
+
+##### having()
+
+```typescript
+having(condition: string): TypeSafeQueryBuilder<T>
+```
+
+Add HAVING clause.
+
+**Example**:
+```typescript
+builder.groupBy('customer_id')
+      .having('COUNT(*) > 5')
+```
+
+##### limit()
+
+```typescript
+limit(count: number): TypeSafeQueryBuilder<T>
+```
+
+Add LIMIT clause.
+
+##### offset()
+
+```typescript
+offset(count: number): TypeSafeQueryBuilder<T>
+```
+
+Add OFFSET clause.
+
+##### toSQL()
+
+```typescript
+toSQL(): string
+```
+
+Generate SQL string with parameterized placeholders.
+
+**Returns**: SQL string with `?` placeholders
+
+**Example**:
+```typescript
+const sql = builder
+  .select(['id', 'name'])
+  .where('status', '=', 'active')
+  .toSQL();
+// Returns: "SELECT id, name FROM users WHERE status = ?"
+```
+
+---
+
+## Transactions
+
+### TransactionManager
+
+Handles database transactions with isolation levels.
+
+#### Constructor
+
+```typescript
+class TransactionManager {
+  constructor(
+    connection: DatabaseConnection,
+    config: TransactionConfig,
+    logger: Logger
+  );
+}
+```
+
+**Parameters**:
+```typescript
+interface TransactionConfig {
+  isolationLevel: 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE_READ' | 'SERIALIZABLE';
+  timeout: number;           // Transaction timeout in ms
+  retryAttempts: number;     // Number of retry attempts on conflict
+}
+```
+
+#### Methods
+
+##### execute()
+
+```typescript
+execute<T>(
+  callback: (tx: DatabaseTransaction) => Promise<T>
+): Promise<Result<T, TransactionError>>
+```
+
+Execute operations within a transaction.
+
+**Example**:
+```typescript
+const result = await txManager.execute(async (tx) => {
+  await tx.execute('INSERT INTO accounts (balance) VALUES (?)', [1000]);
+  await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, 1]);
+  await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, 2]);
+  return { success: true };
+});
+```
+
+### DatabaseTransaction
+
+Represents an active transaction.
+
+#### Methods
+
+##### execute()
+
+```typescript
+execute(sql: string, params?: any[]): Promise<Result<any, DatabaseError>>
+```
+
+Execute SQL within the transaction.
+
+##### commit()
+
+```typescript
+commit(): Promise<Result<void, TransactionError>>
+```
+
+Commit the transaction.
+
+##### rollback()
+
+```typescript
+rollback(): Promise<Result<void, TransactionError>>
+```
+
+Rollback the transaction.
+
+##### getState()
+
+```typescript
+getState(): 'PENDING' | 'ACTIVE' | 'COMMITTED' | 'ROLLED_BACK'
+```
+
+Get current transaction state.
+
+---
+
+## Multi-Tenancy
+
+### TenantContext
+
+Manages tenant context for multi-tenant applications.
+
+#### Constructor
+
+```typescript
+class TenantContext {
+  constructor(logger: Logger);
+}
+```
+
+#### Methods
+
+##### setTenant()
+
+```typescript
+setTenant(context: TenantContextData): void
+```
+
+Set the current tenant context.
+
+**Parameters**:
+```typescript
+interface TenantContextData {
+  tenantId: string;
+  isAdmin: boolean;
+  metadata?: Record<string, any>;
+}
+```
+
+**Example**:
+```typescript
+tenantContext.setTenant({
+  tenantId: 'tenant-123',
+  isAdmin: false
+});
+```
+
+##### getTenant()
+
+```typescript
+getTenant(): Option<TenantContextData>
+```
+
+Get the current tenant context.
+
+##### clearTenant()
+
+```typescript
+clearTenant(): void
+```
+
+Clear the tenant context.
+
+##### withTenant()
+
+```typescript
+withTenant<T>(
+  context: TenantContextData,
+  callback: () => Promise<T>
+): Promise<T>
+```
+
+Execute callback with temporary tenant context.
+
+**Example**:
+```typescript
+const result = await tenantContext.withTenant(
+  { tenantId: 'tenant-456', isAdmin: false },
+  async () => {
+    return await queryUsers();
+  }
+);
+```
+
+### QueryWrapper
+
+Wraps queries with automatic tenant filtering.
+
+#### Constructor
+
+```typescript
+class QueryWrapper {
+  constructor(
+    tenantContext: TenantContext,
+    logger: Logger
+  );
+}
+```
+
+#### Methods
+
+##### query()
+
+```typescript
+query<T>(
+  table: string,
+  options: QueryOptions,
+  config?: QueryConfig
+): Promise<Result<T[], DatabaseError>>
+```
+
+Execute query with automatic tenant filtering.
+
+**Parameters**:
+```typescript
+interface QueryOptions {
+  select?: string[];
+  where?: Record<string, any>;
+  orderBy?: { column: string; direction: 'ASC' | 'DESC' };
+  limit?: number;
+  offset?: number;
+}
+
+interface QueryConfig {
+  bypassTenantFilter?: boolean;  // Admin only
+}
+```
+
+**Example**:
+```typescript
+const result = await wrapper.query('products', {
+  where: { status: 'active' },
+  orderBy: { column: 'created_at', direction: 'DESC' },
+  limit: 10
+});
+// Automatically adds: WHERE tenant_id = ? AND status = ?
+```
+
+---
+
+## Caching
+
+### MemoryCache
+
+In-memory LRU cache for query results.
+
+#### Constructor
+
+```typescript
+class MemoryCache {
+  constructor(config: CacheConfig, logger: Logger);
+}
+```
+
+**Parameters**:
+```typescript
+interface CacheConfig {
+  enabled: boolean;
+  backend: 'MEMORY' | 'KV' | 'HYBRID';
+  maxItems?: number;                    // Max cache entries (default: 1000)
+  defaultTTL?: number;                  // Default TTL in seconds (default: 300)
+  evictionPolicy?: 'LRU' | 'LFU' | 'FIFO';
+  invalidationStrategy?: 'TIME_BASED' | 'EVENT_BASED' | 'HYBRID';
+  keyPrefix?: string;                   // Key prefix for namespacing
+}
+```
+
+#### Methods
+
+##### get()
+
+```typescript
+get<T>(key: string): Promise<Option<T>>
+```
+
+Get value from cache.
+
+**Example**:
+```typescript
+const result = await cache.get<User>('user:123');
+if (result.isSome()) {
+  const user = result.unwrap();
+}
+```
+
+##### set()
+
+```typescript
+set<T>(key: string, value: T, ttl?: number): Promise<Result<void, CacheError>>
+```
+
+Set value in cache.
+
+**Example**:
+```typescript
+await cache.set('user:123', { id: 123, name: 'Alice' }, 60);
+```
+
+##### delete()
+
+```typescript
+delete(key: string): Promise<Result<void, CacheError>>
+```
+
+Delete key from cache.
+
+##### has()
+
+```typescript
+has(key: string): Promise<boolean>
+```
+
+Check if key exists in cache.
+
+##### clear()
+
+```typescript
+clear(): Promise<Result<void, CacheError>>
+```
+
+Clear all cache entries.
+
+##### invalidatePattern()
+
+```typescript
+invalidatePattern(pattern: string): Promise<Result<number, CacheError>>
+```
+
+Invalidate all keys matching pattern (supports wildcards).
+
+**Example**:
+```typescript
+await cache.invalidatePattern('user:*');
+```
+
+##### getStats()
+
+```typescript
+getStats(): CacheStats
+```
+
+Get cache statistics.
+
+**Returns**:
+```typescript
+interface CacheStats {
+  hits: number;
+  misses: number;
+  hitRate: number;
+  size: number;
+  evictions: number;
+}
+```
+
+### KVCache
+
+Cloudflare Workers KV-backed cache.
+
+#### Constructor
+
+```typescript
+class KVCache {
+  constructor(
+    kv: KVNamespace,
+    config: CacheConfig,
+    logger: Logger
+  );
+}
+```
+
+Methods are identical to `MemoryCache`.
+
+---
+
+## Migrations
+
+### MigrationPlanner
+
+Plans and validates database migrations.
+
+#### Constructor
+
+```typescript
+class MigrationPlanner {
+  constructor(config: MigrationConfig, logger: Logger);
+}
+```
+
+**Parameters**:
+```typescript
+interface MigrationConfig {
+  enabled: boolean;
+  migrationTable: string;      // Table to track migrations (default: 'migrations')
+  autoRun: boolean;            // Auto-run migrations on startup (default: false)
+  migrationPath?: string;      // Path to migration files
+}
+```
+
+#### Methods
+
+##### loadMigrations()
+
+```typescript
+loadMigrations(
+  migrations: Migration[]
+): Promise<Result<void, MigrationError>>
+```
+
+Load migrations from array.
+
+**Parameters**:
+```typescript
+interface Migration {
+  version: string;
+  name: string;
+  up: string;          // SQL to apply migration
+  down: string;        // SQL to rollback migration
+  dependencies?: string[];
+}
+```
+
+##### loadFromDirectory()
+
+```typescript
+loadFromDirectory(
+  path: string
+): Promise<Result<Migration[], MigrationError>>
+```
+
+Load migrations from directory.
+
+##### planMigration()
+
+```typescript
+planMigration(
+  targetVersion: string
+): Result<MigrationPlan, MigrationError>
+```
+
+Plan migration to target version.
+
+**Returns**:
+```typescript
+interface MigrationPlan {
+  migrations: Migration[];
+  totalSteps: number;
+  estimatedDuration: number;
+  warnings: string[];
+}
+```
+
+##### checkStatus()
+
+```typescript
+checkStatus(): Promise<Result<MigrationStatus, MigrationError>>
+```
+
+Check migration status.
+
+**Returns**:
+```typescript
+interface MigrationStatus {
+  currentVersion: string;
+  appliedMigrations: string[];
+  pendingMigrations: string[];
+  lastMigrationDate: Date;
+}
+```
+
+### MigrationExecutor
+
+Executes migration plans.
+
+#### Constructor
+
+```typescript
+class MigrationExecutor {
+  constructor(
+    connection: DatabaseConnection,
+    logger: Logger
+  );
+}
+```
+
+#### Methods
+
+##### executeMigration()
+
+```typescript
+executeMigration(
+  plan: MigrationPlan
+): Promise<Result<MigrationResult, MigrationError>>
+```
+
+Execute migration plan.
+
+**Returns**:
+```typescript
+interface MigrationResult {
+  appliedMigrations: string[];
+  duration: number;
+  success: boolean;
+}
+```
+
+##### rollback()
+
+```typescript
+rollback(steps?: number): Promise<Result<void, MigrationError>>
+```
+
+Rollback migrations.
+
+**Parameters**:
+- `steps?: number` - Number of steps to rollback (default: 1)
+
+---
+
+## CloudForge Adapters
+
+### D1Adapter
+
+Cloudflare D1 database adapter.
+
+#### Constructor
+
+```typescript
+class D1Adapter {
+  constructor(d1: D1Database, logger: Logger);
+}
+```
+
+**Parameters**:
+- `d1: D1Database` - Cloudflare D1 database binding
+- `logger: Logger` - Logger instance
+
+#### Methods
+
+##### execute()
+
+```typescript
+execute(
+  sql: string,
+  params?: any[]
+): Promise<Result<D1Result, DatabaseError>>
+```
+
+Execute SQL query.
+
+**Example**:
+```typescript
+// In Cloudflare Worker
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const adapter = new D1Adapter(env.DB, logger);
+    const result = await adapter.execute(
+      'SELECT * FROM users WHERE id = ?',
+      [123]
+    );
+    return new Response(JSON.stringify(result));
+  }
+};
+```
+
+##### batch()
+
+```typescript
+batch(
+  statements: { sql: string; params?: any[] }[]
+): Promise<Result<D1Result[], DatabaseError>>
+```
+
+Execute batch of statements.
+
+### DurableObjectStorage
+
+Durable Objects storage adapter.
+
+#### Constructor
+
+```typescript
+class DurableObjectStorage {
+  constructor(
+    storage: DurableObjectStorage,
+    logger: Logger
+  );
+}
+```
+
+#### Methods
+
+##### get()
+
+```typescript
+get<T>(key: string): Promise<Option<T>>
+```
+
+Get value from Durable Object storage.
+
+##### put()
+
+```typescript
+put<T>(key: string, value: T): Promise<Result<void, StorageError>>
+```
+
+Store value in Durable Object storage.
+
+##### delete()
+
+```typescript
+delete(key: string): Promise<Result<void, StorageError>>
+```
+
+Delete key from storage.
+
+##### list()
+
+```typescript
+list(options?: ListOptions): Promise<Result<Map<string, any>, StorageError>>
+```
+
+List keys in storage.
+
+**Parameters**:
+```typescript
+interface ListOptions {
+  start?: string;
+  end?: string;
+  prefix?: string;
+  limit?: number;
+  reverse?: boolean;
+}
+```
+
+---
+
+## Error Handling
+
+All methods return `Result<T, E>` types for functional error handling.
+
+### Error Types
+
+#### DatabaseError
+
+```typescript
+class DatabaseError extends Error {
+  code: string;
+  query?: string;
+  params?: any[];
+  constructor(message: string, code: string, query?: string, params?: any[]);
+}
+```
+
+**Error Codes**:
+- `DB_CONNECTION_FAILED` - Connection failure
+- `DB_QUERY_FAILED` - Query execution failed
+- `DB_CONSTRAINT_VIOLATION` - Constraint violation
+- `DB_TIMEOUT` - Query timeout
+- `DB_PERMISSION_DENIED` - Permission denied
+
+#### TransactionError
+
+```typescript
+class TransactionError extends Error {
+  code: string;
+  transactionId?: string;
+  constructor(message: string, code: string, transactionId?: string);
+}
+```
+
+**Error Codes**:
+- `TX_ALREADY_STARTED` - Transaction already active
+- `TX_NOT_ACTIVE` - Transaction not active
+- `TX_COMMIT_FAILED` - Commit failed
+- `TX_ROLLBACK_FAILED` - Rollback failed
+- `TX_TIMEOUT` - Transaction timeout
+
+#### CacheError
+
+```typescript
+class CacheError extends Error {
+  code: string;
+  key?: string;
+  constructor(message: string, code: string, key?: string);
+}
+```
+
+**Error Codes**:
+- `CACHE_GET_FAILED` - Get operation failed
+- `CACHE_SET_FAILED` - Set operation failed
+- `CACHE_DELETE_FAILED` - Delete operation failed
+- `CACHE_FULL` - Cache is full
+
+#### MigrationError
+
+```typescript
+class MigrationError extends Error {
+  code: string;
+  migration?: string;
+  constructor(message: string, code: string, migration?: string);
+}
+```
+
+**Error Codes**:
+- `MIGRATION_LOAD_FAILED` - Failed to load migrations
+- `MIGRATION_EXECUTE_FAILED` - Migration execution failed
+- `MIGRATION_ROLLBACK_FAILED` - Rollback failed
+- `MIGRATION_VERSION_CONFLICT` - Version conflict
+
+---
+
+## Usage Patterns
+
+### Pattern 1: Basic Query with Error Handling
+
+```typescript
+import {
+  ConnectionManager,
+  TypeSafeQueryBuilder,
+  Logger,
+  Result,
+  DatabaseError
+} from '@gl-life/gl-life-database';
+
+const logger = new Logger({ level: 'info' });
+const manager = new ConnectionManager(logger);
+
+const connResult = await manager.connect({
+  type: 'sqlite',
+  filename: './app.db'
+});
+
+if (connResult.isErr()) {
+  console.error('Connection failed:', connResult.unwrapErr());
+  process.exit(1);
+}
+
+const connection = connResult.unwrap();
+const builder = new TypeSafeQueryBuilder('users', null, logger);
+const sql = builder.select(['*']).where('active', '=', true).toSQL();
+
+const queryResult = await connection.execute(sql, [true]);
+if (queryResult.isOk()) {
+  const users = queryResult.unwrap();
+  console.log('Users:', users);
+}
+```
+
+### Pattern 2: Multi-Tenant Query
+
+```typescript
+import {
+  TenantContext,
+  QueryWrapper,
+  Logger
+} from '@gl-life/gl-life-database';
+
+const logger = new Logger({ level: 'info' });
+const tenantContext = new TenantContext(logger);
+const wrapper = new QueryWrapper(tenantContext, logger);
+
+// Set tenant from request
+const tenantId = request.headers.get('X-Tenant-ID');
+tenantContext.setTenant({
+  tenantId,
+  isAdmin: false
+});
+
+// Query automatically includes tenant filter
+const result = await wrapper.query('products', {
+  where: { status: 'active' },
+  limit: 20
+});
+// SQL: WHERE tenant_id = ? AND status = ? LIMIT 20
+```
+
+### Pattern 3: Transaction with Retry
+
+```typescript
+import {
+  TransactionManager,
+  Logger
+} from '@gl-life/gl-life-database';
+
+const config = {
+  isolationLevel: 'READ_COMMITTED' as const,
+  timeout: 30000,
+  retryAttempts: 3
+};
+
+const txManager = new TransactionManager(connection, config, logger);
+
+const result = await txManager.execute(async (tx) => {
+  // Transfer money between accounts
+  const debit = await tx.execute(
+    'UPDATE accounts SET balance = balance - ? WHERE id = ?',
+    [amount, fromAccountId]
+  );
+
+  if (debit.isErr()) throw debit.unwrapErr();
+
+  const credit = await tx.execute(
+    'UPDATE accounts SET balance = balance + ? WHERE id = ?',
+    [amount, toAccountId]
+  );
+
+  if (credit.isErr()) throw credit.unwrapErr();
+
+  return { transferred: amount };
+});
+```
+
+### Pattern 4: Cached Query
+
+```typescript
+import {
+  MemoryCache,
+  Logger,
+  CacheConfig
+} from '@gl-life/gl-life-database';
+
+const cacheConfig: CacheConfig = {
+  enabled: true,
+  backend: 'MEMORY',
+  maxItems: 1000,
+  defaultTTL: 300,
+  evictionPolicy: 'LRU',
+  invalidationStrategy: 'TIME_BASED',
+  keyPrefix: 'app:'
+};
+
+const cache = new MemoryCache(cacheConfig, logger);
+
+async function getUser(id: number) {
+  const cacheKey = `user:${id}`;
+
+  // Try cache first
+  const cached = await cache.get<User>(cacheKey);
+  if (cached.isSome()) {
+    return cached.unwrap();
+  }
+
+  // Query database
+  const result = await queryUser(id);
+  if (result.isOk()) {
+    const user = result.unwrap();
+    await cache.set(cacheKey, user, 60);
+    return user;
+  }
+
+  throw result.unwrapErr();
+}
+
+// Invalidate on update
+async function updateUser(id: number, data: Partial<User>) {
+  const result = await executeUpdate(id, data);
+  if (result.isOk()) {
+    await cache.delete(`user:${id}`);
+  }
+  return result;
+}
+```
+
+### Pattern 5: Database Migration
+
+```typescript
+import {
+  MigrationPlanner,
+  MigrationExecutor,
+  Logger,
+  MigrationConfig
+} from '@gl-life/gl-life-database';
+
+const config: MigrationConfig = {
+  enabled: true,
+  migrationTable: 'migrations',
+  autoRun: false
+};
+
+const logger = new Logger({ level: 'info' });
+const planner = new MigrationPlanner(config, logger);
+const executor = new MigrationExecutor(connection, logger);
+
+// Load migrations
+const migrations = [
+  {
+    version: '001',
+    name: 'create_users',
+    up: 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)',
+    down: 'DROP TABLE users'
+  },
+  {
+    version: '002',
+    name: 'add_users_email',
+    up: 'ALTER TABLE users ADD COLUMN email TEXT',
+    down: 'ALTER TABLE users DROP COLUMN email',
+    dependencies: ['001']
+  }
+];
+
+await planner.loadMigrations(migrations);
+
+// Check status
+const status = await planner.checkStatus();
+if (status.isOk()) {
+  console.log('Current version:', status.unwrap().currentVersion);
+  console.log('Pending:', status.unwrap().pendingMigrations);
+}
+
+// Plan and execute
+const plan = planner.planMigration('002');
+if (plan.isOk()) {
+  const result = await executor.executeMigration(plan.unwrap());
+  console.log('Migration result:', result);
+}
+```
+
+### Pattern 6: Cloudflare D1 Worker
+
+```typescript
+import {
+  D1Adapter,
+  Logger,
+  MemoryCache,
+  CacheConfig
+} from '@gl-life/gl-life-database';
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const logger = new Logger({ level: 'info' });
+    const db = new D1Adapter(env.DB, logger);
+
+    // Set up cache
+    const cacheConfig: CacheConfig = {
+      enabled: true,
+      backend: 'MEMORY',
+      maxItems: 100,
+      defaultTTL: 60,
+      evictionPolicy: 'LRU',
+      invalidationStrategy: 'TIME_BASED'
+    };
+    const cache = new MemoryCache(cacheConfig, logger);
+
+    // Parse request
+    const url = new URL(request.url);
+    const userId = url.searchParams.get('id');
+
+    if (!userId) {
+      return new Response('Missing user ID', { status: 400 });
+    }
+
+    // Try cache
+    const cacheKey = `user:${userId}`;
+    const cached = await cache.get(cacheKey);
+
+    if (cached.isSome()) {
+      return new Response(JSON.stringify({
+        data: cached.unwrap(),
+        cached: true
+      }), {
+        headers: { 'Content-Type': 'application/json' }
+      });
+    }
+
+    // Query D1
+    const result = await db.execute(
+      'SELECT * FROM users WHERE id = ?',
+      [userId]
+    );
+
+    if (result.isErr()) {
+      return new Response(
+        JSON.stringify({ error: result.unwrapErr().message }),
+        { status: 500 }
+      );
+    }
+
+    const data = result.unwrap();
+    await cache.set(cacheKey, data, 60);
+
+    return new Response(JSON.stringify({
+      data,
+      cached: false
+    }), {
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+};
+```
+
+---
+
+## Type Definitions Summary
+
+### Connection Types
+
+```typescript
+type DatabaseType = 'sqlite' | 'postgres' | 'mysql' | 'd1';
+
+interface DatabaseConfig {
+  type: DatabaseType;
+  filename?: string;
+  host?: string;
+  port?: number;
+  database?: string;
+  username?: string;
+  password?: string;
+  poolSize?: number;
+  timeout?: number;
+}
+
+interface DatabaseConnection {
+  execute(sql: string, params?: any[]): Promise<Result<any, DatabaseError>>;
+  close(): Promise<Result<void, ConnectionError>>;
+}
+```
+
+### Query Types
+
+```typescript
+type Operator = '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN';
+type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+type SortDirection = 'ASC' | 'DESC';
+
+interface WhereCondition {
+  field: string;
+  operator: Operator;
+  value: any;
+  connector: 'AND' | 'OR';
+}
+
+interface JoinClause {
+  table: string;
+  leftColumn: string;
+  operator: string;
+  rightColumn: string;
+  joinType: JoinType;
+}
+```
+
+### Transaction Types
+
+```typescript
+type IsolationLevel =
+  | 'READ_UNCOMMITTED'
+  | 'READ_COMMITTED'
+  | 'REPEATABLE_READ'
+  | 'SERIALIZABLE';
+
+type TransactionState =
+  | 'PENDING'
+  | 'ACTIVE'
+  | 'COMMITTED'
+  | 'ROLLED_BACK';
+
+interface TransactionConfig {
+  isolationLevel: IsolationLevel;
+  timeout: number;
+  retryAttempts: number;
+}
+```
+
+### Cache Types
+
+```typescript
+type CacheBackend = 'MEMORY' | 'KV' | 'HYBRID';
+type EvictionPolicy = 'LRU' | 'LFU' | 'FIFO';
+type InvalidationStrategy = 'TIME_BASED' | 'EVENT_BASED' | 'HYBRID';
+
+interface CacheConfig {
+  enabled: boolean;
+  backend: CacheBackend;
+  maxItems?: number;
+  defaultTTL?: number;
+  evictionPolicy?: EvictionPolicy;
+  invalidationStrategy?: InvalidationStrategy;
+  keyPrefix?: string;
+}
+
+interface CacheStats {
+  hits: number;
+  misses: number;
+  hitRate: number;
+  size: number;
+  evictions: number;
+}
+```
+
+### Migration Types
+
+```typescript
+interface Migration {
+  version: string;
+  name: string;
+  up: string;
+  down: string;
+  dependencies?: string[];
+}
+
+interface MigrationConfig {
+  enabled: boolean;
+  migrationTable: string;
+  autoRun: boolean;
+  migrationPath?: string;
+}
+
+interface MigrationStatus {
+  currentVersion: string;
+  appliedMigrations: string[];
+  pendingMigrations: string[];
+  lastMigrationDate: Date;
+}
+
+interface MigrationPlan {
+  migrations: Migration[];
+  totalSteps: number;
+  estimatedDuration: number;
+  warnings: string[];
+}
+```
+
+### Tenant Types
+
+```typescript
+interface TenantContextData {
+  tenantId: string;
+  isAdmin: boolean;
+  metadata?: Record<string, any>;
+}
+
+interface QueryOptions {
+  select?: string[];
+  where?: Record<string, any>;
+  orderBy?: { column: string; direction: 'ASC' | 'DESC' };
+  limit?: number;
+  offset?: number;
+}
+
+interface QueryConfig {
+  bypassTenantFilter?: boolean;
+}
+```
+
+---
+
+## Performance Considerations
+
+### Query Builder
+
+- Query building overhead: **<1ms** (P95)
+- Supports parameterized queries to prevent SQL injection
+- Minimal memory footprint per query (~0.001 MB)
+
+### Cache
+
+- GET operation: **<1ms** (P95)
+- SET operation: **<1ms** (P95)
+- Pattern invalidation (100 keys): **<10ms** (P95)
+- LRU eviction prevents unbounded memory growth
+
+### Transactions
+
+- Automatic retry on conflict
+- Configurable isolation levels
+- Timeout protection
+
+---
+
+## Security Features
+
+- ✅ **SQL Injection Protection** - All queries use parameterized statements
+- ✅ **Tenant Isolation** - Automatic tenant_id filtering prevents data leaks
+- ✅ **Type Safety** - TypeScript compile-time + Zod runtime validation
+- ✅ **Audit Logging** - All operations logged for security auditing
+
+See [SECURITY.md](./SECURITY.md) for security audit results.
+
+---
+
+## Version Compatibility
+
+- **TypeScript**: 5.0+
+- **Node.js**: 18+
+- **Cloudflare Workers**: Compatible
+- **Deno**: Compatible (use npm: imports)
+
+---
+
+## Support
+
+For questions or issues:
+- Email: [packages@gl.life](mailto:packages@gl.life)
+- Website: [gl.life](https://gl.life)
+
+---
+
+**Part of the GoodLife Sargam ecosystem**