spindb 0.32.2 → 0.34.0

package/core/docker-exporter.ts

@@ -71,6 +71,7 @@ function getEngineDisplayName(engine: Engine): string {
     [Engine.SurrealDB]: 'SurrealDB',
     [Engine.QuestDB]: 'QuestDB',
     [Engine.TypeDB]: 'TypeDB',
+    [Engine.InfluxDB]: 'InfluxDB',
   }
   return displayNames[engine] || engine
 }
@@ -141,6 +142,9 @@ const _ENGINE_BINARY_CONFIG: Record<
   [Engine.TypeDB]: {
     primaryBinaries: ['typedb', 'typedb_console_bin'],
   },
+  [Engine.InfluxDB]: {
+    primaryBinaries: [], // REST API only, no CLI tools
+  },
 }
 
 /**
@@ -193,6 +197,7 @@ function getConnectionStringTemplate(
       return useTLS ? `https://<host>:${port}` : `http://<host>:${port}`
 
     case Engine.Meilisearch:
+    case Engine.InfluxDB:
       return useTLS ? `https://<host>:${port}` : `http://<host>:${port}`
 
     case Engine.CouchDB:
@@ -492,6 +497,13 @@ echo "User configured via server settings"
       userCreationCommands = `
 # API key is configured at server start
 echo "API key configured via server settings"
+`
+      break
+
+    case Engine.InfluxDB:
+      userCreationCommands = `
+# InfluxDB 3.x local dev runs without authentication
+echo "No authentication required for local InfluxDB 3.x"
 `
       break
 
@@ -1284,6 +1296,7 @@ export async function getDockerConnectionString(
       return `http://${host}:${port}`
 
     case Engine.Meilisearch:
+    case Engine.InfluxDB:
       return `http://${host}:${port}`
 
     case Engine.CouchDB:

package/core/pgweb-utils.ts

@@ -0,0 +1,62 @@
+import { existsSync } from 'fs'
+import { readFile, unlink } from 'fs/promises'
+import { join } from 'path'
+import { platformService } from './platform-service'
+import { paths } from '../config/paths'
+
+/** Pinned pgweb version — single source of truth for download URL */
+export const PGWEB_VERSION = '0.17.0'
+
+/**
+ * Check if pgweb is running for a container.
+ * Reads pgweb.pid/pgweb.port files and verifies the process is alive.
+ * Cleans up stale PID/port files if the process is dead.
+ */
+export async function getPgwebStatus(
+  containerName: string,
+  engine: string,
+): Promise<{ running: boolean; port?: number; pid?: number }> {
+  const containerDir = paths.getContainerPath(containerName, { engine })
+  const pidFile = join(containerDir, 'pgweb.pid')
+  const portFile = join(containerDir, 'pgweb.port')
+
+  if (!existsSync(pidFile)) return { running: false }
+
+  try {
+    const pid = parseInt(await readFile(pidFile, 'utf8'), 10)
+    if (platformService.isProcessRunning(pid)) {
+      const port = parseInt(await readFile(portFile, 'utf8'), 10)
+      return { running: true, port, pid }
+    }
+  } catch {
+    // PID file invalid or process dead
+  }
+
+  // Clean up stale files
+  await unlink(pidFile).catch(() => {})
+  await unlink(portFile).catch(() => {})
+  return { running: false }
+}
+
+/**
+ * Stop a running pgweb process for a container (no UI output).
+ * Returns true if a process was stopped, false if nothing was running.
+ */
+export async function stopPgweb(
+  containerName: string,
+  engine: string,
+): Promise<boolean> {
+  const status = await getPgwebStatus(containerName, engine)
+  if (!status.running || !status.pid) return false
+
+  try {
+    await platformService.terminateProcess(status.pid, false)
+  } catch {
+    // Already gone
+  }
+
+  const containerDir = paths.getContainerPath(containerName, { engine })
+  await unlink(join(containerDir, 'pgweb.pid')).catch(() => {})
+  await unlink(join(containerDir, 'pgweb.port')).catch(() => {})
+  return true
+}

package/engines/base-engine.ts

