spindb 0.37.2 → 0.38.0

package/engines/postgresql/version-validator.ts

@@ -1,413 +0,0 @@
-/**
- * PostgreSQL Version Validator
- *
- * Validates compatibility between pg_restore tool version and dump file version.
- * PostgreSQL is backwards compatible - we only fail when dump_version > tool_version.
- */
-
-import { exec } from 'child_process'
-import { promisify } from 'util'
-import { createReadStream } from 'fs'
-import { createInterface } from 'readline'
-import {
-  SpinDBError,
-  ErrorCodes,
-  logWarning,
-  logDebug,
-} from '../../core/error-handler'
-import { detectPackageManager } from '../../core/dependency-manager'
-import {
-  detectInstalledPostgres,
-  getDirectBinaryPath,
-  findCompatibleVersion,
-} from '../../core/homebrew-version-manager'
-import {
-  detectRemotePostgresVersion,
-  type RemoteVersionResult,
-} from './remote-version'
-
-const execAsync = promisify(exec)
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export type VersionInfo = {
-  major: number
-  minor: number
-  patch: number
-  full: string
-}
-
-export type CompatibilityResult = {
-  compatible: boolean
-  dumpVersion: VersionInfo | null
-  toolVersion: VersionInfo
-  warning?: string
-  error?: string
-}
-
-// =============================================================================
-// Version Parsing
-// =============================================================================
-
-/**
- * Parse version from pg_dump/pg_restore --version output
- * Examples:
- *   "pg_restore (PostgreSQL) 16.1"
- *   "pg_restore (PostgreSQL) 14.9 (Homebrew)"
- *   "pg_dump (PostgreSQL) 17.0"
- */
-export function parseToolVersion(output: string): VersionInfo {
-  const match = output.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
-  if (!match) {
-    throw new Error(`Cannot parse version from: ${output}`)
-  }
-  return {
-    major: parseInt(match[1], 10),
-    minor: parseInt(match[2], 10),
-    patch: parseInt(match[3] || '0', 10),
-    full: match[0],
-  }
-}
-
-async function readFirstLines(
-  filePath: string,
-  lineCount: number,
-): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const lines: string[] = []
-    const stream = createReadStream(filePath, { encoding: 'utf8' })
-    const rl = createInterface({ input: stream })
-
-    rl.on('line', (line) => {
-      lines.push(line)
-      if (lines.length >= lineCount) {
-        rl.close()
-        stream.destroy()
-      }
-    })
-
-    rl.on('close', () => {
-      resolve(lines.join('\n'))
-    })
-
-    rl.on('error', reject)
-    stream.on('error', reject)
-  })
-}
-
-/**
- * Parse version from dump file header
- *
- * Plain SQL format: "-- Dumped from database version 16.1"
- * Archive format: Uses `pg_restore -l` to read TOC header
- */
-export async function parseDumpVersion(
-  dumpPath: string,
-  format: string,
-  pgRestorePath?: string,
-): Promise<VersionInfo | null> {
-  try {
-    if (format === 'custom' || format === 'directory') {
-      // Use pg_restore -l to get archive info
-      const restorePath = pgRestorePath || 'pg_restore'
-      const { stdout } = await execAsync(
-        `"${restorePath}" -l "${dumpPath}" 2>&1 | head -20`,
-      )
-      // Look for: "; Dumped from database version 16.1"
-      const match = stdout.match(
-        /Dumped from database version (\d+)\.(\d+)(?:\.(\d+))?/,
-      )
-      if (match) {
-        return {
-          major: parseInt(match[1], 10),
-          minor: parseInt(match[2], 10),
-          patch: parseInt(match[3] || '0', 10),
-          full: `${match[1]}.${match[2]}${match[3] ? `.${match[3]}` : ''}`,
-        }
-      }
-    } else {
-      // Plain SQL format - read first 50 lines
-      const header = await readFirstLines(dumpPath, 50)
-      const match = header.match(
-        /Dumped from database version (\d+)\.(\d+)(?:\.(\d+))?/,
-      )
-      if (match) {
-        return {
-          major: parseInt(match[1], 10),
-          minor: parseInt(match[2], 10),
-          patch: parseInt(match[3] || '0', 10),
-          full: `${match[1]}.${match[2]}${match[3] ? `.${match[3]}` : ''}`,
-        }
-      }
-    }
-  } catch (error) {
-    logDebug('Failed to parse dump version', {
-      dumpPath,
-      format,
-      error: error instanceof Error ? error.message : String(error),
-    })
-  }
-
-  return null // Version not found in dump
-}
-
-// Get the version of pg_restore
-export async function getPgRestoreVersion(
-  pgRestorePath: string,
-): Promise<VersionInfo> {
-  const { stdout } = await execAsync(`"${pgRestorePath}" --version`)
-  return parseToolVersion(stdout)
-}
-
-// =============================================================================
-// Compatibility Checking
-// =============================================================================
-
-/**
- * Check version compatibility - ONLY fails when dump is NEWER than tool
- *
- * | Scenario | Result |
- * |----------|--------|
- * | pg_restore v16 + dump from v14 | ✅ Works (backwards compatible) |
- * | pg_restore v16 + dump from v16 | ✅ Works (same version) |
- * | pg_restore v14 + dump from v16 | ❌ Fails (dump newer than tool) |
- * | pg_restore v16 + dump from v10 | ⚠️ Works with warning (very old) |
- */
-export function checkVersionCompatibility(
-  dumpVersion: VersionInfo | null,
-  toolVersion: VersionInfo,
-): CompatibilityResult {
-  // If we couldn't parse dump version, proceed with warning
-  if (!dumpVersion) {
-    return {
-      compatible: true,
-      dumpVersion: null,
-      toolVersion,
-      warning: 'Could not detect dump version. Proceeding anyway.',
-    }
-  }
-
-  // FAIL: Dump is newer than tool (e.g., pg_restore 14 + dump from 16)
-  if (dumpVersion.major > toolVersion.major) {
-    return {
-      compatible: false,
-      dumpVersion,
-      toolVersion,
-      error:
-        `Backup was created with PostgreSQL ${dumpVersion.major}, ` +
-        `but your pg_restore is version ${toolVersion.major}. ` +
-        `Install PostgreSQL ${dumpVersion.major} client tools to restore this backup.`,
-    }
-  }
-
-  // WARN: Dump is very old (3+ major versions behind)
-  if (dumpVersion.major < toolVersion.major - 2) {
-    return {
-      compatible: true,
-      dumpVersion,
-      toolVersion,
-      warning:
-        `Backup was created with PostgreSQL ${dumpVersion.major}. ` +
-        `Some features may not restore correctly.`,
-    }
-  }
-
-  // OK: Same version or dump is older (backwards compatible)
-  return { compatible: true, dumpVersion, toolVersion }
-}
-
-// =============================================================================
-// Main Validation Function
-// =============================================================================
-
-/**
- * Validate that a dump file can be restored with the available pg_restore
- *
- * @throws SpinDBError if versions are incompatible
- */
-export async function validateRestoreCompatibility(options: {
-  dumpPath: string
-  format: string
-  pgRestorePath: string
-}): Promise<{ dumpVersion: VersionInfo | null; toolVersion: VersionInfo }> {
-  const { dumpPath, format, pgRestorePath } = options
-
-  // Get tool version
-  const toolVersion = await getPgRestoreVersion(pgRestorePath)
-  logDebug('pg_restore version detected', { version: toolVersion.full })
-
-  // Get dump version
-  const dumpVersion = await parseDumpVersion(dumpPath, format, pgRestorePath)
-  if (dumpVersion) {
-    logDebug('Dump version detected', { version: dumpVersion.full })
-  } else {
-    logDebug('Could not detect dump version')
-  }
-
-  // Check compatibility
-  const result = checkVersionCompatibility(dumpVersion, toolVersion)
-
-  if (!result.compatible) {
-    throw new SpinDBError(
-      ErrorCodes.VERSION_MISMATCH,
-      result.error!,
-      'fatal',
-      `Install PostgreSQL ${dumpVersion!.major} client tools: brew install postgresql@${dumpVersion!.major}`,
-      { dumpVersion, toolVersion },
-    )
-  }
-
-  if (result.warning) {
-    logWarning(result.warning)
-  }
-
-  return { dumpVersion, toolVersion }
-}
-
-// =============================================================================
-// Pre-Dump Compatibility Validation
-// =============================================================================
-
-export type DumpCompatibilityResult = {
-  compatible: boolean
-  localToolVersion: VersionInfo
-  remoteDbVersion: RemoteVersionResult
-  requiredAction: 'none' | 'use_direct_path' | 'switch_homebrew' | 'install'
-  alternativePath?: string // Direct path to correct version binary
-  switchTarget?: string // Major version to switch to
-  error?: string
-}
-
-export async function getPgDumpVersion(
-  pgDumpPath: string,
-): Promise<VersionInfo> {
-  const { stdout } = await execAsync(`"${pgDumpPath}" --version`)
-  return parseToolVersion(stdout)
-}
-
-/**
- * Validate that a remote database can be dumped with the current pg_dump
- *
- * This checks BEFORE dumping to avoid creating incompatible dump files.
- * Returns the recommended action if the current pg_dump is incompatible.
- */
-export async function validateDumpCompatibility(options: {
-  connectionString: string
-  pgDumpPath: string
-}): Promise<DumpCompatibilityResult> {
-  const { connectionString, pgDumpPath } = options
-
-  // Get local pg_dump version
-  const localVersion = await getPgDumpVersion(pgDumpPath)
-  logDebug('Local pg_dump version', { version: localVersion.full })
-
-  // Detect remote database version
-  const remoteVersion = await detectRemotePostgresVersion(connectionString)
-  logDebug('Remote database version', {
-    version: remoteVersion.fullVersion,
-    serverType: remoteVersion.serverType,
-  })
-
-  // Check compatibility: local tool must be >= remote version
-  if (localVersion.major >= remoteVersion.majorVersion) {
-    return {
-      compatible: true,
-      localToolVersion: localVersion,
-      remoteDbVersion: remoteVersion,
-      requiredAction: 'none',
-    }
-  }
-
-  // Version mismatch - check if we can use a direct path
-  const targetMajor = String(remoteVersion.majorVersion)
-  const directPath = await getDirectBinaryPath('pg_dump', targetMajor)
-
-  if (directPath) {
-    // Have a direct path to the correct version
-    return {
-      compatible: false,
-      localToolVersion: localVersion,
-      remoteDbVersion: remoteVersion,
-      requiredAction: 'use_direct_path',
-      alternativePath: directPath,
-      switchTarget: targetMajor,
-    }
-  }
-
-  // Check if any compatible version is installed via Homebrew
-  const compatibleVersion = await findCompatibleVersion(
-    remoteVersion.majorVersion,
-  )
-
-  if (compatibleVersion) {
-    const altPath = await getDirectBinaryPath(
-      'pg_dump',
-      compatibleVersion.majorVersion,
-    )
-    return {
-      compatible: false,
-      localToolVersion: localVersion,
-      remoteDbVersion: remoteVersion,
-      requiredAction: 'use_direct_path',
-      alternativePath: altPath || undefined,
-      switchTarget: compatibleVersion.majorVersion,
-    }
-  }
-
-  // Check if we could switch Homebrew (version is installed but not as direct path)
-  const installed = await detectInstalledPostgres()
-  const hasTarget = installed.some(
-    (v) => parseInt(v.majorVersion, 10) >= remoteVersion.majorVersion,
-  )
-
-  if (hasTarget) {
-    const best = installed
-      .filter((v) => parseInt(v.majorVersion, 10) >= remoteVersion.majorVersion)
-      .sort(
-        (a, b) => parseInt(a.majorVersion, 10) - parseInt(b.majorVersion, 10),
-      )[0]
-
-    return {
-      compatible: false,
-      localToolVersion: localVersion,
-      remoteDbVersion: remoteVersion,
-      requiredAction: 'switch_homebrew',
-      switchTarget: best.majorVersion,
-    }
-  }
-
-  // Need to install - provide platform-specific instructions
-  const installCmd = await getInstallCommand(targetMajor)
-  return {
-    compatible: false,
-    localToolVersion: localVersion,
-    remoteDbVersion: remoteVersion,
-    requiredAction: 'install',
-    switchTarget: targetMajor,
-    error:
-      `Your pg_dump version (${localVersion.major}) cannot dump from PostgreSQL ${remoteVersion.majorVersion}. ` +
-      `Install PostgreSQL ${targetMajor} client tools: ${installCmd}`,
-  }
-}
-
-export async function getInstallCommand(majorVersion: string): Promise<string> {
-  const pm = await detectPackageManager()
-
-  if (!pm) {
-    return `Install PostgreSQL ${majorVersion} client tools for your platform`
-  }
-
-  // Versioned package names per package manager
-  const packages: Record<string, string> = {
-    brew: `postgresql@${majorVersion}`,
-    apt: `postgresql-client-${majorVersion}`,
-    yum: `postgresql${majorVersion}`,
-    dnf: `postgresql${majorVersion}`,
-    pacman: 'postgresql-libs', // Arch doesn't version packages the same way
-  }
-
-  const pkg = packages[pm.id] || `postgresql-${majorVersion}`
-  return pm.config.installTemplate.replace('{package}', pkg)
-}

