spindb 0.34.3 → 0.35.2

package/README.md

@@ -38,7 +38,7 @@ SpinDB supports **18 database engines** across **5 platform architectures**—al
 | 🪶 **SQLite** | Embedded SQL | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🦆 **DuckDB** | Embedded OLAP | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🍃 **MongoDB** | Document Store | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🦔 **FerretDB** | Document Store | ✅ | ✅ | ✅ | ✅ | ❌ |
+| 🦔 **FerretDB** | Document Store | ✅ | ✅ | ✅ | ✅ | ⚠️ |
 | 🔴 **Redis** | Key-Value | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🔷 **Valkey** | Key-Value | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🏠 **ClickHouse** | Columnar OLAP | ✅ | ✅ | ✅ | ✅ | ❌ |
@@ -51,9 +51,9 @@ SpinDB supports **18 database engines** across **5 platform architectures**—al
 | 🤖 **TypeDB** | Knowledge Graph | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 📈 **InfluxDB** | Time-Series | ✅ | ✅ | ✅ | ✅ | ✅ |
 
-**88 combinations. One CLI. Zero configuration.**
+**89 combinations. One CLI. Zero configuration.**
 
-> ClickHouse and FerretDB are available on Windows via WSL.
+> ClickHouse is available on Windows via WSL. FerretDB v1 is natively supported on Windows (uses plain PostgreSQL backend); v2 requires macOS/Linux.
 
 ---
 
