spindb 0.5.3 → 0.5.5

package/README.md

@@ -10,7 +10,7 @@ Spin up local PostgreSQL and MySQL databases without Docker. A lightweight alter
 - **Interactive menu** - Arrow-key navigation for all operations
 - **Auto port management** - Automatically finds available ports
 - **Clone containers** - Duplicate databases with all data
-- **Backup restore** - Restore pg_dump/mysqldump backups
+- **Backup & restore** - Create and restore pg_dump/mysqldump backups
 - **Custom database names** - Specify database name separate from container name
 - **Engine management** - View installed PostgreSQL versions and free up disk space
 - **Dynamic version selection** - Fetches available PostgreSQL versions from Maven Central
@@ -48,9 +48,10 @@ spindb connect mydb
 | `spindb info [name]` | Show container details (or all containers) |
 | `spindb start [name]` | Start a container |
 | `spindb stop [name]` | Stop a container |
-| `spindb connect [name]` | Connect with psql/mysql shell |
+| `spindb connect [name]` | Connect with psql/mysql shell (`--pgcli`/`--mycli` for enhanced) |
 | `spindb url [name]` | Output connection string |
 | `spindb edit [name]` | Edit container properties (rename, port) |
+| `spindb backup [name]` | Create a database backup |
 | `spindb restore [name] [backup]` | Restore a backup file |
 | `spindb clone [source] [target]` | Clone a container |
 | `spindb delete [name]` | Delete a container |
@@ -107,6 +108,44 @@ Data is stored in `~/.spindb/`:
 └── config.json
 ```
 
+## How Data Persists
+
+SpinDB runs database servers as **native processes** on your machine—no Docker or virtualization involved. When you start a container, SpinDB launches the actual `postgres` or `mysqld` binary, which listens on localhost at your configured port.
+
+### What happens when you start a container
+
+1. SpinDB runs the database server binary (e.g., `pg_ctl start`)
+2. The server binds to `127.0.0.1` on your configured port
+3. A **PID file** is created to track the running process
+4. Logs are written to the container's log file
+
+### What happens when you stop a container
+
+1. SpinDB sends a shutdown signal to the database process
+2. The server flushes any pending writes to disk
+3. The **PID file is removed**
+4. Your data remains safely in the data directory
+
+### Where your data lives
+
+All database files persist in the container's `data/` directory:
+
+```
+~/.spindb/containers/postgresql/mydb/
+├── container.json    # Container configuration (port, version, etc.)
+├── postgres.log      # Server logs
+└── data/             # ← Your actual database files live here
+    ├── base/         # Table data
+    ├── pg_wal/       # Transaction logs
+    └── ...
+```
+
+The `data/` directory is a standard PostgreSQL/MySQL data directory. Stopping and starting a container doesn't affect your data—only the PID file changes.
+
+### How SpinDB knows if a container is running
+
+SpinDB checks for the PID file and verifies the process is still alive. No PID file (or dead process) = stopped container.
+
 ## Client Tools
 
 SpinDB bundles the PostgreSQL **server** but not client tools. For `connect` and `restore` commands, you need client tools installed.
@@ -205,6 +244,18 @@ spindb start test-branch
 # Interactive shell (auto-detects engine)
 spindb connect mydb
 
+# Use pgcli/mycli for enhanced shell (dropdown auto-completion)
+spindb connect mydb --pgcli     # PostgreSQL
+spindb connect mydb --mycli     # MySQL
+
+# Install pgcli/mycli and connect in one command
+spindb connect mydb --install-pgcli
+spindb connect mydb --install-mycli
+
+# Use usql for universal SQL client (works with both engines)
+spindb connect mydb --tui
+spindb connect mydb --install-tui
+
 # Or use connection string directly
 psql postgresql://postgres@localhost:5432/mydb
 mysql -u root -h 127.0.0.1 -P 3306 mydb
@@ -254,6 +305,31 @@ psql $(spindb url mydb)
 spindb url mydb --copy
 ```
 
