spindb 0.37.2 → 0.38.0

package/engines/cockroachdb/README.md

@@ -1,170 +0,0 @@
-# CockroachDB Engine Implementation
-
-## Overview
-
-CockroachDB is a distributed SQL database with PostgreSQL wire protocol compatibility. It uses a single `cockroach` binary for all operations.
-
-## Platform Support
-
-| Platform | Architecture | Status | Notes |
-|----------|--------------|--------|-------|
-| darwin | x64 | Supported | Uses hostdb binaries |
-| darwin | arm64 | Supported | Uses hostdb binaries (Apple Silicon) |
-| linux | x64 | Supported | Uses hostdb binaries |
-| linux | arm64 | Supported | Uses hostdb binaries |
-| win32 | x64 | Supported | Uses hostdb binaries |
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: `zip`
-
-### Archive Structure
-```
-cockroachdb/
-└── bin/
-    └── cockroach        # Unified binary
-```
-
-### Version Format - YY.MM
-
-Like ClickHouse, CockroachDB uses **year-based versioning**:
-- `25.4.2` means 2025, release 4, patch 2
-- **NOT** semver
-
-### Version Map Sync
-
-```typescript
-export const COCKROACHDB_VERSION_MAP: Record<string, string> = {
-  '25': '25.4.2',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-CockroachDB uses `BaseBinaryManager` with standard configuration.
-
-### Version Parsing
-
-- **Version output format**: `Build Tag: v25.4.2` or `CockroachDB CCL v25.4.2`
-- **Parse pattern**: `/v?(\d+\.\d+\.\d+)/`
-
-### Default Configuration
-
-- **Default Port**: 26257 (auto-increments on conflict)
-- **HTTP Port**: 8080 (Admin UI)
-- **PID File**: `cockroach.pid` in container directory
-
-### PostgreSQL Wire Protocol
-
-CockroachDB is PostgreSQL-compatible:
-- Use `psql` for connections
-- Standard PostgreSQL connection strings work
-- PostgreSQL drivers work
-
-### Connection String Format
-
-```
-postgresql://root@127.0.0.1:{port}/{database}
-```
-
-### Critical: Background Process Stdio
-
-**MUST use `stdio: ['ignore', 'ignore', 'ignore']`** for spawning detached server:
-
-```typescript
-const proc = spawn(cockroachBinary, args, {
-  stdio: ['ignore', 'ignore', 'ignore'],  // NOT 'pipe'
-  detached: true,
-  windowsHide: true,
-})
-proc.unref()
-```
-
-Using `'pipe'` for stdout/stderr keeps file descriptors open that prevent Node.js from exiting, causing `spindb start` to hang indefinitely in Docker/CI environments.
-
-This is documented in CLAUDE.md as a major gotcha.
-
-### Startup Command
-
-```bash
-cockroach start-single-node \
-  --insecure \
-  --store={dataDir} \
-  --listen-addr=127.0.0.1:{port} \
-  --http-addr=127.0.0.1:{httpPort} \
-  --background
-```
-
-## Backup & Restore
-
-CockroachDB supports SQL-based backup/restore compatible with PostgreSQL tools.
-
-## Integration Test Notes
-
-### PostgreSQL Tools
-
-Integration tests can use `psql` for CockroachDB operations.
-
-### Test Fixtures
-
-Located in `tests/fixtures/cockroachdb/seeds/`:
-- SQL data for testing
-
-## Docker E2E Test Notes
-
-CockroachDB Docker E2E tests verify:
-- Single-node cluster startup
-- PostgreSQL wire protocol operations
-- Database creation/deletion
-- Data operations
-
-## Known Issues & Gotchas
-
-### 1. stdio Must Be 'ignore'
-
-**Critical**: Using `stdio: 'pipe'` causes Node.js to hang. Always use `['ignore', 'ignore', 'ignore']` for detached spawn. This is the most important gotcha for CockroachDB.
-
-### 2. YY.MM Version Format
-
-Version `25.4.2` is year 2025, not semver version 25.
-
-### 3. Single-Node Mode
-
-SpinDB runs CockroachDB in single-node mode (`--insecure`) for local development. Not suitable for production.
-
-### 4. Admin UI Port
-
-CockroachDB has a web Admin UI on a separate HTTP port (default 8080). This is in addition to the SQL port.
-
-### 5. Slow Initial Startup
-
-First startup can be slow as CockroachDB initializes its distributed storage layer.
-
-### 6. Memory Usage
-
-CockroachDB is designed for distributed systems and may use more memory than simpler databases.
-
-## CI/CD Notes
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache CockroachDB binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/cockroachdb-*
-    key: cockroachdb-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/cockroachdb/version-maps.ts') }}
-```
-
-## PostgreSQL Compatibility Notes
-
-CockroachDB is largely PostgreSQL-compatible but has some differences:
-- Not all PostgreSQL features are supported
-- Some SQL syntax differences
-- Different system tables
-
-For most common operations, PostgreSQL tools and drivers work correctly.