@@ -13,6 +13,7 @@ import type {
   UserCredentials,
 } from '../types'
 import { UnsupportedOperationError } from '../core/error-handler'
+import { stopPgweb } from '../core/pgweb-utils'
 
 /**
  * Base class for database engines
@@ -267,6 +268,14 @@ export abstract class BaseEngine {
     // 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

package/engines/cockroachdb/index.ts

@@ -506,6 +506,9 @@ export class CockroachDBEngine extends BaseEngine {
       }
     }
 
+    // Kill pgweb if running for this container
+    await this.stopPgweb(name)
+
     logDebug('CockroachDB stopped')
   }
 

package/engines/ferretdb/index.ts

@@ -622,41 +622,57 @@ export class FerretDBEngine extends BaseEngine {
     let ferretStarted = false
 
     try {
-      // 1. Start PostgreSQL
+      // 1. Start PostgreSQL (skip if already running)
       onProgress?.({
         stage: 'starting',
         message: 'Starting PostgreSQL backend...',
       })
 
-      // Use pg_ctl to start PostgreSQL
-      // Add 60s timeout to prevent hanging if PostgreSQL fails to start (especially on Windows)
+      // Check if PostgreSQL backend is already running in this data dir
+      let pgAlreadyRunning = false
       try {
-        await spawnAsync(
-          pgCtl,
-          [
-            'start',
-            '-D',
-            pgDataDir,
-            '-l',
-            pgLogFile,
-            '-o',
-            `-p ${backendPort} -h 127.0.0.1`,
-            '-w', // Wait for startup
-          ],
-          { env: pgSpawnEnv, timeout: 60000 },
-        )
-      } catch (pgError) {
-        // Read PostgreSQL log for debugging
-        let pgLog = ''
+        await spawnAsync(pgCtl, ['status', '-D', pgDataDir], {
+          env: pgSpawnEnv,
+          timeout: 5000,
+        })
+        // pg_ctl status exits 0 if server is running
+        pgAlreadyRunning = true
+        logDebug('PostgreSQL backend already running, skipping start')
+      } catch {
+        // Exit code != 0 means not running — proceed to start
+      }
+
+      if (!pgAlreadyRunning) {
+        // Use pg_ctl to start PostgreSQL
+        // Add 60s timeout to prevent hanging if PostgreSQL fails to start (especially on Windows)
         try {
-          pgLog = await readFile(pgLogFile, 'utf8')
-        } catch {
-          pgLog = '(no log available)'
+          await spawnAsync(
+            pgCtl,
+            [
+              'start',
+              '-D',
+              pgDataDir,
+              '-l',
+              pgLogFile,
+              '-o',
+              `-p ${backendPort} -h 127.0.0.1`,
+              '-w', // Wait for startup
+            ],
+            { env: pgSpawnEnv, timeout: 60000 },
+          )
+        } catch (pgError) {
+          // Read PostgreSQL log for debugging
+          let pgLog = ''
+          try {
+            pgLog = await readFile(pgLogFile, 'utf8')
+          } catch {
+            pgLog = '(no log available)'
+          }
+          throw new Error(
+            `PostgreSQL backend failed to start: ${pgError instanceof Error ? pgError.message : pgError}\n` +
+              `PostgreSQL log:\n${pgLog.slice(-2000)}`, // Last 2KB of log
+          )
         }
-        throw new Error(
-          `PostgreSQL backend failed to start: ${pgError instanceof Error ? pgError.message : pgError}\n` +
-            `PostgreSQL log:\n${pgLog.slice(-2000)}`, // Last 2KB of log
-        )
       }
 
       pgStarted = true
@@ -880,6 +896,9 @@ export class FerretDBEngine extends BaseEngine {
       await this.stopPostgreSQLProcess(pgCtl, pgDataDir, pgSpawnEnv)
     }
 
+    // Kill pgweb if running for this container
+    await this.stopPgweb(name)
+
     logDebug('FerretDB stopped')
   }
 

package/engines/index.ts

@@ -15,6 +15,7 @@ import { cockroachdbEngine } from './cockroachdb'
 import { surrealdbEngine } from './surrealdb'
 import { questdbEngine } from './questdb'
 import { typedbEngine } from './typedb'
+import { influxdbEngine } from './influxdb'
 import { platformService } from '../core/platform-service'
 import { Engine, Platform } from '../types'
 import type { BaseEngine } from './base-engine'
@@ -80,6 +81,9 @@ export const engines: Record<string, BaseEngine> = {
   // TypeDB and aliases
   [Engine.TypeDB]: typedbEngine,
   tdb: typedbEngine,
+  // InfluxDB and aliases
+  [Engine.InfluxDB]: influxdbEngine,
+  influx: influxdbEngine,
 }
 
 // Get an engine by name

package/engines/influxdb/README.md

@@ -0,0 +1,180 @@
+# InfluxDB Engine Implementation
+
+## Overview
+
+InfluxDB 3.x is a time-series database rewritten in Rust. It uses a REST API for all operations (no CLI client). InfluxDB 3.x supports SQL queries via its HTTP API, unlike earlier versions which used InfluxQL/Flux.
+
+## 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
+```text
+influxdb/
+├── influxdb3           # Server binary
+├── python/             # Bundled Python runtime
+│   └── lib/
+│       └── libpython3.13.dylib
+├── LICENSE-APACHE
+└── LICENSE-MIT
+```
+
+### Binary + Python Runtime
+InfluxDB 3.x ships as a single `influxdb3` binary that acts as the server, bundled with a Python runtime. The binary uses `@executable_path/python/lib/libpython3.13.dylib`, so the `python/` directory must be co-located with the binary. The custom `moveExtractedEntries` override ensures both end up in `bin/`. There is no separate CLI client — all interactions use the REST API.
+
+### Version Map Sync
+
+```typescript
+export const INFLUXDB_VERSION_MAP: Record<string, string> = {
+  '3': '3.8.0',
+}
+```
+
+## Implementation Details
+
+### Binary Manager
+
+InfluxDB uses `BaseBinaryManager` since it's a server-based engine with single-digit major versions:
+
+```typescript
+class InfluxDBBinaryManager extends BaseBinaryManager {
+  protected readonly config = {
+    engine: Engine.InfluxDB,
+    engineName: 'influxdb',
+    displayName: 'InfluxDB',
+    serverBinary: 'influxdb3',
+  }
+}
+```
+
+### REST API Engine
+
+InfluxDB is a **REST API engine**:
+- `spindb run` is **NOT applicable** (scriptFileLabel is `null`)
+- `spindb connect` opens the health endpoint info in terminal
+- All operations use HTTP REST API
+
+### Default Configuration
+
+- **Default Port**: 8086
+- **Health Endpoint**: `GET /health`
+- **SQL Query Endpoint**: `POST /api/v3/query_sql`
+- **Write Endpoint**: `POST /api/v3/write_lp`
+- **No Authentication**: InfluxDB 3.x local dev has no auth by default
+- **PID File**: `influxdb.pid` in container directory
+
+### Database Creation
+
+InfluxDB 3.x creates databases **implicitly on first write**. There is no explicit `CREATE DATABASE` command. When you write data with a database name, it's auto-created.
+
+### Connection String Format
+
+```text
+http://127.0.0.1:{port}
+```
+
+## Backup & Restore
+
+### Backup Formats
+
+| Format | Extension | Method | Notes |
+|--------|-----------|--------|-------|
+| sql | `.sql` | REST API | SQL dump with CREATE TABLE + INSERT statements |
+
+### Backup Method
+
+Uses InfluxDB's SQL query API to export data:
+1. `SHOW TABLES` — lists all tables/measurements
+2. `SELECT * FROM {table}` — exports all data per table
+3. Generates SQL INSERT statements for restore
+
+### Restore Method
+
+Parses SQL dump file and executes statements via `POST /api/v3/query_sql`.
+
+## Integration Test Notes
+
+### REST API Testing
+
+Integration tests use `fetch()` to interact with InfluxDB REST API.
+
+### Test Fixtures
+
+Located in `tests/fixtures/influxdb/seeds/`:
+- `README.md` documenting the API-based approach
+
+## Known Issues & Gotchas
+
+### 1. No CLI Client
+
+InfluxDB 3.x has no bundled CLI client. All operations use the HTTP REST API. The `clientTools` array in engine-defaults is empty.
+
+### 2. Implicit Database Creation
+
+Databases are created on first write, not via explicit commands. `createDatabase()` verifies server health but doesn't create anything.
+
+### 3. SQL Query Support
+
+InfluxDB 3.x supports SQL queries (not InfluxQL or Flux from v1/v2). Query via:
+```bash
+curl -X POST http://localhost:8086/api/v3/query_sql \
+  -H "Content-Type: application/json" \
+  -d '{"db":"mydb","q":"SELECT * FROM measurement","format":"json"}'
+```
+
+### 4. Write via Line Protocol
+
+Data writes use InfluxDB line protocol format:
+```bash
+curl -X POST "http://localhost:8086/api/v3/write_lp?db=mydb" \
+  -H "Content-Type: text/plain" \
+  -d 'measurement,tag=value field=123'
+```
+
+### 5. Windows PID Handling
+
+On Windows, uses `platformService.findProcessByPort(port)` after startup to find the real PID, similar to QuestDB/TypeDB pattern.
+
+## REST API Quick Reference
+
+### Health
+```bash
+GET /health
+```
+
+### Query (SQL)
+```bash
+POST /api/v3/query_sql
+Content-Type: application/json
+{"db":"mydb","q":"SELECT 1","format":"json"}
+```
+
+### Write (Line Protocol)
+```bash
+POST /api/v3/write_lp?db=mydb
+Content-Type: text/plain
+measurement,tag=value field=123
+```
+
+### Show Tables
+```bash
+POST /api/v3/query_sql
+{"db":"mydb","q":"SHOW TABLES","format":"json"}
+```
+
+### List Databases
+```bash
+GET /api/v3/configure/database?format=json
+```

package/engines/influxdb/api-client.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared InfluxDB REST API client utilities
+ */
+
+/**
+ * Make an HTTP request to InfluxDB REST API
+ *
+ * @param port - The HTTP port InfluxDB is listening on
+ * @param method - HTTP method (GET, POST, PUT, DELETE)
+ * @param path - API path (e.g., '/health', '/api/v3/query_sql')
+ * @param body - Optional body: object for JSON, string for text/plain (line protocol)
+ * @param timeoutMs - Request timeout in milliseconds (default: 30s)
+ */
+export async function influxdbApiRequest(
+  port: number,
+  method: string,
+  path: string,
+  body?: Record<string, unknown> | string,
+  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,
+    signal: controller.signal,
+  }
+
+  if (body !== undefined) {
+    if (typeof body === 'string') {
+      options.headers = { 'Content-Type': 'text/plain' }
+      options.body = body
+    } else {
+      options.headers = { 'Content-Type': 'application/json' }
+      options.body = JSON.stringify(body)
+    }
+  }
+
+  try {
+    const response = await fetch(url, options)
+
+    // Try to parse as JSON, fall back to text for endpoints like /health
+    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(
+        `InfluxDB API request timed out after ${timeoutMs / 1000}s: ${method} ${path}`,
+      )
+    }
+    throw error
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}

