spindb 0.31.2 → 0.31.3

package/cli/commands/databases.ts

@@ -437,6 +437,90 @@ databasesCommand
     },
   )
 
+// Refresh databases from server - queries the actual database server
+databasesCommand
+  .command('refresh')
+  .description(
+    'Refresh tracking by querying the database server for actual databases',
+  )
+  .argument('<container>', 'Container name')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (container: string, options: { json?: boolean }) => {
+    try {
+      const config = await containerManager.getConfig(container)
+      if (!config) {
+        if (options.json) {
+          console.log(
+            JSON.stringify(
+              { error: `Container "${container}" not found` },
+              null,
+              2,
+            ),
+          )
+        } else {
+          console.error(uiError(`Container "${container}" not found`))
+        }
+        process.exit(1)
+      }
+
+      const beforeDatabases = config.databases || [config.database]
+      const afterDatabases = await containerManager.syncDatabases(container)
+
+      // Calculate changes
+      const added = afterDatabases.filter((db) => !beforeDatabases.includes(db))
+      const removed = beforeDatabases.filter(
+        (db) => !afterDatabases.includes(db),
+      )
+
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              success: true,
+              container,
+              databases: afterDatabases,
+              changes: {
+                added: added.length > 0 ? added : undefined,
+                removed: removed.length > 0 ? removed : undefined,
+              },
+            },
+            null,
+            2,
+          ),
+        )
+      } else {
+        if (added.length === 0 && removed.length === 0) {
+          console.log(chalk.gray(`Registry already in sync for "${container}"`))
+        } else {
+          console.log(
+            uiSuccess(`Refreshed database tracking for "${container}"`),
+          )
+          if (added.length > 0) {
+            console.log(chalk.green(`  Added: ${added.join(', ')}`))
+          }
+          if (removed.length > 0) {
+            console.log(chalk.yellow(`  Removed: ${removed.join(', ')}`))
+          }
+        }
+        console.log()
+        console.log(chalk.bold('Current databases:'))
+        for (const db of afterDatabases) {
+          const isPrimary = db === config.database
+          const label = isPrimary ? chalk.gray(' (primary)') : ''
+          console.log(`  ${chalk.cyan(db)}${label}`)
+        }
+      }
+    } catch (error) {
+      const e = error as Error
+      if (options.json) {
+        console.log(JSON.stringify({ error: e.message }, null, 2))
+      } else {
+        console.error(uiError(e.message))
+      }
+      process.exit(1)
+    }
+  })
+
 // Set the default/primary database for a container
 databasesCommand
   .command('set-default')

package/cli/commands/start.ts

@@ -9,8 +9,8 @@ import { getEngineDefaults } from '../../config/defaults'
 import { promptContainerSelect, promptConfirm } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
 import { uiWarning } from '../ui/theme'
-import { Engine } from '../../types'
-import { exitWithError } from '../../core/error-handler'
+import { Engine, isFileBasedEngine } from '../../types'
+import { exitWithError, logDebug } from '../../core/error-handler'
 
 export const startCommand = new Command('start')
   .description('Start a container')
@@ -174,6 +174,18 @@ export const startCommand = new Command('start')
         }
       }
 