package/engines/cockroachdb/backup.ts

@@ -1,376 +0,0 @@
-/**
- * CockroachDB backup module
- * Supports SQL-based backups using cockroach sql
- *
- * CockroachDB backup formats:
- * - SQL: DDL + INSERT statements (portable, human-readable)
- */
-
-import { spawn } from 'child_process'
-import { stat, mkdir, writeFile } from 'fs/promises'
-import { existsSync } from 'fs'
-import { dirname } from 'path'
-import { logDebug, logWarning } from '../../core/error-handler'
-import {
-  requireCockroachPath,
-  validateCockroachIdentifier,
-  escapeCockroachIdentifier,
-} from './cli-utils'
-import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
-
-/**
- * Execute a CockroachDB query and return the result
- */
-async function execCockroachQuery(
-  cockroachPath: string,
-  port: number,
-  database: string,
-  query: string,
-): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const args = [
-      'sql',
-      '--insecure',
-      '--host',
-      `127.0.0.1:${port}`,
-      '--database',
-      database,
-      '--execute',
-      query,
-      '--format=csv',
-    ]
-
-    const proc = spawn(cockroachPath, args, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-
-    let stdout = ''
-    let stderr = ''
-
-    proc.stdout.on('data', (data: Buffer) => {
-      stdout += data.toString()
-    })
-    proc.stderr.on('data', (data: Buffer) => {
-      stderr += data.toString()
-    })
-
-    proc.on('error', reject)
-
-    proc.on('close', (code) => {
-      if (code === 0 || code === null) {
-        resolve(stdout)
-      } else {
-        reject(new Error(stderr || `cockroach sql exited with code ${code}`))
-      }
-    })
-  })
-}
-
-/**
- * Get list of tables in a database
- */
-async function getTables(
-  cockroachPath: string,
-  port: number,
-  database: string,
-): Promise<string[]> {
-  // Validate database identifier to prevent SQL injection
-  validateCockroachIdentifier(database, 'database')
-
-  const result = await execCockroachQuery(
-    cockroachPath,
-    port,
-    database,
-    `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_type = 'BASE TABLE' ORDER BY table_name`,
-  )
-
-  // Parse CSV output (skip header row)
-  const lines = result.trim().split('\n')
-  if (lines.length <= 1) return []
-
-  return lines
-    .slice(1) // Skip header
-    .map((line) => line.trim())
-    .filter((t) => t)
-}
-
-/**
- * Get CREATE TABLE statement for a table
- */
-async function getCreateTableStatement(
-  cockroachPath: string,
-  port: number,
-  database: string,
-  table: string,
-): Promise<string> {
-  // Validate identifiers to prevent SQL injection
-  validateCockroachIdentifier(database, 'database')
-  validateCockroachIdentifier(table, 'table')
-  const escapedTable = escapeCockroachIdentifier(table)
-
-  const result = await execCockroachQuery(
-    cockroachPath,
-    port,
-    database,
-    `SHOW CREATE TABLE ${escapedTable}`,
-  )
-
-  // Parse CSV output - format is: table_name,create_statement
-  const lines = result.trim().split('\n')
-  if (lines.length < 2) {
-    throw new Error(`Could not get CREATE TABLE for ${table}`)
-  }
-
-  // The create statement may span multiple lines, so join everything after the header
-  // and extract the statement part
-  const dataLines = lines.slice(1).join('\n')
-
-  // CockroachDB CSV output has the create statement in the second column
-  // Format: "table_name","CREATE TABLE..."
-  const match = dataLines.match(/^"?[^"]*"?,\s*"?(CREATE TABLE[\s\S]*)"?$/i)
-  if (match) {
-    // Remove surrounding quotes and unescape double quotes
-    return match[1].replace(/^"|"$/g, '').replace(/""/g, '"')
-  }
-
-  // Fallback: return everything after the first comma
-  const commaIdx = dataLines.indexOf(',')
-  if (commaIdx !== -1) {
-    return dataLines
-      .slice(commaIdx + 1)
-      .trim()
-      .replace(/^"|"$/g, '')
-  }
-
-  return dataLines
-}
-
-/**
- * Get INSERT statements for a table's data
- */
-async function getTableData(
-  cockroachPath: string,
-  port: number,
-  database: string,
-  table: string,
-): Promise<string[]> {
-  validateCockroachIdentifier(table, 'table')
-  const escapedTable = escapeCockroachIdentifier(table)
-
-  // Get column names
-  const columnsResult = await execCockroachQuery(
-    cockroachPath,
-    port,
-    database,
-    `SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = '${table.replace(/'/g, "''")}' ORDER BY ordinal_position`,
-  )
-
-  const columns = columnsResult
-    .trim()
-    .split('\n')
-    .slice(1) // Skip header
-    .map((line) => line.trim())
-    .filter((c) => c)
-
-  if (columns.length === 0) {
-    return []
-  }
-
-  // Get data
-  const dataResult = await execCockroachQuery(
-    cockroachPath,
-    port,
-    database,
-    `SELECT * FROM ${escapedTable}`,
-  )
-
-  const lines = dataResult.trim().split('\n')
-  if (lines.length <= 1) {
-    return [] // No data rows
-  }
-
-  const inserts: string[] = []
-
-  // Parse CSV data rows
-  for (const line of lines.slice(1)) {
-    if (!line.trim()) continue
-
-    // Simple CSV parsing (handles basic cases)
-    const fields = parseCSVLine(line)
-    if (fields.length !== columns.length) {
-      logWarning(
-        `Column count mismatch for table ${table}: expected ${columns.length}, got ${fields.length}`,
-      )
-      continue
-    }
-
-    const escapedValues = fields.map((field) => {
-      // Unquoted empty string or unquoted literal 'NULL' becomes SQL NULL
-      if (!field.wasQuoted && (field.value === '' || field.value === 'NULL')) {
-        return 'NULL'
-      }
-      // Quoted empty string stays as empty string, all other values get escaped
-      return `'${field.value.replace(/'/g, "''")}'`
-    })
-
-    const columnList = columns
-      .map((c) => escapeCockroachIdentifier(c))
-      .join(', ')
-    inserts.push(
-      `INSERT INTO ${escapedTable} (${columnList}) VALUES (${escapedValues.join(', ')});`,
-    )
-  }
-
-  return inserts
-}
-
-/**
- * Parsed CSV field with value and whether it was quoted
- */
-type CSVField = {
-  value: string
-  wasQuoted: boolean
-}
-
-/**
- * Parse a CSV line (basic implementation)
- * Returns both the value and whether the field was quoted,
- * which is important for distinguishing empty strings from NULL
- */
-function parseCSVLine(line: string): CSVField[] {
-  const fields: CSVField[] = []
-  let current = ''
-  let inQuotes = false
-  let fieldWasQuoted = false
-
-  for (let i = 0; i < line.length; i++) {
-    const char = line[i]
-
-    if (char === '"') {
-      if (inQuotes && line[i + 1] === '"') {
-        // Escaped quote
-        current += '"'
-        i++
-      } else {
-        // Toggle quote state
-        if (!inQuotes) {
-          fieldWasQuoted = true
-        }
-        inQuotes = !inQuotes
-      }
-    } else if (char === ',' && !inQuotes) {
-      fields.push({ value: current, wasQuoted: fieldWasQuoted })
-      current = ''
-      fieldWasQuoted = false
-    } else {
-      current += char
-    }
-  }
-
-  fields.push({ value: current, wasQuoted: fieldWasQuoted })
-  return fields
-}
-
-/**
- * Create a SQL backup (DDL + INSERT statements)
- */
-async function createSqlBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  database: string,
-): Promise<BackupResult> {
-  const { port, version } = container
-
-  const cockroachPath = await requireCockroachPath(version)
-
-  const lines: string[] = []
-  lines.push('-- CockroachDB backup generated by SpinDB')
-  lines.push(`-- Date: ${new Date().toISOString()}`)
-  lines.push(`-- Database: ${database}`)
-  lines.push('')
-
-  // Get list of tables
-  const tables = await getTables(cockroachPath, port, database)
-  logDebug(`Found ${tables.length} tables to backup`)
-
-  for (const table of tables) {
-    lines.push(`-- Table: ${table}`)
-    lines.push('')
-
-    // Get CREATE TABLE statement
-    try {
-      const createStmt = await getCreateTableStatement(
-        cockroachPath,
-        port,
-        database,
-        table,
-      )
-      lines.push(createStmt + ';')
-      lines.push('')
-    } catch (error) {
-      logWarning(`Could not get CREATE TABLE for ${table}: ${error}`)
-      continue
-    }
-
-    // Export data
-    try {
-      const inserts = await getTableData(cockroachPath, port, database, table)
-      if (inserts.length > 0) {
-        lines.push(...inserts)
-        lines.push('')
-      }
-    } catch (error) {
-      logWarning(`Could not export data for ${table}: ${error}`)
-    }
-  }
-
-  // Ensure output directory exists
-  const outputDir = dirname(outputPath)
-  if (!existsSync(outputDir)) {
-    await mkdir(outputDir, { recursive: true })
-  }
-
-  // Write to file
-  const content = lines.join('\n')
-  await writeFile(outputPath, content, 'utf-8')
-
-  const stats = await stat(outputPath)
-
-  return {
-    path: outputPath,
-    format: 'sql',
-    size: stats.size,
-  }
-}
-
-/**
- * Create a backup
- *
- * @param container - Container configuration
- * @param outputPath - Path to write backup file
- * @param options - Backup options
- */
-export async function createBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  options: BackupOptions,
-): Promise<BackupResult> {
-  const database = options.database || container.database || 'defaultdb'
-
-  return createSqlBackup(container, outputPath, database)
-}
-
-/**
- * Create a backup for cloning purposes
- * Uses SQL format for reliability
- */
-export async function createCloneBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  return createSqlBackup(
-    container,
-    outputPath,
-    container.database || 'defaultdb',
-  )
-}