package/engines/qdrant/README.md

@@ -1,222 +0,0 @@
-# Qdrant Engine Implementation
-
-## Overview
-
-Qdrant is a vector similarity search engine with a REST API. Unlike traditional databases, Qdrant is interacted with via HTTP, not a CLI shell.
-
-## 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
-```
-qdrant/
-└── bin/
-    └── qdrant           # Server binary
-```
-
-### Version Map Sync
-
-```typescript
-export const QDRANT_VERSION_MAP: Record<string, string> = {
-  '1': '1.16.3',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-Qdrant uses `BaseBinaryManager` with standard configuration.
-
-### Version Parsing
-
-- **Version output format**: `qdrant 1.16.3` or `v1.16.3`
-- **Parse pattern**: `/(?:qdrant\s+)?v?(\d+\.\d+\.\d+)/`
-
-### REST API Engine
-
-Qdrant is a **REST API engine** - it doesn't have a CLI shell:
-- `spindb run` is **NOT applicable**
-- `spindb connect` opens the web dashboard in browser
-- All data operations use HTTP REST API
-
-### Dual Ports
-
-Qdrant uses two ports:
-- **HTTP Port** (default 6333): REST API
-- **gRPC Port** (default 6334): gRPC API (typically HTTP + 1)
-
-### Default Configuration
-
-- **Default HTTP Port**: 6333 (auto-increments on conflict)
-- **gRPC Port**: HTTP port + 1
-- **Health Endpoint**: `/healthz`
-- **Dashboard**: `/dashboard`
-- **PID File**: `qdrant.pid` in container directory
-
-### YAML Configuration
-
-Qdrant uses YAML configuration (`config.yaml`):
-
-```yaml
-storage:
-  storage_path: /path/to/data
-service:
-  http_port: 6333
-  grpc_port: 6334
-```
-
-### Connection String Format
-
-```
-http://127.0.0.1:{port}
-```
-
-### Web Dashboard
-
-Qdrant has a built-in web dashboard at:
-```
-http://localhost:{port}/dashboard
-```
-
-The `connect` command opens this URL in the default browser using platform-specific commands (`open`, `xdg-open`, `cmd /c start`).
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| snapshot | `.snapshot` | REST API | Qdrant native snapshot |
-
-### Snapshot API
-
-Backup and restore use Qdrant's snapshot REST endpoints:
-- `POST /collections/{name}/snapshots` - Create snapshot
-- `PUT /collections/{name}/snapshots/recover` - Restore snapshot
-
-## Integration Test Notes
-
-### REST API Testing
-
-Integration tests use `fetch()` or `curl` for operations, not CLI tools.
-
-### Test Fixtures
-
-Located in `tests/fixtures/qdrant/seeds/`:
-- `README.md` documenting the API-based approach (no SQL/script files)
-
-## Docker E2E Test Notes
-
-Qdrant Docker E2E uses `curl` for all operations:
-
-```bash
-# Health check
-curl http://localhost:6333/healthz
-
-# Create collection
-curl -X PUT http://localhost:6333/collections/test \
-  -H 'Content-Type: application/json' \
-  -d '{"vectors":{"size":4,"distance":"Dot"}}'
-
-# Insert vectors
-curl -X PUT http://localhost:6333/collections/test/points \
-  -H 'Content-Type: application/json' \
-  -d '{"points":[...]}'
-```
-
-### Backup/Restore Skipped in Docker E2E
-
-Qdrant backup/restore tests are skipped in Docker E2E (covered by integration tests).
-
-## Known Issues & Gotchas
-
-### 1. No CLI Shell
-
-`spindb run` does nothing for Qdrant. Use the REST API or web dashboard.
-
-### 2. Vector Database Semantics
-
-Qdrant uses "collections" instead of "databases". Operations are vector-centric:
-- Insert points with vectors
-- Search by vector similarity
-- Filter by payload
-
-### 3. gRPC Port
-
-The gRPC port is separate from HTTP. Ensure both ports are available if using gRPC clients.
-
-### 4. Snapshot Format
-
-Snapshots are Qdrant's native format and are not compatible with other databases.
-
-### 5. Health Check Endpoint
-
-Use `/healthz` (not `/health`) for health checks.
-
-## CI/CD Notes
-
-### curl-Based Testing
-
-CI tests use `curl` commands rather than database CLI tools.
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache Qdrant binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/qdrant-*
-    key: qdrant-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/qdrant/version-maps.ts') }}
-```
-
-## REST API Quick Reference
-
-### Collections
-```bash
-# List collections
-GET /collections
-
-# Create collection
-PUT /collections/{name}
-
-# Delete collection
-DELETE /collections/{name}
-```
-
-### Points (Vectors)
-```bash
-# Upsert points
-PUT /collections/{name}/points
-
-# Search
-POST /collections/{name}/points/search
-
-# Get point
-GET /collections/{name}/points/{id}
-```
-
-### Snapshots
-```bash
-# Create snapshot
-POST /collections/{name}/snapshots
-
-# List snapshots
-GET /collections/{name}/snapshots
-
-# Recover from snapshot
-PUT /collections/{name}/snapshots/recover
-```

