@pineliner/odb-client 1.0.0 → 1.0.2

package/src/database/manager.ts

@@ -0,0 +1,336 @@
+import type {
+  DatabaseManagerConfig,
+  BackendType,
+  Connection,
+  DatabaseAdapter,
+  MigrationConfig,
+  QueryResult,
+} from './types'
+import { BunSQLiteAdapter } from './adapters/bun-sqlite'
+import { LibSQLAdapter } from './adapters/libsql'
+import { ODBLiteAdapter } from './adapters/odblite'
+import { parseSQL } from './sql-parser'
+import fs from 'node:fs'
+
+/**
+ * Database factory for creating and managing multiple databases
+ *
+ * Features:
+ * - Creates multiple databases from single manager instance
+ * - Supports libsql, bun:sqlite, and ODB-Lite backends
+ * - Connection pooling with LRU eviction
+ * - Automatic schema migrations
+ *
+ * @example
+ * ```ts
+ * const dbManager = new DatabaseManager({
+ *   backend: 'libsql',
+ *   databasePath: './data'
+ * })
+ *
+ * // Create databases
+ * await dbManager.createDatabase('identity', { schemaContent })
+ * await dbManager.createDatabase('analytics', { schemaContent })
+ *
+ * // Get connections
+ * const identityDB = await dbManager.getConnection('identity')
+ * const analyticsDB = await dbManager.getConnection('analytics')
+ * ```
+ */
+export class DatabaseManager {
+  private config: DatabaseManagerConfig
+  private adapter: DatabaseAdapter
+  private connections: Map<string, Connection> = new Map()
+
+  // Connection pool management (LRU)
+  private connectionTimestamps: Map<string, number> = new Map()
+  private maxConnections: number
+
+  constructor(config: DatabaseManagerConfig) {
+    this.config = config
+    this.maxConnections = config.connectionPoolSize || 10
+
+    // Create appropriate adapter based on backend
+    switch (config.backend) {
+      case 'bun-sqlite':
+        this.adapter = new BunSQLiteAdapter({ databasePath: config.databasePath, create: true })
+        break
+
+      case 'libsql':
+        this.adapter = new LibSQLAdapter({
+          url: `file:${config.databasePath}`,
+          ...config.libsql
+        })
+        break
+
+      case 'odblite':
+        if (!config.odblite) {
+          throw new Error('odblite config required for odblite backend')
+        }
+        this.adapter = new ODBLiteAdapter(config.odblite)
+        break
+
+      default:
+        throw new Error(`Unknown backend type: ${config.backend}`)
+    }
+  }
+
+  /**
+   * Create a new database
+   * @param name - Database name (becomes filename or ODB-Lite database name)
+   * @param options - Optional creation options
+   */
+  async createDatabase(
+    name: string,
+    options?: { schemaContent?: string }
+  ): Promise<void> {
+    console.log(`📦 Creating database: ${name}`)
+
+    // Build database-specific config
+    const dbConfig = this.getDatabaseConfig(name)
+
+    // Create connection
+    const conn = await this.adapter.connect(dbConfig)
+
+    // Run migrations if schema provided
+    if (options?.schemaContent) {
+      await this.runMigrations(conn, { schemaContent: options.schemaContent })
+    }
+
+    // Store connection
+    this.connections.set(name, conn)
+    this.connectionTimestamps.set(name, Date.now())
+
+    // Evict LRU if pool is full
+    if (this.connections.size > this.maxConnections) {
+      await this.evictLRU()
+    }
+
+    console.log(`✅ Database created: ${name}`)
+  }
+
+  /**
+   * Check if a database exists
+   * @param name - Database name
+   * @returns true if database exists, false otherwise
+   *
+   * Note: For local backends (libsql, bun-sqlite), checks file existence.
+   * For ODB-Lite, checks if database is in connection cache.
+   */
+  async databaseExists(name: string): Promise<boolean> {
+    // Check if already in connection cache
+    if (this.connections.has(name)) {
+      return true
+    }
+
+    // For local file-based backends, check if file exists
+    switch (this.config.backend) {
+      case 'bun-sqlite': {
+        const dbPath = `${this.config.databasePath}/${name}.db`
+        return fs.existsSync(dbPath)
+      }
+
+      case 'libsql': {
+        const dbPath = `${this.config.databasePath}/${name}.db`
+        return fs.existsSync(dbPath)
+      }
+
+      case 'odblite': {
+        // For ODB-Lite, only return true if in cache
+        // (no way to check remote database existence without connecting)
+        return false
+      }
+
+      default:
+        return false
+    }
+  }
+
+  /**
+   * Get connection to a database
+   * @param name - Database name
+   *
+   * If database exists on disk but not in cache, it will be connected automatically.
+   * If database doesn't exist at all, an error will be thrown.
+   */
+  async getConnection(name: string): Promise<Connection> {
+    // Check if connection exists in cache
+    let conn = this.connections.get(name)
+
+    if (conn) {
+      this.connectionTimestamps.set(name, Date.now())
+      return conn
+    }
+
+    // Check if database exists on disk
+    const exists = await this.databaseExists(name)
+    if (exists) {
+      // Connect to existing database
+      const dbConfig = this.getDatabaseConfig(name)
+      conn = await this.adapter.connect(dbConfig)
+
+      // Store connection
+      this.connections.set(name, conn)
+      this.connectionTimestamps.set(name, Date.now())
+
+      // Evict LRU if pool is full
+      if (this.connections.size > this.maxConnections) {
+        await this.evictLRU()
+      }
+
+      return conn
+    }
+
+    // If database doesn't exist, throw error
+    throw new Error(
+      `Database "${name}" not found. Call createDatabase("${name}", { schemaContent }) first.`
+    )
+  }
+
+  /**
+   * Delete a database
+   * @param name - Database name
+   */
+  async deleteDatabase(name: string): Promise<void> {
+    console.log(`🗑️  Deleting database: ${name}`)
+
+    // Close connection if exists
+    const conn = this.connections.get(name)
+    if (conn) {
+      await conn.close()
+      this.connections.delete(name)
+      this.connectionTimestamps.delete(name)
+    }
+
+    // Backend-specific deletion
+    await this.adapter.disconnect(name)
+
+    console.log(`✅ Database deleted: ${name}`)
+  }
+
+  /**
+   * Execute SQL content on a database connection
+   * Useful for running migrations or initial schema
+   * @param name - Database name
+   * @param sqlContent - SQL content to execute
+   */
+  async executeSQLFile(name: string, sqlContent: string): Promise<void> {
+    const conn = await this.getConnection(name)
+    await this.runMigrations(conn, { schemaContent: sqlContent })
+  }
+
+  /**
+   * List all managed databases
+   */
+  async listDatabases(): Promise<string[]> {
+    return Array.from(this.connections.keys())
+  }
+
+  /**
+   * Close all connections
+   */
+  async close(): Promise<void> {
+    console.log(`🔌 Closing all database connections...`)
+
+    for (const [name, conn] of this.connections) {
+      await conn.close()
+    }
+
+    this.connections.clear()
+    this.connectionTimestamps.clear()
+
+    console.log(`✅ All connections closed`)
+  }
+
+  /**
+   * Run migrations on a connection
+   */
+  private async runMigrations(conn: Connection, config: MigrationConfig): Promise<void> {
+    // Parse SQL statements
+    const { pragmaStatements, regularStatements } = parseSQL(config.schemaContent)
+
+    // Execute PRAGMA statements first
+    for (const pragma of pragmaStatements) {
+      try {
+        await conn.execute(pragma)
+      } catch (error: any) {
+        // Ignore PRAGMA errors (they might not be supported on all backends)
+        console.log(`⚠️  PRAGMA note: ${error.message}`)
+      }
+    }
+
+    // Execute regular statements
+    for (const statement of regularStatements) {
+      try {
+        await conn.execute(statement)
+      } catch (error: any) {
+        // Ignore "already exists" errors for idempotency
+        if (
+          error.message?.includes('already exists') ||
+          error.message?.includes('no such column') ||
+          error.message?.includes('no such table')
+        ) {
+          console.log(`  ⚠️  Skipping: ${error.message}`)
+          continue
+        }
+        console.error(`❌ Migration failed: ${statement.substring(0, 100)}...`)
+        throw error
+      }
+    }
+
+    console.log(`✅ Migrations completed (${regularStatements.length} statements)`)
+  }
+
+  /**
+   * Get database-specific configuration
+   */
+  private getDatabaseConfig(name: string): any {
+    switch (this.config.backend) {
+      case 'bun-sqlite':
+        return {
+          databasePath: `${this.config.databasePath}/${name}.db`,
+          create: true
+        }
+
+      case 'libsql':
+        return {
+          url: `file:${this.config.databasePath}/${name}.db`,
+          ...this.config.libsql
+        }
+
+      case 'odblite':
+        return {
+          databaseName: `${this.config.databasePath}_${name}`,
+          ...this.config.odblite
+        }
+
+      default:
+        throw new Error(`Unknown backend: ${this.config.backend}`)
+    }
+  }
+
+  /**
+   * Evict least recently used connection
+   */
+  private async evictLRU(): Promise<void> {
+    let oldestKey: string | null = null
+    let oldestTime = Infinity
+
+    for (const [key, timestamp] of this.connectionTimestamps) {
+      if (timestamp < oldestTime) {
+        oldestTime = timestamp
+        oldestKey = key
+      }
+    }
+
+    if (oldestKey) {
+      const conn = this.connections.get(oldestKey)
+      if (conn) {
+        await conn.close()
+      }
+      this.connections.delete(oldestKey)
+      this.connectionTimestamps.delete(oldestKey)
+      console.log(`♻️  Evicted LRU connection: ${oldestKey}`)
+    }
+  }
+}