package/engines/cockroachdb/binary-manager.ts

@@ -1,45 +0,0 @@
-/**
- * CockroachDB Binary Manager
- *
- * Handles downloading, extracting, and managing CockroachDB binaries from hostdb.
- * Extends BaseBinaryManager for shared download/extraction logic.
- */
-
-import {
-  BaseBinaryManager,
-  type BinaryManagerConfig,
-} from '../../core/base-binary-manager'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, type Platform, type Arch } from '../../types'
-
-class CockroachDBBinaryManager extends BaseBinaryManager {
-  protected readonly config: BinaryManagerConfig = {
-    engine: Engine.CockroachDB,
-    engineName: 'cockroachdb',
-    displayName: 'CockroachDB',
-    serverBinary: 'cockroach',
-  }
-
-  protected getBinaryUrlFromModule(
-    version: string,
-    platform: Platform,
-    arch: Arch,
-  ): string {
-    return getBinaryUrl(version, platform, arch)
-  }
-
-  protected normalizeVersionFromModule(version: string): string {
-    return normalizeVersion(version)
-  }
-
-  protected parseVersionFromOutput(stdout: string): string | null {
-    // Extract version from output like:
-    // "Build Tag:        v25.4.2"
-    // or "CockroachDB CCL v25.4.2"
-    const match = stdout.match(/v?(\d+\.\d+\.\d+)/)
-    return match?.[1] ?? null
-  }
-}
-
-export const cockroachdbBinaryManager = new CockroachDBBinaryManager()

