spindb 0.19.4 → 0.20.1

package/README.md

@@ -269,8 +269,8 @@ psql $(spindb url mydb)
 spindb backup mydb                              # Auto-generated filename
 spindb backup mydb --name production-backup     # Custom name
 spindb backup mydb --output ./backups/          # Custom directory
-spindb backup mydb --format sql                 # SQL text format
-spindb backup mydb --format dump                # Binary format
+spindb backup mydb --format sql                 # SQL text format (PostgreSQL)
+spindb backup mydb --format custom              # Custom binary format (PostgreSQL)
 
 # Restore from backups
 spindb restore mydb backup.dump
@@ -430,7 +430,7 @@ spindb create modern --engine postgresql --db-version 18
 
 # Backup formats
 spindb backup myapp --format sql      # Plain SQL (.sql)
-spindb backup myapp --format dump     # Binary custom format (.dump)
+spindb backup myapp --format custom   # Binary custom format (.dump)
 ```
 
 **Versions:** 15, 16, 17, 18
@@ -563,12 +563,12 @@ Every engine supports backup and restore with engine-specific formats:
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | pg_dump | Human-readable, portable |
-| Custom | `.dump` | pg_dump -Fc | Compressed, faster restore |
+| sql | `.sql` | pg_dump | Human-readable, portable |
+| custom | `.dump` | pg_dump -Fc | Compressed, faster restore |
 
 ```bash
-spindb backup mydb --sql                # Plain SQL
-spindb backup mydb --dump               # Binary custom format
+spindb backup mydb --format sql         # Plain SQL
+spindb backup mydb --format custom      # Binary custom format
 spindb restore mydb backup.dump
 ```
 
@@ -576,23 +576,23 @@ spindb restore mydb backup.dump
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | mysqldump / mariadb-dump | Human-readable |
-| Compressed | `.sql.gz` | mysqldump + gzip | Smaller file size |
+| sql | `.sql` | mysqldump / mariadb-dump | Human-readable |
+| compressed | `.sql.gz` | mysqldump + gzip | Smaller file size |
 
 ```bash
-spindb backup mydb --sql                # Plain SQL
-spindb backup mydb --dump               # Compressed SQL
+spindb backup mydb --format sql         # Plain SQL
+spindb backup mydb --format compressed  # Compressed SQL
 ```
 
 ### MongoDB
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| BSON | `.bson` | mongodump | Binary, preserves all types |
-| Archive | `.archive` | mongodump --archive | Single compressed file |
+| bson | _(directory)_ | mongodump | Binary, preserves all types |
+| archive | `.archive` | mongodump --archive | Single compressed file |
 
 ```bash
-spindb backup mydb                      # BSON directory
+spindb backup mydb --format bson        # BSON directory
 spindb backup mydb --format archive     # Single .archive file
 ```
 
@@ -600,12 +600,12 @@ spindb backup mydb --format archive     # Single .archive file
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| RDB | `.rdb` | BGSAVE | Binary snapshot, requires restart |
-| Text | `.redis` / `.valkey` | Custom | Human-readable commands |
+| rdb | `.rdb` | BGSAVE | Binary snapshot, requires stop/start |
+| text | `.redis` / `.valkey` | Custom | Human-readable commands |
 
 ```bash
-spindb backup mydb --dump               # RDB snapshot
-spindb backup mydb --sql                # Text commands
+spindb backup mydb --format rdb         # RDB snapshot (default)
+spindb backup mydb --format text        # Text commands
 
 # Restore with merge or replace strategy
 spindb restore mydb backup.redis        # Prompts: Replace all / Merge
@@ -615,23 +615,22 @@ spindb restore mydb backup.redis        # Prompts: Replace all / Merge
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | .dump / duckdb | Human-readable |
-| Binary | `.sqlite` / `.duckdb` | File copy | Exact database copy |
+| sql | `.sql` | .dump / duckdb | Human-readable |
+| binary | `.sqlite` / `.duckdb` | File copy | Exact database copy |
 
 ```bash
-spindb backup mydb --sql                # SQL dump
-spindb backup mydb --dump               # Binary copy
+spindb backup mydb --format sql         # SQL dump
+spindb backup mydb --format binary      # Binary copy (default)
 ```
 
 ### ClickHouse
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | clickhouse-client | Plain SQL dump |
-| Native | `.clickhouse` | clickhouse-backup | Native format (future) |
+| sql | `.sql` | clickhouse-client | Plain SQL dump |
 
 ```bash
-spindb backup mydb --sql                # SQL dump
+spindb backup mydb --format sql         # SQL dump (only format)
 ```
 
 ---

