spindb 0.37.2 → 0.38.0

package/core/version-utils.ts

@@ -1,104 +0,0 @@
-/**
- * Shared version comparison utilities
- *
- * Provides robust version comparison that handles prerelease suffixes
- * like "11.8.0-rc1" or "7.4.7-beta2".
- */
-
-/**
- * Parse a version segment into numeric prefix and suffix
- *
- * Expected format: optional digits followed by optional suffix
- * Examples:
- *   "7"     -> { num: 7, suffix: "" }
- *   "7-rc1" -> { num: 7, suffix: "-rc1" }
- *   "0"     -> { num: 0, suffix: "" }
- *
- * Non-numeric segments (no leading digits):
- *   "abc"   -> { num: -1, suffix: "abc" }
- *   ""      -> { num: -1, suffix: "" }
- *
- * Use num === -1 to detect non-numeric segments. When comparing versions,
- * non-numeric segments sort before numeric ones (since -1 < 0).
- *
- * @param segment - A single version segment (part between dots)
- * @returns Object with numeric prefix and remaining suffix
- */
-export function parseVersionSegment(segment: string): {
-  num: number
-  suffix: string
-} {
-  const match = segment.match(/^(\d+)(.*)$/)
-  if (!match) {
-    // Non-numeric segment: use -1 as sentinel so callers can distinguish
-    return { num: -1, suffix: segment }
-  }
-  return { num: parseInt(match[1], 10), suffix: match[2] }
-}
-
-/**
- * Compare two version strings (e.g., "11.8.5" vs "11.8.4")
- * Handles prerelease suffixes like "11.8.0-rc1" - empty suffix sorts after prerelease
- * Returns positive if a > b, negative if a < b, 0 if equal
- */
-export function compareVersions(a: string, b: string): number {
-  const partsA = a.split('.')
-  const partsB = b.split('.')
-
-  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-    const segA = parseVersionSegment(partsA[i] || '0')
-    const segB = parseVersionSegment(partsB[i] || '0')
-
-    // Compare numeric parts first
-    if (segA.num !== segB.num) {
-      return segA.num - segB.num
-    }
-
-    // If numeric parts equal, compare suffixes
-    // Empty suffix (release) > prerelease suffix (e.g., "-rc1")
-    if (segA.suffix !== segB.suffix) {
-      if (segA.suffix === '') return 1 // a is release, b is prerelease
-      if (segB.suffix === '') return -1 // b is release, a is prerelease
-      // NOTE: Lexicographic comparison means -rc10 < -rc2 (incorrect for numeric suffixes).
-      // This is acceptable for hostdb versions which use single-digit prereleases.
-      // If multi-digit prereleases are needed, parse numeric suffix separately.
-      return segA.suffix.localeCompare(segB.suffix)
-    }
-  }
-  return 0
-}
-
-/**
- * Check if versionA is newer than versionB
- * Convenience wrapper around compareVersions
- */
-export function isNewerVersion(versionA: string, versionB: string): boolean {
-  return compareVersions(versionA, versionB) > 0
-}
-
-/**
- * Regex pattern for validating semver-like version strings.
- * Matches: X, X.Y, or X.Y.Z where each component is numeric.
- * Examples: "8", "8.0", "8.0.40", "17", "17.7.0"
- */
-export const SEMVER_LIKE_PATTERN = /^\d+(\.\d+){0,2}$/
-
-/**
- * Validate that a version string matches semver-like format (X, X.Y, or X.Y.Z).
- * Used by engines that require strict version format validation (MySQL, PostgreSQL).
- *
- * @param version - Version string to validate
- * @param engineName - Engine name for error message (e.g., 'MySQL', 'PostgreSQL')
- * @throws TypeError if version format is invalid
- */
-export function validateSemverLikeVersion(
-  version: string,
-  engineName: string,
-): void {
-  if (!SEMVER_LIKE_PATTERN.test(version)) {
-    throw new TypeError(
-      `Invalid ${engineName} version format: "${version}". ` +
-        `Expected format: X, X.Y, or X.Y.Z (e.g., "8", "8.0", "8.0.40")`,
-    )
-  }
-}

package/engines/base-engine.ts