package/engines/cockroachdb/binary-urls.ts

@@ -1,40 +0,0 @@
-/**
- * CockroachDB binary URL generation
- *
- * Generates download URLs for CockroachDB binaries from the layerbase registry.
- */
-
-import { type Platform, type Arch, Engine } from '../../types'
-import { normalizeVersion } from './version-maps'
-import { buildHostdbUrl } from '../../core/hostdb-client'
-
-/**
- * Get the binary download URL for a specific version and platform
- *
- * URL format: https://registry.layerbase.host/cockroachdb-{version}/cockroachdb-{version}-{platform}-{arch}.{ext}
- *
- * @param version - CockroachDB version (e.g., '25.4.2' or '25')
- * @param platform - Target platform (darwin, linux, win32)
- * @param arch - Target architecture (x64, arm64)
- */
-export function getBinaryUrl(
-  version: string,
-  platform: Platform,
-  arch: Arch,
-): string {
-  const fullVersion = normalizeVersion(version)
-  const ext = platform === 'win32' ? 'zip' : 'tar.gz'
-
-  return buildHostdbUrl(Engine.CockroachDB, {
-    version: fullVersion,
-    hostdbPlatform: `${platform}-${arch}`,
-    extension: ext,
-  })
-}
-
-/**
- * Get the archive extension for a platform
- */
-export function getArchiveExtension(platform: Platform): string {
-  return platform === 'win32' ? 'zip' : 'tar.gz'
-}