package/src/database/sql-parser.ts

@@ -0,0 +1,112 @@
+export interface ParsedStatements {
+  pragmaStatements: string[]
+  regularStatements: string[]
+}
+
+export interface SQLParserOptions {
+  separatePragma?: boolean
+}
+
+/**
+ * Parse SQL file into statements, separating PRAGMA from regular SQL
+ * Handles comments, quotes, and semicolons properly
+ */
+export function parseSQL(sqlContent: string, options: SQLParserOptions = {}): ParsedStatements {
+  const separatePragma = options.separatePragma ?? true
+
+  // Split by semicolons (node-sql-parser doesn't handle multiple statements well)
+  const statements = splitStatements(sqlContent)
+
+  if (!separatePragma) {
+    return {
+      pragmaStatements: [],
+      regularStatements: statements,
+    }
+  }
+
+  const pragmaStatements: string[] = []
+  const regularStatements: string[] = []
+
+  for (const statement of statements) {
+    const trimmed = statement.trim().toUpperCase()
+    if (trimmed.startsWith('PRAGMA')) {
+      pragmaStatements.push(statement)
+    } else {
+      regularStatements.push(statement)
+    }
+  }
+
+  return { pragmaStatements, regularStatements }
+}
+
+/**
+ * Split SQL content into individual statements
+ * Handles comments, quotes, and semicolons properly
+ */
+function splitStatements(sqlContent: string): string[] {
+  const statements: string[] = []
+  let currentStatement = ''
+  let inQuote = false
+  let quoteChar = ''
+
+  const lines = sqlContent.split('\n')
+
+  for (const line of lines) {
+    let processedLine = ''
+
+    for (let i = 0; i < line.length; i++) {
+      const char = line[i]
+      const prevChar = i > 0 ? line[i - 1] : ''
+      const nextChar = i < line.length - 1 ? line[i + 1] : ''
+
+      // Handle single-line comments
+      if (!inQuote && char === '-' && nextChar === '-') {
+        break // Skip rest of line
+      }
+
+      // Track quotes
+      if ((char === "'" || char === '"') && prevChar !== '\\') {
+        if (!inQuote) {
+          inQuote = true
+          quoteChar = char
+        } else if (char === quoteChar) {
+          inQuote = false
+          quoteChar = ''
+        }
+      }
+
+      processedLine += char
+
+      // Split on semicolon when not in quotes
+      if (char === ';' && !inQuote) {
+        currentStatement += processedLine
+        const stmt = currentStatement.trim()
+        if (stmt) {
+          statements.push(stmt)
+        }
+        currentStatement = ''
+        processedLine = ''
+      }
+    }
+
+    if (processedLine.trim()) {
+      currentStatement += `${processedLine}\n`
+    }
+  }
+
+  // Handle remaining statement
+  const finalStmt = currentStatement.trim()
+  if (finalStmt) {
+    statements.push(finalStmt)
+  }
+
+  return statements
+}
+
+/**
+ * Simple split for systems that don't need PRAGMA separation
+ */
+export function splitSQLStatements(sqlContent: string): string[] {
+  const { pragmaStatements, regularStatements } = parseSQL(sqlContent)
+  return [...pragmaStatements, ...regularStatements]
+}