+      // Sync database registry with actual server state (silent, non-blocking)
+      if (!isFileBasedEngine(config.engine)) {
+        try {
+          await containerManager.syncDatabases(containerName)
+        } catch (syncError) {
+          // Don't fail start if sync fails - just log for debugging
+          logDebug(
+            `Failed to sync databases for ${containerName}: ${syncError}`,
+          )
+        }
+      }
+
       const connectionString = engine.getConnectionString(config)
 
       if (options.json) {

package/core/container-manager.ts

@@ -13,13 +13,13 @@ import { paths } from '../config/paths'
 import { processManager } from './process-manager'
 import { portManager } from './port-manager'
 import { isWindows } from './platform-service'
-import { logDebug } from './error-handler'
+import { logDebug, UnsupportedOperationError } from './error-handler'
 import { getEngineDefaults, getSupportedEngines } from '../config/defaults'
 import { getEngine } from '../engines'
 import { sqliteRegistry } from '../engines/sqlite/registry'
 import { duckdbRegistry } from '../engines/duckdb/registry'
 import type { ContainerConfig } from '../types'
-import { Engine } from '../types'
+import { Engine, isFileBasedEngine } from '../types'
 
 export type CreateOptions = {
   engine: Engine
@@ -712,6 +712,72 @@ export class ContainerManager {
     }
   }
 
+  /**
+   * Sync the databases array with the actual databases on the server.
+   * Queries the database server for all user databases and updates the registry.
+   *
+   * @param containerName - The container to sync
+   * @returns The updated list of databases
+   * @throws Error if the container is not running or doesn't support listing databases
+   */
+  async syncDatabases(containerName: string): Promise<string[]> {
+    const config = await this.getConfig(containerName)
+    if (!config) {
+      throw new Error(`Container "${containerName}" not found`)
+    }
+
+    // File-based engines don't have multiple databases to sync
+    if (isFileBasedEngine(config.engine)) {
+      return config.databases || [config.database]
+    }
+
+    // Container must be running to query databases
+    const running = await processManager.isRunning(containerName, {
+      engine: config.engine,
+    })
+    if (!running) {
+      throw new Error(
+        `Container "${containerName}" is not running. Start it first to sync databases.`,
+      )
+    }
+
+    const engine = getEngine(config.engine)
+
+    // Query the actual database server for all databases
+    let actualDatabases: string[]
+    try {
+      actualDatabases = await engine.listDatabases(config)
+    } catch (error) {
+      // If the engine doesn't support listDatabases, return current registry
+      if (error instanceof UnsupportedOperationError) {
+        logDebug(
+          `listDatabases not supported for ${config.engine}, skipping sync`,
+        )
+        return config.databases || [config.database]
+      }
+      throw error
+    }
+
+    // Ensure primary database is always included
+    if (!actualDatabases.includes(config.database)) {
+      actualDatabases = [config.database, ...actualDatabases]
+    }
+
+    // Sort for consistent ordering (primary database first, then alphabetical)
+    const sortedDatabases = [
+      config.database,
+      ...actualDatabases
+        .filter((db) => db !== config.database)
+        .sort((a, b) => a.localeCompare(b)),
+    ]
+
+    // Update the registry
+    config.databases = sortedDatabases
+    await this.saveConfig(containerName, { engine: config.engine }, config)
+
+    return sortedDatabases
+  }
+
   getConnectionString(config: ContainerConfig, database?: string): string {
     const engine = getEngine(config.engine)
     return engine.getConnectionString(config, database)

package/core/error-handler.ts

@@ -136,6 +136,27 @@ export class MissingToolError extends Error {
   }
 }
 
+/**
+ * Error thrown when an operation is not supported by an engine.
+ * For example, listDatabases on engines that don't have the concept of databases.
+ */
+export class UnsupportedOperationError extends Error {
+  public readonly operation: string
+  public readonly engine: string
+
+  constructor(operation: string, engine: string, message?: string) {
+    super(
+      message ??
+        `${operation} is not supported for ${engine}. ` +
+          `This engine may use a different concept (collections, indexes, etc.).`,
+    )
+    this.name = 'UnsupportedOperationError'
+    this.operation = operation
+    this.engine = engine
+    Error.captureStackTrace(this, UnsupportedOperationError)
+  }
+}
+
 function getLogPath(): string {
   return join(getSpinDBRoot(), 'spindb.log')
 }

package/core/pull-manager.ts

@@ -123,7 +123,7 @@ export class PullManager {
     // Track whether to keep backup in final result (user didn't specify --no-backup)
     const keepBackup = !options.noBackup
 
-    return withTransaction(async (tx) => {
+    const result = await withTransaction(async (tx) => {
       // --- BACKUP ORIGINAL (always if post-script, otherwise if not --no-backup) ---
       if (needsBackup) {
         // Step 1: Create backup database
@@ -217,12 +217,7 @@ export class PullManager {
         createDatabase: false,
       })
 
-      // Step 9: Update registry (add backup if we're keeping it)
-      if (keepBackup) {
-        await containerManager.addDatabase(config.name, backupDatabase)
-      }
-
-      // Step 10: Cleanup temp files
+      // Step 9: Cleanup temp files
       try {
         await unlink(tempOriginalDump)
       } catch {
@@ -234,7 +229,7 @@ export class PullManager {
         // Ignore errors
       }
 
-      // Step 11: Run post-script if provided
+      // Step 10: Run post-script if provided
       if (options.postScript) {
         const context: PullContext = {
           container: config.name,
@@ -278,6 +273,19 @@ export class PullManager {
           : `Pulled remote data into "${targetDatabase}"`,
       }
     })
+
+    // Sync registry with actual databases on server after transaction commits
+    // This captures the backup database (if kept) and any other databases
+    // Wrapped in try/catch to avoid affecting the main pull result on transient failures
+    try {
+      await containerManager.syncDatabases(config.name)
+    } catch (error) {
+      logDebug(
+        `Failed to sync databases for "${config.name}": ${error instanceof Error ? error.message : error}`,
+      )
+    }
+
+    return result
   }
 
   private async executeCloneMode(
@@ -335,17 +343,14 @@ export class PullManager {
         createDatabase: false,
       })
 
-      // Step 5: Update registry
-      await containerManager.addDatabase(config.name, targetDatabase)
-
-      // Step 6: Cleanup
+      // Step 5: Cleanup
       try {
         await unlink(tempRemoteDump)
       } catch {
         // Ignore errors
       }
 
-      // Step 7: Run post-script if provided
+      // Step 6: Run post-script if provided
       if (options.postScript) {
         const context: PullContext = {
           container: config.name,
@@ -360,6 +365,16 @@ export class PullManager {
         await this.runPostScript(options.postScript, context)
       }
 
+      // Step 7: Sync registry with actual databases on server
+      // Wrapped in try/catch to avoid rolling back a successful clone on transient failures
+      try {
+        await containerManager.syncDatabases(config.name)
+      } catch (error) {
+        logDebug(
+          `Failed to sync databases for "${config.name}": ${error instanceof Error ? error.message : error}`,
+        )
+      }
+
       return {
         success: true,
         mode: 'clone' as const,

package/engines/base-engine.ts

@@ -10,6 +10,7 @@ import type {
   QueryResult,
   QueryOptions,
 } from '../types'
+import { UnsupportedOperationError } from '../core/error-handler'
 
 /**
  * Base class for database engines
@@ -263,4 +264,21 @@ export abstract class BaseEngine {
     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)
+  }
 }

package/engines/clickhouse/index.ts

@@ -1185,6 +1185,65 @@ export class ClickHouseEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all user databases, excluding system databases (system, information_schema, INFORMATION_SCHEMA).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port, version } = container
+    const clickhouse = await this.getClickHouseClientPath(version)
+
+    logDebug(`Listing databases on port ${port} with version ${version}`)
+
+    return new Promise((resolve, reject) => {
+      const args = [
+        'client',
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--query',
+        'SHOW DATABASES',
+      ]
+
+      const proc = spawn(clickhouse, args, {
+        stdio: ['ignore', '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) {
+          reject(new Error(stderr || `clickhouse exited with code ${code}`))
+          return
+        }
+
+        // Parse output (one database per line)
+        const systemDatabases = [
+          'system',
+          'information_schema',
+          'INFORMATION_SCHEMA',
+        ]
+        const databases = stdout
+          .trim()
+          .split('\n')
+          .map((db) => db.trim())
+          .filter((db) => db.length > 0 && !systemDatabases.includes(db))
+
+        resolve(databases)
+      })
+    })
+  }
 }
 
 export const clickhouseEngine = new ClickHouseEngine()

package/engines/cockroachdb/index.ts

@@ -1148,6 +1148,59 @@ export class CockroachDBEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all user databases, excluding system databases (defaultdb, postgres, system).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port, version } = container
+    const cockroach = await this.getCockroachPath(version)
+
+    return new Promise((resolve, reject) => {
+      const args = [
+        'sql',
+        '--insecure',
+        '--host',
+        `127.0.0.1:${port}`,
+        '--execute',
+        `SHOW DATABASES`,
+        '--format=csv',
+      ]
+
+      const proc = spawn(cockroach, args, {
+        stdio: ['ignore', '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) {
+          reject(new Error(stderr || `cockroach sql exited with code ${code}`))
+          return
+        }
+
+        // Parse CSV output (first column is database_name, skip header)
+        const systemDatabases = ['defaultdb', 'postgres', 'system']
+        const lines = stdout.trim().split('\n')
+        const databases = lines
+          .slice(1) // Skip header
+          .map((line) => line.split(',')[0].trim())
+          .filter((db) => db.length > 0 && !systemDatabases.includes(db))
+
+        resolve(databases)
+      })
+    })
+  }
 }
 
 export const cockroachdbEngine = new CockroachDBEngine()

package/engines/couchdb/index.ts

@@ -1253,6 +1253,29 @@ export class CouchDBEngine extends BaseEngine {
 
     return parseRESTAPIResult(JSON.stringify(response.data))
   }
+
+  /**
+   * List all user databases, excluding system databases (_users, _replicator, _global_changes).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+
+    const response = await couchdbApiRequest(port, 'GET', '/_all_dbs')
+
+    if (response.status >= 400) {
+      throw new Error(
+        `CouchDB API error (${response.status}): ${JSON.stringify(response.data)}`,
+      )
+    }
+
+    const allDatabases = response.data as string[]
+    const systemDatabases = ['_users', '_replicator', '_global_changes']
+    const databases = allDatabases.filter(
+      (db) => !systemDatabases.includes(db) && !db.startsWith('_'),
+    )
+
+    return databases
+  }
 }
 
 export const couchdbEngine = new CouchDBEngine()

package/engines/duckdb/index.ts

@@ -804,6 +804,16 @@ export class DuckDBEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List databases for DuckDB.
+   * DuckDB is file-based with one database per file.
+   * Returns the configured database (file path) as a single-item array.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    // DuckDB is file-based, one database per file
+    return [container.database]
+  }
 }
 
 export const duckdbEngine = new DuckDBEngine()

package/engines/ferretdb/index.ts

@@ -1283,6 +1283,63 @@ export class FerretDBEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all user databases, excluding system databases (admin, config, local).
+   * FerretDB uses MongoDB protocol, so same approach as MongoDB.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+    const mongosh = await this.getMongoshPath()
+
+    return new Promise((resolve, reject) => {
+      // Use JSON output for reliable parsing
+      const script = `JSON.stringify(db.adminCommand({listDatabases: 1}).databases.map(d => d.name))`
+      const args = [
+        '--quiet',
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--eval',
+        script,
+      ]
+
+      const proc = spawn(mongosh, args, {
+        stdio: ['ignore', '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) {
+          reject(new Error(stderr || `mongosh exited with code ${code}`))
+          return
+        }
+
+        try {
+          const allDatabases = JSON.parse(stdout.trim()) as string[]
+          const systemDatabases = ['admin', 'config', 'local']
+          const databases = allDatabases.filter(
+            (db) => !systemDatabases.includes(db),
+          )
+          resolve(databases)
+        } catch (error) {
+          reject(new Error(`Failed to parse database list: ${error}`))
+        }
+      })
+    })
+  }
 }
 
 export const ferretdbEngine = new FerretDBEngine()

package/engines/mariadb/index.ts

@@ -1112,6 +1112,62 @@ export class MariaDBEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all user databases, excluding system databases
+   * (information_schema, mysql, performance_schema, sys).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+    const mariadb = await this.getMariadbClientPath()
+
+    // Query for all non-system databases
+    const sql = `SHOW DATABASES WHERE \`Database\` NOT IN ('information_schema', 'mysql', 'performance_schema', 'sys')`
+
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-P',
+      String(port),
+      '-u',
+      engineDef.superuser,
+      '-N', // Skip column names
+      '-B', // Batch mode (no formatting)
+      '-e',
+      sql,
+    ]
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn(mariadb, 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) {
+          const databases = stdout
+            .trim()
+            .split('\n')
+            .map((db) => db.trim())
+            .filter((db) => db.length > 0)
+          resolve(databases)
+        } else {
+          reject(new Error(stderr || `mariadb exited with code ${code}`))
+        }
+      })
+    })
+  }
 }
 
 export const mariadbEngine = new MariaDBEngine()

package/engines/meilisearch/index.ts

@@ -1166,6 +1166,31 @@ export class MeilisearchEngine extends BaseEngine {
 
     return parseRESTAPIResult(JSON.stringify(response.data))
   }
+
+  /**
+   * List databases for Meilisearch.
+   * Meilisearch uses indexes, so we query the /indexes endpoint.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+
+    try {
+      const response = await meilisearchApiRequest(port, 'GET', '/indexes')
+      if (response.status === 200 && response.data) {
+        // Response is { results: [{ uid: "index_name", ... }, ...], ... }
+        const data = response.data as { results?: Array<{ uid: string }> }
+        if (Array.isArray(data.results)) {
+          const indexes = data.results.map((index) => index.uid)
+          return indexes.length > 0 ? indexes : [container.database]
+        }
+      }
+      // Fall back to configured database
+      return [container.database]
+    } catch {
+      // On error, fall back to configured database
+      return [container.database]
+    }
+  }
 }
 
 export const meilisearchEngine = new MeilisearchEngine()

package/engines/mongodb/index.ts

@@ -983,6 +983,54 @@ export class MongoDBEngine extends BaseEngine {
 
     return parseMongoDBResult(jsonMatch[0])
   }
+
+  /**
+   * List all user databases, excluding system databases (admin, config, local).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+    const mongosh = await this.getMongoshPath()
+
+    return new Promise((resolve, reject) => {
+      // Use JSON output for reliable parsing
+      const script = `JSON.stringify(db.adminCommand({listDatabases: 1}).databases.map(d => d.name))`
+      const args = ['--quiet', '--host', `127.0.0.1:${port}`, '--eval', script]
+
+      const proc = spawn(mongosh, args, {
+        stdio: ['ignore', '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) {
+          reject(new Error(stderr || `mongosh exited with code ${code}`))
+          return
+        }
+
+        try {
+          const allDatabases = JSON.parse(stdout.trim()) as string[]
+          const systemDatabases = ['admin', 'config', 'local']
+          const databases = allDatabases.filter(
+            (db) => !systemDatabases.includes(db),
+          )
+          resolve(databases)
+        } catch (error) {
+          reject(new Error(`Failed to parse database list: ${error}`))
+        }
+      })
+    })
+  }
 }
 
 export const mongodbEngine = new MongoDBEngine()

package/engines/mysql/index.ts

@@ -1196,6 +1196,62 @@ export class MySQLEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all user databases, excluding system databases
+   * (information_schema, mysql, performance_schema, sys).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+    const mysql = await this.getMysqlClientPath()
+
+    // Query for all non-system databases
+    const sql = `SHOW DATABASES WHERE \`Database\` NOT IN ('information_schema', 'mysql', 'performance_schema', 'sys')`
+
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-P',
+      String(port),
+      '-u',
+      engineDef.superuser,
+      '-N', // Skip column names
+      '-B', // Batch mode (no formatting)
+      '-e',
+      sql,
+    ]
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn(mysql, 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) {
+          const databases = stdout
+            .trim()
+            .split('\n')
+            .map((db) => db.trim())
+            .filter((db) => db.length > 0)
+          resolve(databases)
+        } else {
+          reject(new Error(stderr || `mysql exited with code ${code}`))
+        }
+      })
+    })
+  }
 }
 
 export const mysqlEngine = new MySQLEngine()

package/engines/postgresql/index.ts

@@ -983,6 +983,66 @@ export class PostgreSQLEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all user databases, excluding system databases (template0, template1, postgres).
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port } = container
+    const psqlPath = await this.getPsqlPath()
+
+    // Query pg_database for all non-system databases
+    const sql = `SELECT datname FROM pg_database WHERE datname NOT IN ('template0', 'template1', 'postgres') AND datistemplate = false ORDER BY datname`
+
+    const args = [
+      '-X', // Skip ~/.psqlrc
+      '-h',
+      '127.0.0.1',
+      '-p',
+      String(port),
+      '-U',
+      defaults.superuser,
+      '-d',
+      'postgres',
+      '-t', // Tuples only (no headers)
+      '-A', // Unaligned output
+      '-c',
+      sql,
+    ]
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn(psqlPath, 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', (err: NodeJS.ErrnoException) => {
+        reject(err)
+      })
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          const databases = stdout
+            .trim()
+            .split('\n')
+            .map((db) => db.trim())
+            .filter((db) => db.length > 0)
+          resolve(databases)
+        } else {
+          reject(new Error(stderr || `psql exited with code ${code}`))
+        }
+      })
+    })
+  }
 }
 
 export const postgresqlEngine = new PostgreSQLEngine()

package/engines/qdrant/index.ts

@@ -1192,6 +1192,16 @@ export class QdrantEngine extends BaseEngine {
 
     return parseRESTAPIResult(JSON.stringify(response.data))
   }
+
+  /**
+   * List databases for Qdrant.
+   * Qdrant uses collections, not databases. Returns the configured database.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    // Qdrant uses collections, not databases
+    // Return the container's configured database
+    return [container.database]
+  }
 }
 
 export const qdrantEngine = new QdrantEngine()

package/engines/questdb/index.ts

@@ -1008,6 +1008,16 @@ export class QuestDBEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List databases for QuestDB.
+   * QuestDB has a single database 'qdb'. Returns the configured database.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    // QuestDB has a single database 'qdb'
+    // Return the container's configured database
+    return [container.database]
+  }
 }
 
 export const questdbEngine = new QuestDBEngine()

package/engines/redis/index.ts

@@ -1423,6 +1423,17 @@ export class RedisEngine extends BaseEngine {
       proc.stdin?.end()
     })
   }
+
+  /**
+   * List databases for Redis.
+   * Redis uses numbered databases (0-15 by default), not named databases.
+   * Returns the configured database number as a single-item array.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    // Redis has numbered databases, not named ones
+    // Return the container's configured database
+    return [container.database]
+  }
 }
 
 export const redisEngine = new RedisEngine()

package/engines/sqlite/index.ts

@@ -696,6 +696,16 @@ export class SQLiteEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List databases for SQLite.
+   * SQLite is file-based with one database per file.
+   * Returns the configured database (file path) as a single-item array.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    // SQLite is file-based, one database per file
+    return [container.database]
+  }
 }
 
 export const sqliteEngine = new SQLiteEngine()

package/engines/surrealdb/index.ts

@@ -1070,6 +1070,77 @@ export class SurrealDBEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * List all databases in the container's namespace.
+   * SurrealDB has a namespace > database hierarchy.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    const { port, version, name } = container
+    const surreal = await this.getSurrealPath(version)
+    const namespace = name.replace(/-/g, '_')
+
+    return new Promise((resolve, reject) => {
+      const args = [
+        'sql',
+        '--endpoint',
+        `ws://127.0.0.1:${port}`,
+        '--user',
+        'root',
+        '--pass',
+        'root',
+        '--ns',
+        namespace,
+        '--db',
+        container.database,
+        '--hide-welcome',
+        '--json',
+      ]
+
+      const proc = spawn(surreal, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: paths.getContainerPath(name, { engine: ENGINE }),
+      })
+
+      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)
+
+      // Send the INFO FOR NS query to list databases
+      proc.stdin?.write('INFO FOR NS;\n')
+      proc.stdin?.end()
+
+      proc.on('close', (code) => {
+        if (code !== 0) {
+          reject(new Error(stderr || `surreal sql exited with code ${code}`))
+          return
+        }
+
+        try {
+          // Parse JSON output - INFO FOR NS returns database info
+          const results = JSON.parse(stdout)
+          if (Array.isArray(results) && results[0]?.result?.databases) {
+            const databases = Object.keys(results[0].result.databases)
+            resolve(databases)
+          } else {
+            // No databases found or different format
+            resolve([container.database])
+          }
+        } catch {
+          // If parsing fails, return the configured database
+          resolve([container.database])
+        }
+      })
+    })
+  }
 }
 
 export const surrealdbEngine = new SurrealDBEngine()

package/engines/valkey/index.ts

@@ -1450,6 +1450,17 @@ export class ValkeyEngine extends BaseEngine {
       proc.stdin?.end()
     })
   }
+
+  /**
+   * List databases for Valkey.
+   * Valkey uses numbered databases (0-15 by default), not named databases.
+   * Returns the configured database number as a single-item array.
+   */
+  async listDatabases(container: ContainerConfig): Promise<string[]> {
+    // Valkey has numbered databases, not named ones
+    // Return the container's configured database
+    return [container.database]
+  }
 }
 
 export const valkeyEngine = new ValkeyEngine()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.31.2",
+  "version": "0.31.3",
   "author": "Bob Bass <bob@bbass.co>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",