@gl-life/gl-life-database 1.0.0 → 1.1.1

package/API.md

@@ -1,6 +1,6 @@
 # @gl-life/gl-life-database API Reference
 
-**Version**: 1.0.0
+**Version**: 1.1.1
 **Package**: `@gl-life/gl-life-database`
 **License**: Apache-2.0
 **Homepage**: https://gl.life
@@ -9,11 +9,13 @@
 
 - [Core Types](#core-types)
 - [Connection Management](#connection-management)
+- [Enterprise Database Support](#enterprise-database-support)
 - [Query Builder](#query-builder)
 - [Transactions](#transactions)
 - [Multi-Tenancy](#multi-tenancy)
 - [Caching](#caching)
 - [Migrations](#migrations)
+- [Flex Table System](#flex-table-system)
 - [CloudForge Adapters](#cloudforge-adapters)
 - [Error Handling](#error-handling)
 - [Usage Patterns](#usage-patterns)
@@ -137,6 +139,205 @@ Returns an available connection from the pool.
 
 ---
 
+## Enterprise Database Support
+
+Full support for enterprise databases with bring-your-own-database (BYOD) deployments.
+
+### Supported Databases
+
+#### SQL Server (Microsoft)
+
+```typescript
+interface SQLServerConfig {
+  type: 'sqlserver';
+  host: string;
+  port?: number;              // Default: 1433
+  database: string;
+  username: string;
+  password: string;
+  options?: {
+    encrypt?: boolean;        // Required for Azure SQL
+    trustServerCertificate?: boolean;
+    connectionTimeout?: number;
+    requestTimeout?: number;
+    pool?: {
+      max?: number;
+      min?: number;
+      idleTimeoutMillis?: number;
+    };
+  };
+}
+```
+
+**Example**:
+```typescript
+const connection = await manager.connect({
+  type: 'sqlserver',
+  host: 'sql-server.database.windows.net',
+  port: 1433,
+  database: 'production',
+  username: 'admin',
+  password: process.env.DB_PASSWORD,
+  options: {
+    encrypt: true,
+    trustServerCertificate: false,
+    connectionTimeout: 30000,
+    pool: {
+      max: 20,
+      min: 5,
+      idleTimeoutMillis: 30000
+    }
+  }
+});
+```
+
+#### PostgreSQL
+
+```typescript
+interface PostgreSQLConfig {
+  type: 'postgres';
+  host: string;
+  port?: number;              // Default: 5432
+  database: string;
+  username: string;
+  password: string;
+  options?: {
+    ssl?: boolean | object;
+    poolSize?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+    schema?: string;
+  };
+}
+```
+
+**Example**:
+```typescript
+const connection = await manager.connect({
+  type: 'postgres',
+  host: 'postgres-cluster.company.com',
+  port: 5432,
+  database: 'production',
+  username: 'dbuser',
+  password: process.env.DB_PASSWORD,
+  options: {
+    ssl: { rejectUnauthorized: false },
+    poolSize: 20,
+    schema: 'public'
+  }
+});
+```
+
+#### MySQL / MariaDB
+
+```typescript
+interface MySQLConfig {
+  type: 'mysql';
+  host: string;
+  port?: number;              // Default: 3306
+  database: string;
+  username: string;
+  password: string;
+  options?: {
+    connectionLimit?: number;
+    charset?: string;
+    timezone?: string;
+    ssl?: boolean | object;
+  };
+}
+```
+
+**Example**:
+```typescript
+const connection = await manager.connect({
+  type: 'mysql',
+  host: 'mysql-primary.internal.com',
+  port: 3306,
+  database: 'production',
+  username: 'app_user',
+  password: process.env.DB_PASSWORD,
+  options: {
+    connectionLimit: 10,
+    charset: 'utf8mb4',
+    timezone: 'Z'
+  }
+});
+```
+
+#### Oracle Database
+
+```typescript
+interface OracleConfig {
+  type: 'oracle';
+  host: string;
+  port?: number;              // Default: 1521
+  database: string;           // Service name
+  username: string;
+  password: string;
+  options?: {
+    poolMax?: number;
+    poolMin?: number;
+    poolIncrement?: number;
+    poolTimeout?: number;
+  };
+}
+```
+
+**Example**:
+```typescript
+const connection = await manager.connect({
+  type: 'oracle',
+  host: 'oracle-db.company.com',
+  port: 1521,
+  database: 'ORCL',
+  username: 'system',
+  password: process.env.DB_PASSWORD,
+  options: {
+    poolMax: 10,
+    poolMin: 2,
+    poolIncrement: 1
+  }
+});
+```
+
+### Enterprise Features
+
+All features work identically across all database engines:
+
+- ✅ **Flex Table System** - Dynamic schemas work on any database
+- ✅ **Multi-Tenancy** - Row-Level Security on all engines
+- ✅ **Caching** - Cache layer independent of database type
+- ✅ **Migrations** - Version control for any database
+- ✅ **Transactions** - ACID compliance on all supported databases
+- ✅ **Connection Pooling** - Automatic connection management
+
+### Hybrid Deployments
+
+Mix cloud and on-premise databases in the same application:
+
+```typescript
+// Cloud database for non-sensitive data
+const cloudConn = await manager.connect({
+  type: 'd1',
+  binding: env.DB
+});
+
+// Enterprise database for sensitive data
+const enterpriseConn = await manager.connect({
+  type: 'sqlserver',
+  host: 'on-premise-sql.company.local',
+  database: 'customer_data',
+  username: 'app_user',
+  password: process.env.DB_PASSWORD
+});
+
+// Use both in same application
+const products = await cloudConn.execute('SELECT * FROM products');
+const customers = await enterpriseConn.execute('SELECT * FROM customers WHERE tenant_id = ?', [tenantId]);
+```
+
+---
+
 ## Query Builder
 
 ### TypeSafeQueryBuilder
@@ -805,6 +1006,254 @@ Rollback migrations.
 
 ---
 
+## Flex Table System
+
+The Flex Table System provides dynamic schema capabilities without ALTER TABLE operations. From `gl-life-data`.
+
+### MetaDataService
+
+Manages metadata mappings between logical and physical field names.
+
+#### Constructor
+
+```typescript
+class MetaDataService {
+  constructor(dbPath: string);
+}
+```
+
+**Parameters**:
+- `dbPath: string` - Path to SQLite database containing metadata
+
+#### Methods
+
+##### createMapping()
+
+```typescript
+createMapping(input: CreateMappingInput): Promise<MetadataSelect>
+```
+
+Creates a new metadata mapping, automatically assigning the next available physical field.
+
+**Parameters**:
+```typescript
+interface CreateMappingInput {
+  tableName: string;
+  logicalFieldName: string;
+  dataType: 'string' | 'int' | 'decimal' | 'date' | 'boolean' | 'text' | 'datetime' | 'float' | 'bigint' | 'uuid';
+  isRequired?: boolean;
+  defaultValue?: string | null;
+  validationRules?: ValidationRules;
+  description?: string;
+  displayOrder?: number;
+  isIndexed?: boolean;
+  isUnique?: boolean;
+  foreignKeyRef?: string | null;
+  createdBy?: string;
+}
+```
+
+**Returns**: `Promise<MetadataSelect>` - Created metadata entry
+
+**Example**:
+```typescript
+const metaDataService = new MetaDataService('./database.db');
+
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'productName',
+  dataType: 'string',        // Will map to string_field_1
+  isRequired: true,
+  description: 'Product name'
+});
+```
+
+##### getMappingByLogicalField()
+
+```typescript
+getMappingByLogicalField(tableName: string, logicalFieldName: string): MetadataSelect | null
+```
+
+**Parameters**:
+- `tableName: string` - Entity table name
+- `logicalFieldName: string` - Logical field name to look up
+
+**Returns**: `MetadataSelect | null` - Metadata entry or null if not found
+
+##### getTableMappings()
+
+```typescript
+getTableMappings(tableName: string): MetadataSelect[]
+```
+
+**Parameters**:
+- `tableName: string` - Entity table name
+
+**Returns**: `MetadataSelect[]` - All metadata mappings for the table
+
+### Using Flex Tables with TypeSafeQueryBuilder
+
+```typescript
+import { TypeSafeQueryBuilder, Logger } from '@gl-life/gl-life-database';
+import { MetaDataService } from 'gl-life-data';
+
+const logger = new Logger({ level: 'info' });
+const metaDataService = new MetaDataService('./database.db');
+
+// Create mappings
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'name',
+  dataType: 'string'           // Maps to string_field_1
+});
+
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'price',
+  dataType: 'decimal'          // Maps to decimal_field_1
+});
+
+// Query using logical field names
+const builder = new TypeSafeQueryBuilder('products', metaDataService, logger);
+const sql = builder
+  .select(['name', 'price'])   // Logical names
+  .where('price', '>', 100)
+  .toSQL();
+
+// Generates: SELECT string_field_1, decimal_field_1
+//            FROM flex_table
+//            WHERE decimal_field_1 > ?
+```
+
+### Flex Table Schema
+
+Universal schema for all Flex tables:
+
+```sql
+CREATE TABLE flex_table (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT,
+
+  -- String fields (10 slots)
+  string_field_1 TEXT,
+  string_field_2 TEXT,
+  string_field_3 TEXT,
+  ...
+  string_field_10 TEXT,
+
+  -- Integer fields (10 slots)
+  int_field_1 INTEGER,
+  int_field_2 INTEGER,
+  ...
+  int_field_10 INTEGER,
+
+  -- Decimal fields (10 slots)
+  decimal_field_1 REAL,
+  ...
+  decimal_field_10 REAL,
+
+  -- Date fields (10 slots)
+  date_field_1 TEXT,
+  ...
+  date_field_10 TEXT,
+
+  -- Boolean fields (10 slots)
+  boolean_field_1 INTEGER,
+  ...
+  boolean_field_10 INTEGER,
+
+  -- Text fields (10 slots)
+  text_field_1 TEXT,
+  ...
+  text_field_10 TEXT,
+
+  -- Additional field types (10 slots each):
+  -- datetime_field_1 through datetime_field_10
+  -- float_field_1 through float_field_10
+  -- bigint_field_1 through bigint_field_10
+  -- uuid_field_1 through uuid_field_10
+
+  -- Overflow for extra fields
+  json_data TEXT,
+
+  -- Timestamps
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### Metadata Table Schema
+
+```sql
+CREATE TABLE metadata (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT,                      -- NULL for shared, or specific tenant ID
+  table_name TEXT NOT NULL,
+  logical_field_name TEXT NOT NULL,
+  physical_column_name TEXT NOT NULL,
+  data_type TEXT NOT NULL,
+  is_required INTEGER NOT NULL DEFAULT 0,
+  default_value TEXT,
+  validation_rules TEXT,               -- JSON
+  description TEXT,
+  display_order INTEGER,
+  is_indexed INTEGER NOT NULL DEFAULT 0,
+  is_unique INTEGER NOT NULL DEFAULT 0,
+  foreign_key_ref TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by TEXT,
+  updated_by TEXT,
+  UNIQUE(tenant_id, table_name, logical_field_name),
+  UNIQUE(tenant_id, table_name, physical_column_name)
+);
+```
+
+### Flex Tables + Multi-Tenancy
+
+Combine Flex tables with multi-tenancy for per-tenant custom fields:
+
+```typescript
+// Shared field for all tenants
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'name',
+  dataType: 'string'
+});
+
+// Tenant-specific field (Tenant A only)
+await connection.execute(`
+  INSERT INTO metadata (
+    id, tenant_id, table_name, logical_field_name,
+    physical_column_name, data_type
+  ) VALUES (?, ?, ?, ?, ?, ?)
+`, [
+  'tenantA_products_warranty',
+  'tenant-A',
+  'products',
+  'warrantyMonths',
+  'int_field_1',               // Tenant A uses int_field_1
+  'int'
+]);
+
+// Tenant-specific field (Tenant B only)
+await connection.execute(`
+  INSERT INTO metadata (
+    id, tenant_id, table_name, logical_field_name,
+    physical_column_name, data_type
+  ) VALUES (?, ?, ?, ?, ?, ?)
+`, [
+  'tenantB_products_size',
+  'tenant-B',
+  'products',
+  'size',
+  'string_field_2',            // Tenant B uses string_field_2
+  'string'
+]);
+```
+
+---
+
 ## CloudForge Adapters
 
 ### D1Adapter

package/README.md

@@ -4,15 +4,17 @@ Enhanced gl-life-data wrapper with CloudForge features - Type-safe database abst
 
 ## About
 
-`@gl-life/gl-life-database` is a comprehensive database abstraction layer that extends gl-life-data with enterprise features for multi-tenant SaaS applications running on Cloudflare Workers. Built with TypeScript and designed for type safety, it provides a robust foundation for building scalable database-driven applications.
+`@gl-life/gl-life-database` is a comprehensive database abstraction layer that extends gl-life-data with enterprise features for multi-tenant SaaS applications. Built with TypeScript and designed for type safety, it supports both cloud-native deployments (Cloudflare Workers) and enterprise bring-your-own-database (BYOD) scenarios with SQL Server, MySQL, PostgreSQL, Oracle, and more. Perfect for pro users who want to leverage their existing infrastructure while gaining powerful features like Flex tables, multi-tenancy, and intelligent caching.
 
 ### Key Features
 
 - 🗄️ **Type-Safe Query Builder** - Fluent API with full TypeScript support extending gl-life-data
+- 🔀 **Flex Table System** - Dynamic schema without ALTER TABLE, metadata-driven field mapping
+- 🏢 **Enterprise Database Support** - Full support for SQL Server, MySQL, PostgreSQL, Oracle, and more
 - 👥 **Multi-Tenancy** - Built-in tenant isolation with Row-Level Security (RLS)
-- ⚡ **Caching Layer** - High-performance query result caching with memory and Cloudflare KV backends
+- ⚡ **Flexible Caching** - Memory cache, Redis, or Cloudflare KV backends
 - 🔄 **Migrations** - Version-controlled database migrations with rollback support
-- ☁️ **CloudForge Integration** - Native support for D1, Durable Objects, Workers KV, and R2
+- ☁️ **Cloud + On-Premise** - Deploy on Cloudflare Workers OR bring your own infrastructure
 - 🔒 **SQL Injection Protection** - Parameterized queries with automatic sanitization
 - 🧪 **Well-Tested** - >95% test coverage with comprehensive security tests
 - 📊 **Performance Optimized** - Query building overhead <1ms (P95)
@@ -180,6 +182,174 @@ export default {
 };
 ```
 
+### Enterprise Database Support (BYOD - Bring Your Own Database)
+
+Pro users can connect to their existing enterprise databases instead of using Cloudflare Workers. Full support for:
+
+#### SQL Server (Microsoft)
+
+```typescript
+import { ConnectionManager, Logger } from '@gl-life/gl-life-database';
+
+const logger = new Logger({ level: 'info' });
+const manager = new ConnectionManager(logger);
+
+const connection = await manager.connect({
+  type: 'sqlserver',
+  host: 'your-sql-server.database.windows.net',
+  port: 1433,
+  database: 'production_db',
+  username: 'admin',
+  password: process.env.DB_PASSWORD,
+  options: {
+    encrypt: true,                    // Azure SQL requires encryption
+    trustServerCertificate: false,
+    connectionTimeout: 30000
+  }
+});
+
+// All features work identically: Flex tables, multi-tenancy, caching, migrations
+const builder = new TypeSafeQueryBuilder('users', metaDataService, logger);
+// ... same as any other database
+```
+
+#### PostgreSQL
+
+```typescript
+const connection = await manager.connect({
+  type: 'postgres',
+  host: 'your-postgres-instance.com',
+  port: 5432,
+  database: 'production_db',
+  username: 'dbuser',
+  password: process.env.DB_PASSWORD,
+  options: {
+    ssl: { rejectUnauthorized: false },
+    poolSize: 20,
+    idleTimeoutMillis: 30000
+  }
+});
+```
+
+#### MySQL / MariaDB
+
+```typescript
+const connection = await manager.connect({
+  type: 'mysql',
+  host: 'mysql-cluster.internal.com',
+  port: 3306,
+  database: 'production_db',
+  username: 'dbuser',
+  password: process.env.DB_PASSWORD,
+  options: {
+    connectionLimit: 10,
+    charset: 'utf8mb4',
+    timezone: 'Z'
+  }
+});
+```
+
+#### Oracle Database
+
+```typescript
+const connection = await manager.connect({
+  type: 'oracle',
+  host: 'oracle-enterprise.company.com',
+  port: 1521,
+  database: 'ORCL',              // Service name
+  username: 'system',
+  password: process.env.DB_PASSWORD,
+  options: {
+    poolMax: 10,
+    poolMin: 2,
+    poolIncrement: 1
+  }
+});
+```
+
+#### SQLite (Development/Testing)
+
+```typescript
+const connection = await manager.connect({
+  type: 'sqlite',
+  filename: './dev.db'            // Or ':memory:' for in-memory
+});
+```
+
+**Key Benefits for Enterprise Users:**
+- ✅ **Use Existing Infrastructure** - No migration required, connect to your current databases
+- ✅ **All Features Work** - Flex tables, multi-tenancy, caching, migrations work on any database
+- ✅ **Security Compliant** - Keep data on-premise, meet regulatory requirements
+- ✅ **Cost Control** - Use your existing database licenses and hardware
+- ✅ **Hybrid Deployments** - Mix cloud (D1) and on-premise databases in same application
+- ✅ **Connection Pooling** - Built-in connection management for all enterprise databases
+
+### Flex Table System
+
+The Flex Table System is a powerful feature from gl-life-data that provides dynamic schema capabilities without ALTER TABLE operations. Perfect for multi-tenant SaaS applications where each tenant needs custom fields.
+
+```typescript
+import { TypeSafeQueryBuilder, Logger } from '@gl-life/gl-life-database';
+import { MetaDataService } from 'gl-life-data';
+
+// Initialize metadata service
+const metaDataService = new MetaDataService('./database.db');
+
+// Create metadata mapping: logical field → physical column
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'productName',
+  dataType: 'string',          // Maps to string_field_1
+  isRequired: true,
+  description: 'Product name'
+});
+
+await metaDataService.createMapping({
+  tableName: 'products',
+  logicalFieldName: 'price',
+  dataType: 'decimal',         // Maps to decimal_field_1
+  isRequired: true
+});
+
+// Query using logical field names
+const builder = new TypeSafeQueryBuilder('products', metaDataService, logger);
+const sql = builder
+  .select(['productName', 'price'])  // Uses logical names
+  .where('price', '>', 100)
+  .toSQL();
+// Generates: SELECT string_field_1, decimal_field_1 FROM flex_table WHERE decimal_field_1 > ?
+```
+
+**Key Benefits:**
+- **Universal Schema**: All tables use same physical structure (string_field_1, int_field_1, etc.)
+- **No ALTER TABLE**: Add fields by creating metadata entries
+- **Type Safety**: 10 fields per data type (string, int, decimal, date, boolean, text, datetime, float, bigint, uuid)
+- **Multi-Tenant Ready**: Different tenants can have different custom fields
+- **Query Transparency**: Use logical field names, metadata handles physical mapping
+
+**Flex Table Schema:**
+```sql
+CREATE TABLE flex_table (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT,
+  -- 10 string fields
+  string_field_1 TEXT,
+  string_field_2 TEXT,
+  ...
+  string_field_10 TEXT,
+  -- 10 int fields
+  int_field_1 INTEGER,
+  ...
+  int_field_10 INTEGER,
+  -- Plus: decimal, date, boolean, text, datetime, float, bigint, uuid fields
+  json_data TEXT,           -- Overflow for extra fields
+  created_at TEXT,
+  updated_at TEXT
+);
+```
+
+See [examples/06-flex-tables.ts](./examples/06-flex-tables.ts) and [examples/07-flex-with-multi-tenancy.ts](./examples/07-flex-with-multi-tenancy.ts) for complete workflows.
+
 ## Usage
 
 ### Query Builder

package/dist/index.cjs

@@ -4719,7 +4719,7 @@ var R2BackupAdapter = class {
 };
 
 // src/index.ts
-var version = "1.0.0";
+var version = "1.1.0";
 
 Object.defineProperty(exports, "Config", {
   enumerable: true,