package/src/database/types.ts

@@ -0,0 +1,140 @@
+import type { Database as BunDatabase } from 'bun:sqlite'
+import type { Client as LibSQLClient } from '@libsql/client'
+import type { ServiceClient } from '../service/service-client'
+
+/**
+ * Tenancy modes supported by DatabaseManager
+ */
+export type TenancyMode =
+  | 'single-db'           // Single database for entire system (identity, operation)
+  | 'multi-tenant'        // One database per tenant, no metastore (pipeline)
+  | 'metastore'           // Metastore + per-tenant databases (wallet)
+  | 'dual-mode'           // Switchable local/remote (tracking)
+
+/**
+ * Backend database types
+ */
+export type BackendType = 'bun-sqlite' | 'libsql' | 'odblite'
+
+/**
+ * Query result from any backend
+ */
+export interface QueryResult<T = any> {
+  rows: T[]
+  rowsAffected?: number
+  lastInsertRowid?: number | bigint
+}
+
+/**
+ * Unified database connection interface
+ * All backends implement this through adapters
+ */
+export interface Connection {
+  // Template tag queries (postgres.js-like)
+  query<T = any>(strings: TemplateStringsArray, ...values: any[]): Promise<QueryResult<T>>
+
+  // Standard query methods (supports both formats for LibSQL compatibility)
+  execute(sql: string | { sql: string; args?: any[] }, params?: any[]): Promise<QueryResult>
+  prepare(sql: string): PreparedStatement
+
+  // Transaction support
+  transaction<T>(fn: (tx: Connection) => Promise<T>): Promise<T>
+
+  // Connection management
+  close(): Promise<void>
+}
+
+/**
+ * Prepared statement interface
+ */
+export interface PreparedStatement {
+  execute(params?: any[]): Promise<QueryResult>
+  all(params?: any[]): Promise<any[]>
+  get(params?: any[]): Promise<any | null>
+}
+
+/**
+ * Database backend adapter interface
+ */
+export interface DatabaseAdapter {
+  readonly type: BackendType
+
+  // Connection management
+  connect(config: any): Promise<Connection>
+  disconnect(tenantId?: string): Promise<void>
+
+  // Health check
+  isHealthy(): Promise<boolean>
+}
+
+/**
+ * Migration configuration
+ */
+export interface MigrationConfig {
+  schemaContent: string       // SQL schema content (not file path)
+}
+
+/**
+ * DatabaseManager configuration
+ * Simplified: Manager defines WHERE databases go, createDatabase defines WHAT
+ */
+export interface DatabaseManagerConfig {
+  // Backend type
+  backend: BackendType
+
+  // Database path (where databases are stored)
+  databasePath: string  // e.g., './data', '/var/lib/databases', 'tenants' (for ODB-Lite prefix)
+
+  // Backend-specific options (optional)
+  libsql?: {
+    encryptionKey?: string
+    authToken?: string  // For Turso remote databases
+  }
+
+  odblite?: {
+    serviceUrl: string
+    apiKey: string
+    nodeId?: string  // Optional: specific node to create databases on (server selects if not provided)
+  }
+
+  // Connection pooling
+  connectionPoolSize?: number // Max connections per database (default: 10)
+}
+
+/**
+ * Bun SQLite adapter config
+ */
+export interface BunSQLiteConfig {
+  databasePath: string
+  readonly?: boolean
+  create?: boolean
+}
+
+/**
+ * LibSQL adapter config
+ */
+export interface LibSQLConfig {
+  url: string
+  authToken?: string
+  encryptionKey?: string
+}
+
+/**
+ * ODB-Lite adapter config
+ */
+export interface ODBLiteConfig {
+  serviceUrl: string
+  apiKey: string
+  nodeId?: string  // Optional: specific node to create databases on (server selects if not provided)
+}
+
+/**
+ * Tenant database info
+ */
+export interface TenantInfo {
+  tenantId: string
+  databaseHash?: string       // For ODB-Lite
+  databasePath?: string       // For file-based
+  createdAt: Date
+  metadata?: Record<string, any>
+}