+### Backup databases
+
+```bash
+# Backup with default settings (SQL format, auto-generated filename)
+spindb backup mydb
+
+# Backup specific database in container
+spindb backup mydb --database my_app_db
+
+# Custom filename and output directory
+spindb backup mydb --name my-backup --output ./backups/
+
+# Choose format: sql (plain text) or dump (compressed/binary)
+spindb backup mydb --format sql     # Plain SQL (.sql)
+spindb backup mydb --format dump    # PostgreSQL custom format (.dump) / MySQL gzipped (.sql.gz)
+
+# Shorthand flags
+spindb backup mydb --sql            # Same as --format sql
+spindb backup mydb --dump           # Same as --format dump
+```
+
+**Backup formats:**
+- **SQL format** (`.sql`) - Plain text, universal, can be read/edited
+- **Dump format** - PostgreSQL uses custom format (`.dump`), MySQL uses gzipped SQL (`.sql.gz`)
+
 ### Edit containers
 
 ```bash

package/cli/commands/backup.ts

@@ -0,0 +1,263 @@
+import { Command } from 'commander'
+import { join } from 'path'
+import chalk from 'chalk'
+import { containerManager } from '../../core/container-manager'
+import { processManager } from '../../core/process-manager'
+import { getEngine } from '../../engines'
+import {
+  promptContainerSelect,
+  promptDatabaseSelect,
+  promptBackupFormat,
+  promptBackupFilename,
+  promptInstallDependencies,
+} from '../ui/prompts'
+import { createSpinner } from '../ui/spinner'
+import { success, error, warning, formatBytes } from '../ui/theme'
+import { getMissingDependencies } from '../../core/dependency-manager'
+
+/**
+ * Generate a timestamp string for backup filenames
+ * Format: YYYY-MM-DDTHHMMSS (ISO 8601 without colons for filesystem compatibility)
+ */
+function generateTimestamp(): string {
+  const now = new Date()
+  return now.toISOString().replace(/:/g, '').split('.')[0]
+}
+
+/**
+ * Generate default backup filename
+ */
+function generateDefaultFilename(
+  containerName: string,
+  database: string,
+): string {
+  const timestamp = generateTimestamp()
+  return `${containerName}-${database}-backup-${timestamp}`
+}
+
+/**
+ * Get file extension for backup format
+ */
+function getExtension(format: 'sql' | 'dump', engine: string): string {
+  if (format === 'sql') {
+    return '.sql'
+  }
+  // MySQL dump is gzipped SQL, PostgreSQL dump is custom format
+  return engine === 'mysql' ? '.sql.gz' : '.dump'
+}
+
+export const backupCommand = new Command('backup')
+  .description('Create a backup of a database')
+  .argument('[container]', 'Container name')
+  .option('-d, --database <name>', 'Database to backup')
+  .option('-n, --name <name>', 'Custom backup filename (without extension)')
+  .option('-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)')
+  .action(
+    async (
+      containerArg: string | undefined,
+      options: {
+        database?: string
+        name?: string
+        output?: string
+        format?: string
+        sql?: boolean
+        dump?: boolean
+      },
+    ) => {
+      try {
+        let containerName = containerArg
+
+        // Interactive selection if no container provided
+        if (!containerName) {
+          const containers = await containerManager.list()
+          const running = containers.filter((c) => c.status === 'running')
+
+          if (running.length === 0) {
+            if (containers.length === 0) {
+              console.log(
+                warning('No containers found. Create one with: spindb create'),
+              )
+            } else {
+              console.log(
+                warning(
+                  'No running containers. Start one first with: spindb start',
+                ),
+              )
+            }
+            return
+          }
+
+          const selected = await promptContainerSelect(
+            running,
+            'Select container to backup:',
+          )
+          if (!selected) return
+          containerName = selected
+        }
+
+        // Get container config
+        const config = await containerManager.getConfig(containerName)
+        if (!config) {
+          console.error(error(`Container "${containerName}" not found`))
+          process.exit(1)
+        }
+
+        const { engine: engineName } = config
+
+        // Check if running
+        const running = await processManager.isRunning(containerName, {
+          engine: engineName,
+        })
+        if (!running) {
+          console.error(
+            error(
+              `Container "${containerName}" is not running. Start it first.`,
+            ),
+          )
+          process.exit(1)
+        }
+
+        // Get engine
+        const engine = getEngine(engineName)
+
+        // Check for required client tools
+        const depsSpinner = createSpinner('Checking required tools...')
+        depsSpinner.start()
+
+        let missingDeps = await getMissingDependencies(config.engine)
+        if (missingDeps.length > 0) {
+          depsSpinner.warn(
+            `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+          )
+
+          // Offer to install
+          const installed = await promptInstallDependencies(
+            missingDeps[0].binary,
+            config.engine,
+          )
+
+          if (!installed) {
+            process.exit(1)
+          }
+
+          // Verify installation worked
+          missingDeps = await getMissingDependencies(config.engine)
+          if (missingDeps.length > 0) {
+            console.error(
+              error(
+                `Still missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+              ),
+            )
+            process.exit(1)
+          }
+
+          console.log(chalk.green('  ✓ All required tools are now available'))
+          console.log()
+        } else {
+          depsSpinner.succeed('Required tools available')
+        }
+
+        // Determine which database to backup
+        let databaseName = options.database
+
+        if (!databaseName) {
+          // Get list of databases in container
+          const databases = config.databases || [config.database]
+
+          if (databases.length > 1) {
+            // Interactive mode: prompt for database selection
+            databaseName = await promptDatabaseSelect(
+              databases,
+              'Select database to backup:',
+            )
+          } else {
+            // Single database: use it
+            databaseName = databases[0]
+          }
+        }
+
+        // Determine format
+        let format: 'sql' | 'dump' = 'sql' // Default to SQL
+
+        if (options.sql) {
+          format = 'sql'
+        } else if (options.dump) {
+          format = 'dump'
+        } else if (options.format) {
+          if (options.format !== 'sql' && options.format !== 'dump') {
+            console.error(error('Format must be "sql" or "dump"'))
+            process.exit(1)
+          }
+          format = options.format as 'sql' | 'dump'
+        } else if (!containerArg) {
+          // Interactive mode: prompt for format
+          format = await promptBackupFormat(engineName)
+        }
+
+        // Determine filename
+        const defaultFilename = generateDefaultFilename(containerName, databaseName)
+        let filename = options.name || defaultFilename
+
+        // In interactive mode with no name provided, optionally prompt for custom name
+        if (!containerArg && !options.name) {
+          filename = await promptBackupFilename(defaultFilename)
+        }
+
+        // Build full output path
+        const extension = getExtension(format, engineName)
+        const outputDir = options.output || process.cwd()
+        const outputPath = join(outputDir, `${filename}${extension}`)
+
+        // Create backup
+        const backupSpinner = createSpinner(
+          `Creating ${format === 'sql' ? 'SQL' : 'dump'} backup of "${databaseName}"...`,
+        )
+        backupSpinner.start()
+
+        const result = await engine.backup(config, outputPath, {
+          database: databaseName,
+          format,
+        })
+
+        backupSpinner.succeed('Backup created successfully')
+
+        // Show result
+        console.log()
+        console.log(success('Backup complete'))
+        console.log()
+        console.log(chalk.gray('  File:'), chalk.cyan(result.path))
+        console.log(chalk.gray('  Size:'), chalk.white(formatBytes(result.size)))
+        console.log(chalk.gray('  Format:'), chalk.white(result.format))
+        console.log()
+      } catch (err) {
+        const e = err as Error
+
+        // Check if this is a missing tool error
+        const missingToolPatterns = [
+          'pg_dump not found',
+          'mysqldump not found',
+        ]
+
+        const matchingPattern = missingToolPatterns.find((p) =>
+          e.message.includes(p),
+        )
+
+        if (matchingPattern) {
+          const missingTool = matchingPattern.replace(' not found', '')
+          const installed = await promptInstallDependencies(missingTool)
+          if (installed) {
+            console.log(
+              chalk.yellow('  Please re-run your command to continue.'),
+            )
+          }
+          process.exit(1)
+        }
+
+        console.error(error(e.message))
+        process.exit(1)
+      }
+    },
+  )

package/cli/commands/config.ts

@@ -1,17 +1,43 @@
 import { Command } from 'commander'
 import chalk from 'chalk'
 import { existsSync } from 'fs'
-import { configManager } from '../../core/config-manager'
+import {
+  configManager,
+  POSTGRESQL_TOOLS,
+  MYSQL_TOOLS,
+  ENHANCED_SHELLS,
+  ALL_TOOLS,
+} from '../../core/config-manager'
 import { error, success, header } from '../ui/theme'
 import { createSpinner } from '../ui/spinner'
 import type { BinaryTool } from '../../types'
 
-const VALID_TOOLS: BinaryTool[] = [
-  'psql',
-  'pg_dump',
-  'pg_restore',
-  'pg_basebackup',
-]
+/**
+ * Helper to display a tool's config
+ */
+function displayToolConfig(
+  tool: BinaryTool,
+  binaryConfig: { path: string; version?: string; source: string } | undefined,
+): void {
+  if (binaryConfig) {
+    const sourceLabel =
+      binaryConfig.source === 'system'
+        ? chalk.blue('system')
+        : binaryConfig.source === 'custom'
+          ? chalk.yellow('custom')
+          : chalk.green('bundled')
+    const versionLabel = binaryConfig.version
+      ? chalk.gray(` (v${binaryConfig.version})`)
+      : ''
+    console.log(
+      `    ${chalk.cyan(tool.padEnd(15))} ${binaryConfig.path}${versionLabel} [${sourceLabel}]`,
+    )
+  } else {
+    console.log(
+      `    ${chalk.cyan(tool.padEnd(15))} ${chalk.gray('not detected')}`,
+    )
+  }
+}
 
 export const configCommand = new Command('config')
   .description('Manage spindb configuration')
@@ -26,37 +52,36 @@ export const configCommand = new Command('config')
           console.log(header('SpinDB Configuration'))
           console.log()
 
-          console.log(chalk.bold('  Binary Paths:'))
-          console.log(chalk.gray('  ' + '─'.repeat(50)))
-
-          for (const tool of VALID_TOOLS) {
-            const binaryConfig = config.binaries[tool]
-            if (binaryConfig) {
-              const sourceLabel =
-                binaryConfig.source === 'system'
-                  ? chalk.blue('system')
-                  : binaryConfig.source === 'custom'
-                    ? chalk.yellow('custom')
-                    : chalk.green('bundled')
-              const versionLabel = binaryConfig.version
-                ? chalk.gray(` (v${binaryConfig.version})`)
-                : ''
-              console.log(
-                `  ${chalk.cyan(tool.padEnd(15))} ${binaryConfig.path}${versionLabel} [${sourceLabel}]`,
-              )
-            } else {
-              console.log(
-                `  ${chalk.cyan(tool.padEnd(15))} ${chalk.gray('not configured')}`,
-              )
-            }
+          // PostgreSQL tools
+          console.log(chalk.bold('  🐘 PostgreSQL Tools:'))
+          console.log(chalk.gray('  ' + '─'.repeat(60)))
+          for (const tool of POSTGRESQL_TOOLS) {
+            displayToolConfig(tool, config.binaries[tool])
           }
+          console.log()
+
+          // MySQL tools
+          console.log(chalk.bold('  🐬 MySQL Tools:'))
+          console.log(chalk.gray('  ' + '─'.repeat(60)))
+          for (const tool of MYSQL_TOOLS) {
+            displayToolConfig(tool, config.binaries[tool])
+          }
+          console.log()
 
+          // Enhanced shells
+          console.log(chalk.bold('  ✨ Enhanced Shells (optional):'))
+          console.log(chalk.gray('  ' + '─'.repeat(60)))
+          for (const tool of ENHANCED_SHELLS) {
+            displayToolConfig(tool, config.binaries[tool])
+          }
           console.log()
 
           if (config.updatedAt) {
+            const isStale = await configManager.isStale()
+            const staleWarning = isStale ? chalk.yellow(' (stale - run config detect to refresh)') : ''
             console.log(
               chalk.gray(
-                `  Last updated: ${new Date(config.updatedAt).toLocaleString()}`,
+                `  Last updated: ${new Date(config.updatedAt).toLocaleString()}${staleWarning}`,
               ),
             )
             console.log()
@@ -70,55 +95,108 @@ export const configCommand = new Command('config')
   )
   .addCommand(
     new Command('detect')
-      .description('Auto-detect PostgreSQL client tools on your system')
+      .description('Auto-detect all database tools on your system')
       .action(async () => {
         try {
           console.log()
-          console.log(header('Detecting PostgreSQL Tools'))
+          console.log(header('Detecting Database Tools'))
           console.log()
 
-          const spinner = createSpinner(
-            'Searching for PostgreSQL client tools...',
-          )
+          const spinner = createSpinner('Searching for database tools...')
           spinner.start()
 
           // Clear existing configs to force re-detection
           await configManager.clearAllBinaries()
 
-          const { found, missing } = await configManager.initialize()
+          const result = await configManager.initialize()
 
           spinner.succeed('Detection complete')
           console.log()
 
-          if (found.length > 0) {
-            console.log(chalk.bold('  Found:'))
-            for (const tool of found) {
-              const config = await configManager.getBinaryConfig(tool)
-              if (config) {
-                const versionLabel = config.version
-                  ? chalk.gray(` (v${config.version})`)
-                  : ''
+          // Helper to display category results
+          async function displayCategory(
+            title: string,
+            icon: string,
+            found: BinaryTool[],
+            missing: BinaryTool[],
+          ): Promise<void> {
+            console.log(chalk.bold(`  ${icon} ${title}:`))
+
+            if (found.length > 0) {
+              for (const tool of found) {
+                const config = await configManager.getBinaryConfig(tool)
+                if (config) {
+                  const versionLabel = config.version
+                    ? chalk.gray(` (v${config.version})`)
+                    : ''
+                  console.log(
+                    `    ${chalk.green('✓')} ${chalk.cyan(tool.padEnd(15))} ${config.path}${versionLabel}`,
+                  )
+                }
+              }
+            }
+
+            if (missing.length > 0) {
+              for (const tool of missing) {
                 console.log(
-                  `  ${chalk.green('✓')} ${chalk.cyan(tool.padEnd(15))} ${config.path}${versionLabel}`,
+                  `    ${chalk.gray('○')} ${chalk.gray(tool.padEnd(15))} not found`,
                 )
               }
             }
+
             console.log()
           }
 
-          if (missing.length > 0) {
-            console.log(chalk.bold('  Not found:'))
-            for (const tool of missing) {
-              console.log(`  ${chalk.red('✗')} ${chalk.cyan(tool)}`)
+          await displayCategory(
+            'PostgreSQL Tools',
+            '🐘',
+            result.postgresql.found,
+            result.postgresql.missing,
+          )
+          await displayCategory(
+            'MySQL Tools',
+            '🐬',
+            result.mysql.found,
+            result.mysql.missing,
+          )
+          await displayCategory(
+            'Enhanced Shells (optional)',
+            '✨',
+            result.enhanced.found,
+            result.enhanced.missing,
+          )
+
+          // Show install hints for missing required tools
+          if (
+            result.postgresql.missing.length > 0 ||
+            result.mysql.missing.length > 0
+          ) {
+            console.log(chalk.gray('  Install missing tools:'))
+            if (result.postgresql.missing.length > 0) {
+              console.log(
+                chalk.gray('    PostgreSQL: brew install postgresql@17'),
+              )
+            }
+            if (result.mysql.missing.length > 0) {
+              console.log(chalk.gray('    MySQL:      brew install mysql'))
             }
             console.log()
-            console.log(chalk.gray('  Install missing tools:'))
-            console.log(
-              chalk.gray(
-                '    macOS:  brew install libpq && brew link --force libpq',
-              ),
-            )
-            console.log(chalk.gray('    Ubuntu: apt install postgresql-client'))
+          }
+
+          // Show enhanced shell hints
+          if (result.enhanced.missing.length > 0) {
+            console.log(chalk.gray('  Optional enhanced shells:'))
+            if (result.enhanced.missing.includes('pgcli')) {
+              console.log(chalk.gray('    pgcli: brew install pgcli'))
+            }
+            if (result.enhanced.missing.includes('mycli')) {
+              console.log(chalk.gray('    mycli: brew install mycli'))
+            }
+            if (result.enhanced.missing.includes('usql')) {
+              console.log(
+                chalk.gray('    usql:  brew tap xo/xo && brew install usql'),
+              )
+            }
             console.log()
           }
         } catch (err) {
@@ -131,14 +209,14 @@ export const configCommand = new Command('config')
   .addCommand(
     new Command('set')
       .description('Set a custom binary path')
-      .argument('<tool>', `Tool name (${VALID_TOOLS.join(', ')})`)
+      .argument('<tool>', 'Tool name (psql, mysql, pgcli, etc.)')
       .argument('<path>', 'Path to the binary')
       .action(async (tool: string, path: string) => {
         try {
           // Validate tool name
-          if (!VALID_TOOLS.includes(tool as BinaryTool)) {
+          if (!ALL_TOOLS.includes(tool as BinaryTool)) {
             console.error(error(`Invalid tool: ${tool}`))
-            console.log(chalk.gray(`  Valid tools: ${VALID_TOOLS.join(', ')}`))
+            console.log(chalk.gray(`  Valid tools: ${ALL_TOOLS.join(', ')}`))
             process.exit(1)
           }
 
@@ -164,13 +242,13 @@ export const configCommand = new Command('config')
   .addCommand(
     new Command('unset')
       .description('Remove a custom binary path')
-      .argument('<tool>', `Tool name (${VALID_TOOLS.join(', ')})`)
+      .argument('<tool>', 'Tool name (psql, mysql, pgcli, etc.)')
       .action(async (tool: string) => {
         try {
           // Validate tool name
-          if (!VALID_TOOLS.includes(tool as BinaryTool)) {
+          if (!ALL_TOOLS.includes(tool as BinaryTool)) {
             console.error(error(`Invalid tool: ${tool}`))
-            console.log(chalk.gray(`  Valid tools: ${VALID_TOOLS.join(', ')}`))
+            console.log(chalk.gray(`  Valid tools: ${ALL_TOOLS.join(', ')}`))
             process.exit(1)
           }
 
@@ -186,13 +264,13 @@ export const configCommand = new Command('config')
   .addCommand(
     new Command('path')
       .description('Show the path for a specific tool')
-      .argument('<tool>', `Tool name (${VALID_TOOLS.join(', ')})`)
+      .argument('<tool>', 'Tool name (psql, mysql, pgcli, etc.)')
       .action(async (tool: string) => {
         try {
           // Validate tool name
-          if (!VALID_TOOLS.includes(tool as BinaryTool)) {
+          if (!ALL_TOOLS.includes(tool as BinaryTool)) {
             console.error(error(`Invalid tool: ${tool}`))
-            console.log(chalk.gray(`  Valid tools: ${VALID_TOOLS.join(', ')}`))
+            console.log(chalk.gray(`  Valid tools: ${ALL_TOOLS.join(', ')}`))
             process.exit(1)
           }