package/cli/commands/backup.ts

@@ -14,6 +14,15 @@ import {
 import { createSpinner } from '../ui/spinner'
 import { uiSuccess, uiError, uiWarning, formatBytes } from '../ui/theme'
 import { getMissingDependencies } from '../../core/dependency-manager'
+import { isFileBasedEngine } from '../../types'
+import {
+  getBackupExtension,
+  getBackupSpinnerLabel,
+  getDefaultFormat,
+  isValidFormat,
+  getValidFormats,
+} from '../../config/backup-formats'
+import type { BackupFormatType } from '../../types'
 
 function generateTimestamp(): string {
   const now = new Date()
@@ -28,42 +37,6 @@ function generateDefaultFilename(
   return `${containerName}-${database}-backup-${timestamp}`
 }
 
-function getExtension(format: 'sql' | 'dump', engine: string): string {
-  // Handle 'sql' format (human-readable option)
-  if (format === 'sql') {
-    // MongoDB uses BSON directory format for 'sql' choice
-    return engine === 'mongodb' ? '' : '.sql'
-  }
-
-  // Handle 'dump' format (binary/compressed option)
-  switch (engine) {
-    case 'mysql':
-      return '.sql.gz'
-    case 'sqlite':
-      return '.sqlite'
-    case 'mongodb':
-      return '.archive'
-    case 'redis':
-      return '.rdb'
-    case 'postgresql':
-    default:
-      return '.dump'
-  }
-}
-
-function getFormatDescription(format: 'sql' | 'dump', engine: string): string {
-  if (engine === 'redis') {
-    return 'RDB snapshot'
-  }
-  if (engine === 'mongodb') {
-    return format === 'sql' ? 'BSON directory' : 'archive'
-  }
-  if (engine === 'sqlite') {
-    return format === 'sql' ? 'SQL' : 'binary'
-  }
-  return format === 'sql' ? 'SQL' : 'dump'
-}
-
 export const backupCommand = new Command('backup')
   .description('Create a backup of a database')
   .argument('[container]', 'Container name')
@@ -73,9 +46,7 @@ export const backupCommand = new Command('backup')
     '-o, --output <path>',
     'Output directory (defaults to current directory)',
   )
-  .option('--format <format>', 'Output format: sql or dump')
-  .option('--sql', 'Output as plain SQL (shorthand for --format sql)')
-  .option('--dump', 'Output as dump format (shorthand for --format dump)')
+  .option('--format <format>', 'Backup format (engine-specific, e.g., sql, custom, rdb, binary)')
   .option('-j, --json', 'Output result as JSON')
   .action(
     async (
@@ -85,8 +56,6 @@ export const backupCommand = new Command('backup')
         name?: string
         output?: string
         format?: string
-        sql?: boolean
-        dump?: boolean
         json?: boolean
       },
     ) => {
@@ -130,16 +99,19 @@ export const backupCommand = new Command('backup')
 
         const { engine: engineName } = config
 
-        const running = await processManager.isRunning(containerName, {
-          engine: engineName,
-        })
-        if (!running) {
-          console.error(
-            uiError(
-              `Container "${containerName}" is not running. Start it first.`,
-            ),
-          )
-          process.exit(1)
+        // File-based engines (SQLite, DuckDB) don't need to be "running"
+        if (!isFileBasedEngine(engineName)) {
+          const running = await processManager.isRunning(containerName, {
+            engine: engineName,
+          })
+          if (!running) {
+            console.error(
+              uiError(
+                `Container "${containerName}" is not running. Start it first.`,
+              ),
+            )
+            process.exit(1)
+          }
         }
 
         const engine = getEngine(engineName)
@@ -193,20 +165,26 @@ export const backupCommand = new Command('backup')
           }
         }
 
-        let format: 'sql' | 'dump' = 'sql'
+        let format: BackupFormatType = getDefaultFormat(engineName)
 
-        if (options.sql) {
-          format = 'sql'
-        } else if (options.dump) {
-          format = 'dump'
-        } else if (options.format) {
-          if (options.format !== 'sql' && options.format !== 'dump') {
-            console.error(uiError('Format must be "sql" or "dump"'))
+        if (options.format) {
+          if (!isValidFormat(engineName, options.format)) {
+            const validFormats = getValidFormats(engineName)
+            console.error(
+              uiError(
+                `Invalid format "${options.format}" for ${engineName}. ` +
+                  `Valid formats: ${validFormats.join(', ')}`,
+              ),
+            )
             process.exit(1)
           }
-          format = options.format as 'sql' | 'dump'
+          // Safe to cast: isValidFormat above guarantees the format is valid
+          format = options.format as BackupFormatType
         } else if (!containerArg) {
-          format = await promptBackupFormat(engineName)
+          const selectedFormat = await promptBackupFormat(engineName)
+          if (selectedFormat) {
+            format = selectedFormat
+          }
         }
 
         const defaultFilename = generateDefaultFilename(
@@ -219,13 +197,13 @@ export const backupCommand = new Command('backup')
           filename = await promptBackupFilename(defaultFilename)
         }
 
-        const extension = getExtension(format, engineName)
+        const extension = getBackupExtension(engineName, format)
         const outputDir = options.output || process.cwd()
         const outputPath = join(outputDir, `${filename}${extension}`)
 
-        const formatDesc = getFormatDescription(format, engineName)
+        const spinnerLabel = getBackupSpinnerLabel(engineName, format)
         const backupSpinner = createSpinner(
-          `Creating ${formatDesc} backup of "${databaseName}"...`,
+          `Creating ${spinnerLabel} backup of "${databaseName}"...`,
         )
         backupSpinner.start()
 

package/cli/commands/create.ts

@@ -444,23 +444,40 @@ export const createCommand = new Command('create')
           database = answers.database
         }
 
-        // Redis uses numbered databases (0-15), default to "0"
+        // 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) {
+        if (engine === Engine.Redis || engine === Engine.Valkey) {
           database = database ?? '0'
+          // Validate Redis/Valkey database is a pure integer string 0-15
+          // Reject decimals ("1.5"), scientific notation ("1e2"), and trailing garbage ("5abc")
+          if (!/^[0-9]+$/.test(database)) {
+            console.error(
+              uiError(
+                'Redis/Valkey database must be an integer between 0 and 15',
+              ),
+            )
+            process.exit(1)
+          }
+          const dbIndex = parseInt(database, 10)
+          if (dbIndex < 0 || dbIndex > 15) {
+            console.error(
+              uiError(
+                'Redis/Valkey database must be an integer between 0 and 15',
+              ),
+            )
+            process.exit(1)
+          }
         } else {
           database = database ?? containerName.replace(/-/g, '_')
-        }
-
-        // Validate database name to prevent SQL injection
-        // Skip for Redis which uses numbered databases (0-15)
-        if (engine !== Engine.Redis && !isValidDatabaseName(database)) {
-          console.error(
-            uiError(
-              'Database name must start with a letter and contain only letters, numbers, and underscores',
-            ),
-          )
-          process.exit(1)
+          // Validate database name to prevent SQL injection
+          if (!isValidDatabaseName(database)) {
+            console.error(
+              uiError(
+                'Database name must start with a letter and contain only letters, numbers, and underscores',
+              ),
+            )
+            process.exit(1)
+          }
         }
 
         console.log(header('Creating Database Container'))

package/cli/commands/deps.ts

@@ -13,6 +13,7 @@ import {
   getCurrentPlatform,
   type DependencyStatus,
 } from '../../core/dependency-manager'
+import { Platform } from '../../types'
 import {
   engineDependencies,
   getEngineDependencies,
@@ -134,7 +135,7 @@ depsCommand
       console.log()
 
       const platform = getCurrentPlatform()
-      if (platform === 'darwin') {
+      if (platform === Platform.Darwin) {
         console.log(chalk.gray('  macOS: Install Homebrew first:'))
         console.log(
           chalk.cyan(

package/cli/commands/engines.ts

@@ -10,7 +10,7 @@ import { containerManager } from '../../core/container-manager'
 import { processManager } from '../../core/process-manager'
 import { configManager } from '../../core/config-manager'
 import { getEngine } from '../../engines'
-import { binaryManager } from '../../core/binary-manager'
+import { postgresqlBinaryManager } from '../../engines/postgresql/binary-manager'
 import { paths } from '../../config/paths'
 import { platformService } from '../../core/platform-service'
 import {
@@ -41,7 +41,7 @@ import {
   type InstalledRedisEngine,
   type InstalledValkeyEngine,
 } from '../helpers'
-import { Engine } from '../../types'
+import { Engine, Platform } from '../../types'
 import {
   loadEnginesJson,
   type EngineConfig,
@@ -969,7 +969,7 @@ enginesCommand
 
         // Show the path for reference
         const { platform, arch } = platformService.getPlatformInfo()
-        const fullVersion = binaryManager.getFullVersion(version)
+        const fullVersion = postgresqlBinaryManager.getFullVersion(version)
         const binPath = paths.getBinaryPath({
           engine: 'postgresql',
           version: fullVersion,
@@ -1290,7 +1290,7 @@ enginesCommand
       if (['clickhouse', 'ch'].includes(normalizedEngine)) {
         // Check platform support
         const { platform } = platformService.getPlatformInfo()
-        if (platform === 'win32') {
+        if (platform === Platform.Win32) {
           console.error(
             uiError('ClickHouse is not supported on Windows via hostdb'),
           )

package/cli/commands/menu/backup-handlers.ts

@@ -10,8 +10,6 @@ import { platformService } from '../../../core/platform-service'
 import { portManager } from '../../../core/port-manager'
 import { getEngine } from '../../../engines'
 import { defaults } from '../../../config/defaults'
-import { getPostgresHomebrewPackage } from '../../../config/engine-defaults'
-import { updatePostgresClientTools } from '../../../engines/postgresql/binary-manager'
 import {
   getBackupExtension,
   getBackupSpinnerLabel,
@@ -667,90 +665,25 @@ export async function handleRestore(): Promise<void> {
         )
         console.log()
 
-        const { shouldUpgrade } = await inquirer.prompt({
-          type: 'list',
-          name: 'shouldUpgrade',
-          message: `Would you like to upgrade PostgreSQL client tools to support PostgreSQL ${requiredVersion}?`,
-          choices: [
-            { name: 'Yes', value: true },
-            { name: 'No', value: false },
-          ],
-          default: 0,
-        })
-
-        if (shouldUpgrade) {
-          console.log()
-          const upgradeSpinner = createSpinner(
-            'Upgrading PostgreSQL client tools...',
-          )
-          upgradeSpinner.start()
-
-          try {
-            const updateSuccess = await updatePostgresClientTools()
-
-            if (updateSuccess) {
-              upgradeSpinner.succeed('PostgreSQL client tools upgraded')
-              console.log()
-              console.log(
-                uiSuccess(
-                  'Please try the restore again with the updated tools.',
-                ),
-              )
-              await pressEnterToContinue()
-              return
-            } else {
-              upgradeSpinner.fail('Upgrade failed')
-              console.log()
-              console.log(
-                uiError('Automatic upgrade failed. Please upgrade manually:'),
-              )
-              const pgPackage = getPostgresHomebrewPackage()
-              const latestMajor = pgPackage.split('@')[1]
-              console.log(
-                uiWarning(
-                  `  macOS: brew install ${pgPackage} && brew link --force ${pgPackage}`,
-                ),
-              )
-              console.log(
-                chalk.gray(
-                  `    This installs PostgreSQL ${latestMajor} client tools: pg_restore, pg_dump, psql, and libpq`,
-                ),
-              )
-              console.log(
-                uiWarning(
-                  `  Ubuntu/Debian: sudo apt update && sudo apt install postgresql-client-${latestMajor}`,
-                ),
-              )
-              console.log(
-                chalk.gray(
-                  `    This installs PostgreSQL ${latestMajor} client tools: pg_restore, pg_dump, psql, and libpq`,
-                ),
-              )
-              await pressEnterToContinue()
-              return
-            }
-          } catch {
-            upgradeSpinner.fail('Upgrade failed')
-            console.log(uiError('Failed to upgrade PostgreSQL client tools'))
-            console.log(
-              chalk.gray(
-                'Manual upgrade may be required for pg_restore, pg_dump, and psql',
-              ),
-            )
-            await pressEnterToContinue()
-            return
-          }
-        } else {
-          console.log()
-          console.log(
-            uiWarning(
-              'Restore cancelled. Please upgrade PostgreSQL client tools manually and try again.',
-            ),
-          )
-          await pressEnterToContinue()
-          return
-        }
+        console.log()
+        console.log(
+          uiWarning(
+            `To restore this backup, download PostgreSQL ${requiredVersion} binaries:`,
+          ),
+        )
+        console.log(
+          chalk.cyan(`  spindb engines download postgresql ${requiredVersion}`),
+        )
+        console.log()
+        console.log(
+          chalk.gray(
+            'Then create a new container with that version and try the restore again.',
+          ),
+        )
+        await pressEnterToContinue()
+        return
       } else {
+        // Other restore errors - show warnings
         restoreSpinner.warn('Restore completed with warnings')
         if (result.stderr) {
           console.log()