package/src/index.ts

@@ -10,6 +10,16 @@ export { SQLParser, sql, fragment } from './core/sql-parser.ts';
 // Service management exports (high-level tenant database management)
 export { ServiceClient } from './service/service-client.ts';
 
+// Database Manager exports (unified multi-backend database abstraction)
+export {
+  DatabaseManager,
+  parseSQL,
+  splitSQLStatements,
+  BunSQLiteAdapter,
+  LibSQLAdapter,
+  ODBLiteAdapter,
+} from './database/index.ts';
+
 // Export all types
 export type {
   ODBLiteConfig,
@@ -30,6 +40,24 @@ export type {
   ODBLiteNode
 } from './service/service-client.ts';
 
+// Export database manager types
+export type {
+  TenancyMode,
+  BackendType,
+  QueryResult as DatabaseQueryResult,
+  Connection,
+  DatabaseAdapter,
+  PreparedStatement as DatabasePreparedStatement,
+  DatabaseManagerConfig,
+  MigrationConfig,
+  BunSQLiteConfig,
+  LibSQLConfig,
+  ODBLiteConfig as DatabaseODBLiteConfig,
+  TenantInfo,
+  ParsedStatements,
+  SQLParserOptions,
+} from './database/index.ts';
+
 // Export error classes
 export {
   ODBLiteError,

package/src/service/service-client.ts

@@ -97,8 +97,7 @@ export class ServiceClient {
     try {
       // Check if database already exists
       console.log(`🔍 Checking if database exists: ${cacheKey}`);
-      const databases = await this.listDatabases();
-      const existing = databases.find(db => db.name === cacheKey);
+      const existing = await this.getDatabaseByName(cacheKey);
 
       if (existing) {
         console.log(`✅ Database already exists: ${cacheKey} (${existing.hash})`);
@@ -159,17 +158,22 @@ export class ServiceClient {
    * Create a new database
    *
    * @param name - Database name (should be unique)
-   * @param nodeId - ID of the node to host the database
+   * @param nodeId - ID of the node to host the database (optional - server will select if null)
    * @returns Created database object with hash
    */
-  async createDatabase(name: string, nodeId: string): Promise<ODBLiteDatabase> {
+  async createDatabase(name: string, nodeId?: string | null): Promise<ODBLiteDatabase> {
+    const body: any = { name }
+    if (nodeId) {
+      body.nodeId = nodeId
+    }
+
     const response = await fetch(`${this.apiUrl}/api/tenant/databases`, {
       method: 'POST',
       headers: {
         'Authorization': `Bearer ${this.apiKey}`,
         'Content-Type': 'application/json',
       },
-      body: JSON.stringify({ name, nodeId }),
+      body: JSON.stringify(body),
     });
 
     const result = await response.json();
@@ -201,6 +205,31 @@ export class ServiceClient {
     return result.database;
   }
 
+  /**
+   * Get database details by name
+   *
+   * @param name - Database name
+   * @returns Database object or null if not found
+   */
+  async getDatabaseByName(name: string): Promise<ODBLiteDatabase | null> {
+    const response = await fetch(`${this.apiUrl}/api/tenant/databases/by-name/${name}`, {
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+    });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    const result = await response.json();
+    if (!result.success) {
+      throw new Error(result.error || 'Failed to get database');
+    }
+
+    return result.database;
+  }
+
   /**
    * Delete a database
    *