@@ -1,340 +0,0 @@
-import type {
-  ContainerConfig,
-  ProgressCallback,
-  BackupFormat,
-  BackupOptions,
-  BackupResult,
-  RestoreResult,
-  DumpResult,
-  StatusResult,
-  QueryResult,
-  QueryOptions,
-  CreateUserOptions,
-  UserCredentials,
-} from '../types'
-import { UnsupportedOperationError } from '../core/error-handler'
-import { stopPgweb } from '../core/pgweb-utils'
-
-/**
- * Base class for database engines
- * All engines (PostgreSQL, MySQL, SQLite) should extend this class
- */
-export abstract class BaseEngine {
-  abstract name: string
-  abstract displayName: string
-  abstract defaultPort: number
-  abstract supportedVersions: string[]
-
-  // Get the download URL for binaries
-  abstract getBinaryUrl(version: string, platform: string, arch: string): string
-
-  // Verify that the binaries are working correctly
-  abstract verifyBinary(binPath: string): Promise<boolean>
-
-  // Initialize a new data directory
-  abstract initDataDir(
-    containerName: string,
-    version: string,
-    options?: Record<string, unknown>,
-  ): Promise<string>
-
-  // Start the database server
-  abstract start(
-    container: ContainerConfig,
-    onProgress?: ProgressCallback,
-  ): Promise<{ port: number; connectionString: string }>
-
-  // Stop the database server
-  abstract stop(container: ContainerConfig): Promise<void>
-
-  // Get the status of the database server
-  abstract status(container: ContainerConfig): Promise<StatusResult>
-
-  // Detect the format of a backup file
-  abstract detectBackupFormat(filePath: string): Promise<BackupFormat>
-
-  // Restore a backup to the database
-  abstract restore(
-    container: ContainerConfig,
-    backupPath: string,
-    options?: Record<string, unknown>,
-  ): Promise<RestoreResult>
-
-  // Get the connection string for a container
-  abstract getConnectionString(
-    container: ContainerConfig,
-    database?: string,
-  ): string
-
-  /**
-   * Get the path to the psql client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured psql should override this method.
-   */
-  async getPsqlPath(): Promise<string> {
-    throw new Error('psql not found')
-  }
-
-  /**
-   * Get the path to the mysql client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured mysql should override this method.
-   */
-  async getMysqlClientPath(): Promise<string> {
-    throw new Error('mysql client not found')
-  }
-
-  /**
-   * Get the path to the mariadb client if available
-   * Default implementation throws; MariaDB engine overrides this method.
-   */
-  async getMariadbClientPath(): Promise<string> {
-    throw new Error('mariadb client not found')
-  }
-
-  /**
-   * Get the path to the mysqladmin client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured mysqladmin should override this method.
-   */
-  async getMysqladminPath(): Promise<string> {
-    throw new Error('mysqladmin not found')
-  }
-
-  /**
-   * Get the path to the mongosh client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured mongosh should override this method.
-   */
-  async getMongoshPath(): Promise<string> {
-    throw new Error('mongosh not found')
-  }
-
-  /**
-   * Get the path to the redis-cli client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured redis-cli should override this method.
-   */
-  async getRedisCliPath(): Promise<string> {
-    throw new Error('redis-cli not found')
-  }
-
-  /**
-   * Get the path to the valkey-cli client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured valkey-cli should override this method.
-   */
-  async getValkeyCliPath(): Promise<string> {
-    throw new Error('valkey-cli not found')
-  }
-
-  /**
-   * Get the path to the clickhouse client if available
-   * Default implementation throws; engines that can provide a bundled or
-   * configured clickhouse should override this method.
-   */
-  async getClickHouseClientPath(): Promise<string> {
-    throw new Error('clickhouse client not found')
-  }
-
-  /**
-   * Get the path to the cockroach binary if available
-   * Default implementation throws; CockroachDB engine overrides this method.
-   */
-  async getCockroachPath(_version?: string): Promise<string> {
-    throw new Error('cockroach not found')
-  }
-
-  /**
-   * Get the path to the surreal binary if available
-   * Default implementation throws; SurrealDB engine overrides this method.
-   */
-  async getSurrealPath(_version?: string): Promise<string> {
-    throw new Error('surreal not found')
-  }
-
-  /**
-   * Get the path to the typedb console binary if available
-   * Default implementation throws; TypeDB engine overrides this method.
-   */
-  async getTypeDBConsolePath(_version?: string): Promise<string> {
-    throw new Error('typedb_console_bin not found')
-  }
-
-  /**
-   * Get the path to the influxdb3 binary if available
-   * Default implementation throws; InfluxDB engine overrides this method.
-   */
-  async getInfluxDBPath(_version?: string): Promise<string> {
-    throw new Error('influxdb3 not found')
-  }
-
-  /**
-   * Get the path to the tigerbeetle binary if available
-   * Default implementation throws; TigerBeetle engine overrides this method.
-   */
-  async getTigerBeetlePath(_version?: string): Promise<string> {
-    throw new Error('tigerbeetle not found')
-  }
-
-  /**
-   * Get the path to the sqlite3 client if available
-   * Default implementation returns null; SQLite engine overrides this method.
-   */
-  async getSqlite3Path(_version?: string): Promise<string | null> {
-    return null
-  }
-
-  /**
-   * Get the path to the duckdb client if available
-   * Default implementation returns null; DuckDB engine overrides this method.
-   */
-  async getDuckDBPath(_version?: string): Promise<string | null> {
-    return null
-  }
-
-  // Open an interactive shell/CLI connection
-  abstract connect(container: ContainerConfig, database?: string): Promise<void>
-
-  // Create a new database within the container
-  abstract createDatabase(
-    container: ContainerConfig,
-    database: string,
-  ): Promise<void>
-
-  // Drop a database within the container
-  abstract dropDatabase(
-    container: ContainerConfig,
-    database: string,
-  ): Promise<void>
-
-  // Check if binaries are installed
-  abstract isBinaryInstalled(version: string): Promise<boolean>
-
-  // Ensure binaries are available, downloading if necessary
-  abstract ensureBinaries(
-    version: string,
-    onProgress?: ProgressCallback,
-  ): Promise<string>
-
-  /**
-   * Fetch all available versions from remote source (grouped by major version)
-   * Returns a map of major version -> array of full versions (sorted latest first)
-   * Falls back to hardcoded versions if network fails
-   */
-  async fetchAvailableVersions(): Promise<Record<string, string[]>> {
-    // Default implementation returns supported versions as single-item arrays
-    const versions: Record<string, string[]> = {}
-    for (const v of this.supportedVersions) {
-      versions[v] = [v]
-    }
-    return versions
-  }
-
-  // Create a dump from a remote database using a connection string
-  abstract dumpFromConnectionString(
-    connectionString: string,
-    outputPath: string,
-  ): Promise<DumpResult>
-
-  /**
-   * Get the size of a database in bytes
-   * Returns null if the container is not running or size cannot be determined
-   */
-  abstract getDatabaseSize(container: ContainerConfig): Promise<number | null>
-
-  /**
-   * Create a backup of a database
-   * @param container - The container configuration
-   * @param outputPath - Path to write the backup file
-   * @param options - Backup options including database name and format
-   */
-  abstract backup(
-    container: ContainerConfig,
-    outputPath: string,
-    options: BackupOptions,
-  ): Promise<BackupResult>
-
-  /**
-   * Run a SQL file or inline SQL statement against the database
-   * @param container - The container configuration
-   * @param options - Options including file path or SQL statement, and target database
-   */
-  abstract runScript(
-    container: ContainerConfig,
-    options: {
-      file?: string
-      sql?: string
-      database?: string
-      transactionType?: 'read' | 'write' | 'schema'
-    },
-  ): Promise<void>
-
-  /**
-   * Terminate all active connections to a database.
-   * Required before dropping a database that may have active connections.
-   * Default implementation is a no-op - engines that need it should override.
-   * @param container - The container configuration
-   * @param database - The database name to terminate connections for
-   */
-  async terminateConnections(
-    _container: ContainerConfig,
-    _database: string,
-  ): Promise<void> {
-    // Default: no-op. Override in engines that support connection termination.
-  }
-
-  /**
-   * Stop pgweb if running for this container.
-   * Called from stop() in engines that support pgweb (PostgreSQL, CockroachDB, FerretDB).
-   */
-  protected async stopPgweb(containerName: string): Promise<void> {
-    await stopPgweb(containerName, this.name)
-  }
-
-  /**
-   * Execute a query and return results in a structured format.
-   * @param container - The container configuration
-   * @param query - The query to execute (SQL, JavaScript, Redis commands, or REST API request)
-   * @param options - Query options including target database
-   * @returns QueryResult with columns, rows, and row count
-   */
-  abstract executeQuery(
-    container: ContainerConfig,
-    query: string,
-    options?: QueryOptions,
-  ): Promise<QueryResult>
-
-  /**
-   * List all user databases on the server, excluding system databases.
-   * Used to sync the registry with actual databases on the server.
-   *
-   * System databases excluded by default:
-   * - PostgreSQL: template0, template1, postgres
-   * - MySQL/MariaDB: information_schema, mysql, performance_schema, sys
-   * - CockroachDB: defaultdb, postgres, system
-   *
-   * @param container - The container configuration
-   * @returns Array of database names (excluding system databases)
-   * @throws Error if the engine doesn't support multiple databases or listing
-   */
-  async listDatabases(_container: ContainerConfig): Promise<string[]> {
-    throw new UnsupportedOperationError('listDatabases', this.displayName)
-  }
-
-  /**
-   * Create a database user with the given credentials.
-   * Returns credentials including connection string.
-   *
-   * @param container - The container configuration
-   * @param options - Username, password, and optional target database
-   * @returns UserCredentials with connection info
-   * @throws UnsupportedOperationError for engines that don't support users (SQLite, DuckDB, QuestDB)
-   */
-  async createUser(
-    _container: ContainerConfig,
-    _options: CreateUserOptions,
-  ): Promise<UserCredentials> {
-    throw new UnsupportedOperationError('createUser', this.displayName)
-  }
-}