@@ -272,7 +272,7 @@ See [DEPLOY.md](DEPLOY.md) for comprehensive deployment documentation.
 
 - **Local only** - Databases bind to `127.0.0.1`. Remote connection support planned for v1.1.
 - **ClickHouse Windows** - Not supported (hostdb doesn't build for Windows).
-- **FerretDB Windows** - Not supported (postgresql-documentdb has startup issues on Windows).
+- **FerretDB Windows** - v1 supported natively (plain PostgreSQL backend). v2 not supported (postgresql-documentdb has startup issues); use WSL for v2.
 - **Qdrant, Meilisearch, CouchDB** - Use REST API instead of CLI shell. Access via HTTP at the configured port.
 
 ---

package/cli/commands/attach.ts

@@ -2,14 +2,24 @@ import { Command } from 'commander'
 import { existsSync } from 'fs'
 import { resolve, basename } from 'path'
 import chalk from 'chalk'
-import { sqliteRegistry } from '../../engines/sqlite/registry'
 import { containerManager } from '../../core/container-manager'
-import { deriveContainerName } from '../../engines/sqlite/scanner'
+import {
+  detectEngineFromPath,
+  getRegistryForEngine,
+  deriveContainerName,
+  formatAllExtensions,
+} from '../../engines/file-based-utils'
 import { uiSuccess, uiError } from '../ui/theme'
+import type { Engine } from '../../types'
 
 export const attachCommand = new Command('attach')
-  .description('Register an existing SQLite database with SpinDB')
-  .argument('<path>', 'Path to SQLite database file')
+  .description(
+    'Register an existing file-based database with SpinDB (SQLite or DuckDB)',
+  )
+  .argument(
+    '<path>',
+    'Path to database file (.sqlite, .db, .sqlite3, .duckdb, .ddb)',
+  )
   .option('-n, --name <name>', 'Container name (defaults to filename)')
   .option('--json', 'Output as JSON')
   .action(
@@ -20,6 +30,20 @@ export const attachCommand = new Command('attach')
       try {
         const absolutePath = resolve(path)
 
+        // Detect engine from file extension
+        const engine = detectEngineFromPath(absolutePath)
+        if (!engine) {
+          const msg = `Unrecognized file extension. Expected one of: ${formatAllExtensions()}`
+          if (options.json) {
+            console.log(JSON.stringify({ success: false, error: msg }))
+          } else {
+            console.error(uiError(msg))
+          }
+          process.exit(1)
+        }
+
+        const registry = getRegistryForEngine(engine)
+
         // Verify file exists
         if (!existsSync(absolutePath)) {
           if (options.json) {
@@ -33,8 +57,8 @@ export const attachCommand = new Command('attach')
         }
 
         // Check if already registered
-        if (await sqliteRegistry.isPathRegistered(absolutePath)) {
-          const entry = await sqliteRegistry.getByPath(absolutePath)
+        if (await registry.isPathRegistered(absolutePath)) {
+          const entry = await registry.getByPath(absolutePath)
           if (options.json) {
             console.log(
               JSON.stringify({
@@ -53,7 +77,11 @@ export const attachCommand = new Command('attach')
 
         // Determine container name
         const containerName =
-          options.name || deriveContainerName(basename(absolutePath))
+          options.name ||
+          deriveContainerName(
+            basename(absolutePath),
+            engine as Engine.SQLite | Engine.DuckDB,
+          )
 
         // Check if container name exists
         if (await containerManager.exists(containerName)) {
@@ -73,7 +101,7 @@ export const attachCommand = new Command('attach')
         }
 
         // Register the file
-        await sqliteRegistry.add({
+        await registry.add({
           name: containerName,
           filePath: absolutePath,
           created: new Date().toISOString(),
@@ -83,6 +111,7 @@ export const attachCommand = new Command('attach')
           console.log(
             JSON.stringify({
               success: true,
+              engine,
               name: containerName,
               filePath: absolutePath,
             }),
@@ -90,7 +119,7 @@ export const attachCommand = new Command('attach')
         } else {
           console.log(
             uiSuccess(
-              `Registered "${basename(absolutePath)}" as "${containerName}"`,
+              `Registered "${basename(absolutePath)}" as "${containerName}" (${engine})`,
             ),
           )
           console.log()

package/cli/commands/backups.ts

@@ -44,6 +44,9 @@ function detectBackupType(filename: string): {
     case '.db':
     case '.sqlite3':
       return { engine: 'sqlite', format: 'Binary copy' }
+    case '.duckdb':
+    case '.ddb':
+      return { engine: 'duckdb', format: 'Binary copy' }
     case '.archive':
       return { engine: 'mongodb', format: 'BSON archive' }
     case '.rdb':
@@ -65,6 +68,8 @@ function isBackupFile(filename: string): boolean {
     '.sqlite',
     '.sqlite3',
     '.db',
+    '.duckdb',
+    '.ddb',
     '.archive',
     '.rdb',
     '.redis',

package/cli/commands/connect.ts

@@ -26,7 +26,7 @@ import { getEngine } from '../../engines'
 import { getEngineDefaults } from '../../config/defaults'
 import { promptContainerSelect } from '../ui/prompts'
 import { uiError, uiWarning, uiInfo, uiSuccess } from '../ui/theme'
-import { Engine } from '../../types'
+import { Engine, isFileBasedEngine } from '../../types'
 import { configManager } from '../../core/config-manager'
 import { DBLAB_ENGINES, getDblabArgs } from '../../core/dblab-utils'
 import { downloadDblabCli } from './menu/shell-handlers'
@@ -86,9 +86,9 @@ export const connectCommand = new Command('connect')
 
         if (!containerName) {
           const containers = await containerManager.list()
-          // SQLite containers are always "available" if file exists, server containers need to be running
+          // File-based containers are always "available" if file exists, server containers need to be running
           const connectable = containers.filter((c) => {
-            if (c.engine === Engine.SQLite) {
+            if (isFileBasedEngine(c.engine)) {
               return existsSync(c.database)
             }
             return c.status === 'running'
@@ -131,11 +131,11 @@ export const connectCommand = new Command('connect')
         const database =
           options.database ?? config.database ?? engineDefaults.superuser
 
-        // SQLite: check file exists instead of running status
-        if (engineName === Engine.SQLite) {
+        // File-based engines: check file exists instead of running status
+        if (isFileBasedEngine(engineName)) {
           if (!existsSync(config.database)) {
             console.error(
-              uiError(`SQLite database file not found: ${config.database}`),
+              uiError(`Database file not found: ${config.database}`),
             )
             process.exit(1)
           }

package/cli/commands/create.ts

@@ -22,7 +22,11 @@ import { startWithRetry } from '../../core/start-with-retry'
 import { TransactionManager } from '../../core/transaction-manager'
 import { isValidDatabaseName, exitWithError } from '../../core/error-handler'
 import { resolve } from 'path'
-import { Engine } from '../../types'
+import { Engine, Platform } from '../../types'
+import {
+  FERRETDB_VERSION_MAP,
+  isV1 as isFerretDBv1,
+} from '../../engines/ferretdb/version-maps'
 import type { BaseEngine } from '../../engines/base-engine'
 
 /**
@@ -535,6 +539,23 @@ export const createCommand = new Command('create')
           database = answers.database
         }
 
+        // FerretDB: force v1 on Windows (v2 requires postgresql-documentdb, not available on Windows)
+        // Runs after both CLI and interactive paths have resolved engine + version
+        if (
+          engine === Engine.FerretDB &&
+          !isFerretDBv1(version) &&
+          platformService.getPlatformInfo().platform === Platform.Win32
+        ) {
+          version = FERRETDB_VERSION_MAP['1']
+          if (!options.json) {
+            console.log(
+              chalk.yellow(
+                `  FerretDB v2 is not supported on Windows — using v1 (${version})`,
+              ),
+            )
+          }
+        }
+
         // Redis/Valkey use numbered databases (0-15), default to "0"
         // Other engines default to container name (with hyphens replaced by underscores for SQL compatibility)
         if (engine === Engine.Redis || engine === Engine.Valkey) {

package/cli/commands/detach.ts

@@ -1,13 +1,15 @@
 import { Command } from 'commander'
 import chalk from 'chalk'
-import { sqliteRegistry } from '../../engines/sqlite/registry'
 import { containerManager } from '../../core/container-manager'
+import { getRegistryForEngine } from '../../engines/file-based-utils'
 import { promptConfirm } from '../ui/prompts'
 import { uiSuccess, uiError, uiWarning } from '../ui/theme'
-import { Engine } from '../../types'
+import { isFileBasedEngine } from '../../types'
 
 export const detachCommand = new Command('detach')
-  .description('Unregister a SQLite database from SpinDB (keeps file on disk)')
+  .description(
+    'Unregister a file-based database from SpinDB (keeps file on disk)',
+  )
   .argument('<name>', 'Container name')
   .option('-f, --force', 'Skip confirmation prompt')
   .option('--json', 'Output as JSON')
@@ -31,18 +33,22 @@ export const detachCommand = new Command('detach')
           process.exit(1)
         }
 
-        // Verify it's a SQLite container
-        if (config.engine !== Engine.SQLite) {
+        // Verify it's a file-based container
+        if (!isFileBasedEngine(config.engine)) {
           if (options.json) {
             console.log(
               JSON.stringify({
                 success: false,
                 error:
-                  'Not a SQLite container. Use "spindb delete" for server databases.',
+                  'Not a file-based container. Use "spindb delete" for server databases.',
               }),
             )
           } else {
-            console.error(uiError(`"${name}" is not a SQLite container`))
+            console.error(
+              uiError(
+                `"${name}" is not a file-based container (SQLite/DuckDB)`,
+              ),
+            )
             console.log(
               chalk.gray(
                 '  Use "spindb delete" for server databases (PostgreSQL, MySQL)',
@@ -64,11 +70,12 @@ export const detachCommand = new Command('detach')
           }
         }
 
-        const entry = await sqliteRegistry.get(name)
+        const registry = getRegistryForEngine(config.engine)
+        const entry = await registry.get(name)
         const filePath = entry?.filePath
 
         // Remove from registry only (not the file)
-        await sqliteRegistry.remove(name)
+        await registry.remove(name)
 
         if (options.json) {
           console.log(

package/cli/commands/doctor.ts

@@ -24,7 +24,7 @@ import { paths } from '../../config/paths'
 import { getSupportedEngines } from '../../config/engine-defaults'
 import { checkEngineDependencies } from '../../core/dependency-manager'
 import { header, uiSuccess } from '../ui/theme'
-import { Engine } from '../../types'
+import { type Engine, isFileBasedEngine } from '../../types'
 import {
   findOutdatedContainers,
   migrateContainerVersion,
@@ -178,7 +178,7 @@ async function checkContainers(): Promise<HealthCheckResult> {
     }
 
     const details = Object.entries(byEngine).map(([engine, counts]) => {
-      if (engine === Engine.SQLite) {
+      if (isFileBasedEngine(engine as Engine)) {
         return `${engine}: ${counts.running} exist, ${counts.stopped} missing`
       }
       return `${engine}: ${counts.running} running, ${counts.stopped} stopped`

package/cli/commands/duckdb.ts

@@ -0,0 +1,273 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { existsSync } from 'fs'
+import { resolve, basename } from 'path'
+import { duckdbRegistry } from '../../engines/duckdb/registry'
+import {
+  scanForUnregisteredDuckDBFiles,
+  deriveContainerName,
+} from '../../engines/duckdb/scanner'
+import {
+  isValidExtensionForEngine,
+  formatExtensionsForEngine,
+} from '../../engines/file-based-utils'
+import { containerManager } from '../../core/container-manager'
+import { uiSuccess, uiError, uiInfo } from '../ui/theme'
+import { Engine } from '../../types'
+import { detachCommand } from './detach'
+
+export const duckdbCommand = new Command('duckdb').description(
+  'DuckDB-specific operations',
+)
+
+// duckdb scan
+duckdbCommand
+  .command('scan')
+  .description('Scan folder for unregistered DuckDB files')
+  .option('-p, --path <dir>', 'Directory to scan (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action(async (options: { path?: string; json?: boolean }): Promise<void> => {
+    const dir = options.path ? resolve(options.path) : process.cwd()
+
+    if (!existsSync(dir)) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({ error: 'Directory not found', directory: dir }),
+        )
+      } else {
+        console.error(uiError(`Directory not found: ${dir}`))
+      }
+      process.exit(1)
+    }
+
+    const unregistered = await scanForUnregisteredDuckDBFiles(dir)
+
+    if (options.json) {
+      console.log(JSON.stringify({ directory: dir, files: unregistered }))
+      return
+    }
+
+    if (unregistered.length === 0) {
+      console.log(uiInfo(`No unregistered DuckDB files found in ${dir}`))
+      return
+    }
+
+    console.log(
+      chalk.cyan(`Found ${unregistered.length} unregistered DuckDB file(s):`),
+    )
+    for (const file of unregistered) {
+      console.log(chalk.gray(`  ${file.fileName}`))
+    }
+    console.log()
+    console.log(chalk.gray('  Register with: spindb attach <path>'))
+  })
+
+// duckdb ignore
+duckdbCommand
+  .command('ignore')
+  .description('Add folder to ignore list for CWD scanning')
+  .argument('[folder]', 'Folder path to ignore (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      folder: string | undefined,
+      options: { json?: boolean },
+    ): Promise<void> => {
+      const absolutePath = resolve(folder || process.cwd())
+      await duckdbRegistry.addIgnoreFolder(absolutePath)
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, folder: absolutePath }))
+      } else {
+        console.log(uiSuccess(`Added to ignore list: ${absolutePath}`))
+      }
+    },
+  )
+
+// duckdb unignore
+duckdbCommand
+  .command('unignore')
+  .description('Remove folder from ignore list')
+  .argument('[folder]', 'Folder path to unignore (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      folder: string | undefined,
+      options: { json?: boolean },
+    ): Promise<void> => {
+      const absolutePath = resolve(folder || process.cwd())
+      const removed = await duckdbRegistry.removeIgnoreFolder(absolutePath)
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: removed, folder: absolutePath }))
+      } else {
+        if (removed) {
+          console.log(uiSuccess(`Removed from ignore list: ${absolutePath}`))
+        } else {
+          console.log(uiInfo(`Folder was not in ignore list: ${absolutePath}`))
+        }
+      }
+    },
+  )
+
+// duckdb ignored (list ignored folders)
+duckdbCommand
+  .command('ignored')
+  .description('List ignored folders')
+  .option('--json', 'Output as JSON')
+  .action(async (options: { json?: boolean }): Promise<void> => {
+    const folders = await duckdbRegistry.listIgnoredFolders()
+
+    if (options.json) {
+      console.log(JSON.stringify({ folders }))
+      return
+    }
+
+    if (folders.length === 0) {
+      console.log(uiInfo('No folders are being ignored'))
+      return
+    }
+
+    console.log(chalk.cyan('Ignored folders:'))
+    for (const folder of folders) {
+      console.log(chalk.gray(`  ${folder}`))
+    }
+  })
+
+// duckdb attach (alias to top-level attach)
+duckdbCommand
+  .command('attach')
+  .description(
+    'Register an existing DuckDB database (alias for "spindb attach")',
+  )
+  .argument('<path>', 'Path to DuckDB database file')
+  .option('-n, --name <name>', 'Container name')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      path: string,
+      options: { name?: string; json?: boolean },
+    ): Promise<void> => {
+      try {
+        const absolutePath = resolve(path)
+
+        // Validate extension matches DuckDB
+        if (!isValidExtensionForEngine(absolutePath, Engine.DuckDB)) {
+          const msg = `File extension must be one of: ${formatExtensionsForEngine(Engine.DuckDB)}`
+          if (options.json) {
+            console.log(JSON.stringify({ success: false, error: msg }))
+          } else {
+            console.error(uiError(msg))
+            console.log(
+              chalk.gray(
+                '  For SQLite files, use: spindb sqlite attach <path>',
+              ),
+            )
+          }
+          process.exit(1)
+        }
+
+        if (!existsSync(absolutePath)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({ success: false, error: 'File not found' }),
+            )
+          } else {
+            console.error(uiError(`File not found: ${absolutePath}`))
+          }
+          process.exit(1)
+        }
+
+        if (await duckdbRegistry.isPathRegistered(absolutePath)) {
+          const entry = await duckdbRegistry.getByPath(absolutePath)
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Already registered',
+                existingName: entry?.name,
+              }),
+            )
+          } else {
+            console.error(
+              uiError(`File is already registered as "${entry?.name}"`),
+            )
+          }
+          process.exit(1)
+        }
+
+        const containerName =
+          options.name || deriveContainerName(basename(absolutePath))
+
+        if (await containerManager.exists(containerName)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Container name already exists',
+              }),
+            )
+          } else {
+            console.error(
+              uiError(`Container "${containerName}" already exists`),
+            )
+          }
+          process.exit(1)
+        }
+
+        await duckdbRegistry.add({
+          name: containerName,
+          filePath: absolutePath,
+          created: new Date().toISOString(),
+        })
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              success: true,
+              name: containerName,
+              filePath: absolutePath,
+            }),
+          )
+        } else {
+          console.log(
+            uiSuccess(
+              `Registered "${basename(absolutePath)}" as "${containerName}"`,
+            ),
+          )
+          console.log()
+          console.log(chalk.gray('  Connect with:'))
+          console.log(chalk.cyan(`    spindb connect ${containerName}`))
+        }
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )
+
+// duckdb detach (alias to top-level detach)
+duckdbCommand
+  .command('detach')
+  .description('Unregister a DuckDB database (alias for "spindb detach")')
+  .argument('<name>', 'Container name')
+  .option('-f, --force', 'Skip confirmation')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      name: string,
+      options: { force?: boolean; json?: boolean },
+    ): Promise<void> => {
+      // Build args array
+      const args = ['node', 'detach', name]
+      if (options.force) args.push('-f')
+      if (options.json) args.push('--json')
+
+      await detachCommand.parseAsync(args, { from: 'node' })
+    },
+  )