package/engines/qdrant/api-client.ts

@@ -1,61 +0,0 @@
-/**
- * Shared Qdrant REST API client utilities
- */
-
-/**
- * Make an HTTP request to Qdrant REST API
- *
- * @param port - The HTTP port Qdrant is listening on
- * @param method - HTTP method (GET, POST, PUT, DELETE)
- * @param path - API path (e.g., '/collections', '/snapshots')
- * @param body - Optional JSON body for POST/PUT requests
- * @param timeoutMs - Request timeout in milliseconds (default: 30s)
- */
-export async function qdrantApiRequest(
-  port: number,
-  method: string,
-  path: string,
-  body?: Record<string, unknown>,
-  timeoutMs = 30000,
-): Promise<{ status: number; data: unknown }> {
-  const url = `http://127.0.0.1:${port}${path}`
-
-  const controller = new AbortController()
-  const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
-
-  const options: RequestInit = {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    signal: controller.signal,
-  }
-
-  if (body) {
-    options.body = JSON.stringify(body)
-  }
-
-  try {
-    const response = await fetch(url, options)
-
-    // Try to parse as JSON, fall back to text for endpoints like /healthz
-    let data: unknown
-    const contentType = response.headers.get('content-type') || ''
-    if (contentType.includes('application/json')) {
-      data = await response.json()
-    } else {
-      data = await response.text()
-    }
-
-    return { status: response.status, data }
-  } catch (error) {
-    if (error instanceof Error && error.name === 'AbortError') {
-      throw new Error(
-        `Qdrant API request timed out after ${timeoutMs / 1000}s: ${method} ${path}`,
-      )
-    }
-    throw error
-  } finally {
-    clearTimeout(timeoutId)
-  }
-}