package/engines/clickhouse/README.md

@@ -1,231 +0,0 @@
-# ClickHouse Engine Implementation
-
-## Overview
-
-ClickHouse is a high-performance columnar OLAP database. It uses a single unified binary that handles server, client, and local modes.
-
-## 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 | **NOT SUPPORTED** | See "Windows Support" section |
-
-### Windows Support - Extensive Investigation
-
-ClickHouse on Windows is **not supported** after extensive investigation:
-
-1. **No official Windows binaries**: ClickHouse does not provide official Windows builds
-2. **hostdb build attempts**: Multiple attempts were made to build ClickHouse for Windows in hostdb
-3. **Compilation failures**: The Windows build process has significant issues with the ClickHouse codebase
-4. **WSL recommended**: Users on Windows should use WSL (Windows Subsystem for Linux)
-
-This is one of the unsolved platform limitations in SpinDB. The decision was made to put a pin in Windows support and document it clearly rather than continue spending time on an unviable path.
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: Not applicable (unsupported)
-
-### Archive Structure - Potentially Flat
-
-ClickHouse archives may have either structure:
-
-**Standard structure:**
-```
-clickhouse/
-└── bin/
-    └── clickhouse       # Unified binary
-```
-
-**Flat structure:**
-```
-clickhouse              # Unified binary (no subdirectory)
-```
-
-The binary manager handles both cases with custom `moveExtractedEntries()`.
-
-### Unified Binary
-
-ClickHouse uses a single `clickhouse` binary for all operations:
-- `clickhouse server` - Run server
-- `clickhouse client` - Interactive client
-- `clickhouse local` - Local query processing
-
-### Version Map Sync
-
-**Important**: ClickHouse uses YY.MM versioning, not semver:
-
-```typescript
-export const CLICKHOUSE_VERSION_MAP: Record<string, string> = {
-  '25.12': '25.12.3.21',  // YY.MM.patch.build format
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-ClickHouse uses `BaseServerBinaryManager` with several overrides:
-- `extractWindowsBinaries()` - Throws error (Windows unsupported)
-- `moveExtractedEntries()` - Handles flat archive structure
-- `verify()` - Custom YY.MM version matching
-
-### Version Format - YY.MM
-
-ClickHouse versions are **year.month** based:
-- `25.12.3.21` means 2025, December, patch 3, build 21
-- Version matching compares first two parts (YY.MM)
-
-### Version Parsing
-
-- **Version output format**: `ClickHouse client version 25.12.3.21`
-- **Parse pattern**: `/(\d+\.\d+\.\d+\.\d+)/` (4-part version)
-- **Major version matching**: Compares `YY.MM` portion
-
-### XML Configuration
-
-ClickHouse uses XML configuration (not YAML):
-
-```xml
-<?xml version="1.0"?>
-<clickhouse>
-    <http_port>8124</http_port>
-    <tcp_port>9000</tcp_port>
-    <listen_host>127.0.0.1</listen_host>
-    <path>/data/</path>
-    <!-- ... -->
-</clickhouse>
-```
-
-### Dual Ports
-
-ClickHouse uses two ports:
-- **TCP Port** (default 9000): Native protocol
-- **HTTP Port** (default 8123): HTTP API and Play UI
-
-### Default Configuration
-
-- **Default TCP Port**: 9000 (auto-increments on conflict)
-- **HTTP Port**: TCP port + 1
-- **PID File**: `clickhouse.pid` in container directory
-- **Web UI**: Play at `http://localhost:8123/play`
-
-### PID File Handling
-
-ClickHouse in daemon mode doesn't respect `<pid_file>` config. The engine manually finds the process by port and writes the PID file:
-
-```typescript
-const pids = await platformService.findProcessByPort(port)
-if (pids.length > 0) {
-  await writeFile(pidFile, String(pids[0]), 'utf8')
-}
-```
-
-### Startup Command
-
-```bash
-clickhouse server --config-file config.xml --daemon
-```
-
-### Connection String Format
-
-```
-clickhouse://127.0.0.1:{port}/{database}
-```
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| sql | `.sql` | clickhouse client | SQL export |
-
-ClickHouse backup uses `SELECT * FORMAT SQLInsert` for data export.
-
-## Integration Test Notes
-
-### Extended Timeout
-
-ClickHouse can take longer to start on CI runners (up to 90 seconds). The `waitForReady()` timeout is extended accordingly.
-
-### Test Fixtures
-
-Located in `tests/fixtures/clickhouse/seeds/`:
-- SQL data for testing
-
-## Docker E2E Test Notes
-
-ClickHouse Docker E2E tests verify:
-- Server lifecycle
-- SQL operations via client
-- HTTP API availability
-- Backup/restore
-
-### Linux-Only in CI
-
-ClickHouse CI tests only run on Linux and macOS runners.
-
-## Known Issues & Gotchas
-
-### 1. Windows Not Supported
-
-Extensive work was done trying to get ClickHouse working on Windows. It's not viable. Use WSL.
-
-### 2. YY.MM Version Format
-
-Don't expect semver. Version `25.12.3.21` is December 2025, not version 25.12.
-
-### 3. Flat Archive Handling
-
-Some ClickHouse archives have binaries at the root, not in `bin/`. The engine handles this but be aware when debugging.
-
-### 4. XML Config
-
-Unlike most databases, ClickHouse uses XML configuration. The engine generates `config.xml` and `users.xml`.
-
-### 5. Long Startup Time
-
-ClickHouse may take longer to start than other databases, especially on first run or on resource-constrained systems.
-
-### 6. Memory Usage
-
-ClickHouse is designed for high-performance analytics and may use significant memory. The default `mark_cache_size` is 5GB.
-
-### 7. HTTP Port for Play UI
-
-The Play UI (web-based query interface) is at the HTTP port, not TCP port:
-- TCP: `clickhouse://localhost:9000`
-- HTTP/UI: `http://localhost:8123/play`
-
-## CI/CD Notes
-
-### Skipped on Windows
-
-ClickHouse CI tests are completely skipped on Windows runners.
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache ClickHouse binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/clickhouse-*
-    key: clickhouse-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/clickhouse/version-maps.ts') }}
-  if: runner.os != 'Windows'
-```
-
-## Windows Alternative
-
-For Windows users who need ClickHouse:
-
-1. **WSL (Recommended)**: Install SpinDB in WSL and run ClickHouse there
-2. **Docker**: Use official ClickHouse Docker images
-3. **ClickHouse Cloud**: Use managed cloud service
-
-There is no workaround for native Windows support at this time.