package/engines/influxdb/backup.ts

@@ -0,0 +1,160 @@
+/**
+ * InfluxDB backup module
+ * Supports SQL-based backup using InfluxDB's REST API to export data
+ */
+
+import { mkdir, stat, writeFile } from 'fs/promises'
+import { existsSync } from 'fs'
+import { dirname } from 'path'
+import { logDebug } from '../../core/error-handler'
+import { influxdbApiRequest } from './api-client'
+import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
+
+/**
+ * Create an SQL backup using InfluxDB's REST API
+ * Queries all tables and exports data as SQL INSERT statements
+ */
+export async function createBackup(
+  container: ContainerConfig,
+  outputPath: string,
+  options: BackupOptions,
+): Promise<BackupResult> {
+  const { port } = container
+  const database = options.database || container.database
+
+  // Ensure output directory exists
+  const outputDir = dirname(outputPath)
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true })
+  }
+
+  logDebug(
+    `Creating InfluxDB SQL backup via REST API on port ${port} for database "${database}"`,
+  )
+
+  // Get list of tables in the database
+  const tablesResponse = await influxdbApiRequest(
+    port,
+    'POST',
+    '/api/v3/query_sql',
+    {
+      db: database,
+      q: 'SHOW TABLES',
+      format: 'json',
+    },
+  )
+
+  if (tablesResponse.status !== 200) {
+    throw new Error(
+      `Failed to list tables: ${JSON.stringify(tablesResponse.data)}`,
+    )
+  }
+
+  const tablesData = tablesResponse.data as Array<Record<string, unknown>>
+  const tables: string[] = []
+
+  // Extract user table names: include rows with 'iox' schema or no schema field,
+  // skip system schemas (information_schema, system, etc.)
+  if (Array.isArray(tablesData)) {
+    for (const row of tablesData) {
+      const schema = row.table_schema as string | undefined
+      if (schema && schema !== 'iox') continue
+      const tableName =
+        (row.table_name as string) ||
+        (row.name as string) ||
+        (Object.values(row)[0] as string)
+      if (tableName) {
+        tables.push(tableName)
+      }
+    }
+  }
+
+  logDebug(`Found ${tables.length} tables: ${tables.join(', ')}`)
+
+  // Build SQL dump
+  let sqlContent = `-- InfluxDB SQL Backup\n`
+  sqlContent += `-- Database: ${database}\n`
+  sqlContent += `-- Created: ${new Date().toISOString()}\n\n`
+
+  for (const table of tables) {
+    logDebug(`Exporting table: ${table}`)
+
+    // Query column metadata to identify tag columns
+    // Tags use Dictionary(Int32, Utf8) type in InfluxDB 3.x
+    const tagColumns: string[] = []
+    try {
+      const colResponse = await influxdbApiRequest(
+        port,
+        'POST',
+        '/api/v3/query_sql',
+        {
+          db: database,
+          q: `SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '${table.replace(/'/g, "''")}'`,
+          format: 'json',
+        },
+      )
+      if (colResponse.status === 200 && Array.isArray(colResponse.data)) {
+        for (const col of colResponse.data as Array<Record<string, unknown>>) {
+          const dataType = String(col.data_type || '')
+          if (dataType.includes('Dictionary')) {
+            tagColumns.push(String(col.column_name))
+          }
+        }
+      }
+    } catch {
+      logDebug(`Warning: Could not query column metadata for ${table}`)
+    }
+
+    // Query all data from the table
+    const dataResponse = await influxdbApiRequest(
+      port,
+      'POST',
+      '/api/v3/query_sql',
+      {
+        db: database,
+        q: `SELECT * FROM "${table.replace(/"/g, '""')}"`,
+        format: 'json',
+      },
+    )
+
+    if (dataResponse.status !== 200) {
+      logDebug(
+        `Warning: Failed to export table ${table}: ${JSON.stringify(dataResponse.data)}`,
+      )
+      continue
+    }
+
+    const rows = dataResponse.data as Array<Record<string, unknown>>
+
+    if (Array.isArray(rows) && rows.length > 0) {
+      sqlContent += `-- Table: ${table}\n`
+      if (tagColumns.length > 0) {
+        sqlContent += `-- Tags: ${tagColumns.join(', ')}\n`
+      }
+
+      for (const row of rows) {
+        const columns = Object.keys(row)
+        const values = columns.map((col) => {
+          const val = row[col]
+          if (val === null || val === undefined) return 'NULL'
+          if (typeof val === 'number') return String(val)
+          if (typeof val === 'boolean') return val ? 'true' : 'false'
+          return `'${String(val).replace(/'/g, "''")}'`
+        })
+        sqlContent += `INSERT INTO "${table.replace(/"/g, '""')}" (${columns.map((c) => `"${c.replace(/"/g, '""')}"`).join(', ')}) VALUES (${values.join(', ')});\n`
+      }
+      sqlContent += '\n'
+    }
+  }
+
+  // Write SQL content to file
+  await writeFile(outputPath, sqlContent, 'utf-8')
+
+  const stats = await stat(outputPath)
+
+  return {
+    path: outputPath,
+    format: 'sql',
+    size: stats.size,
+  }
+}