spindb 0.5.2 → 0.5.3

package/README.md

@@ -1,6 +1,6 @@
 # SpinDB
 
-Spin up local PostgreSQL and MySQL databases without Docker. A lightweight alternative to DBngin.
+Spin up local PostgreSQL and MySQL databases without Docker. A lightweight alternative to DBngin and Postgres.app.
 
 ## Features
 
@@ -45,12 +45,17 @@ spindb connect mydb
 | `spindb` | Open interactive menu |
 | `spindb create [name]` | Create a new database container |
 | `spindb list` | List all containers |
+| `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 url [name]` | Output connection string |
+| `spindb edit [name]` | Edit container properties (rename, port) |
 | `spindb restore [name] [backup]` | Restore a backup file |
 | `spindb clone [source] [target]` | Clone a container |
 | `spindb delete [name]` | Delete a container |
+| `spindb engines` | List installed database engines |
+| `spindb engines delete` | Delete an installed engine version |
 | `spindb config show` | Show configuration |
 | `spindb config detect` | Auto-detect database tools |
 | `spindb deps check` | Check status of client tools |
@@ -60,16 +65,27 @@ spindb connect mydb
 
 ### PostgreSQL 🐘
 
-- Downloads binaries from [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries)
+- Downloads server binaries from [zonky.io embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries)
 - Versions: 14, 15, 16, 17
 - Requires system client tools (psql, pg_dump, pg_restore) for some operations
 
+**Why zonky.io?** Zonky.io provides pre-compiled PostgreSQL server binaries for multiple platforms (macOS, Linux) and architectures (x64, ARM64) hosted on Maven Central. This allows SpinDB to download and run PostgreSQL without requiring a full system installation. The binaries are extracted from official PostgreSQL distributions and repackaged for easy embedding in applications.
+
 ### MySQL 🐬
 
 - Uses system-installed MySQL (via Homebrew, apt, etc.)
 - Version determined by system installation
 - Requires: mysqld, mysql, mysqldump, mysqladmin
 
+**Linux Note:** On Linux systems, MariaDB is commonly used as a drop-in replacement for MySQL. SpinDB fully supports MariaDB and will automatically detect it. When MariaDB is installed, the `mysql`, `mysqld`, and `mysqldump` commands work the same way. Install with:
+```bash
+# Ubuntu/Debian
+sudo apt install mariadb-server
+
+# Arch
+sudo pacman -S mariadb
+```
+
 ## How It Works
 
 Data is stored in `~/.spindb/`:
@@ -109,12 +125,14 @@ spindb deps install --engine postgresql
 spindb deps install --engine mysql
 ```
 
+**Note:** On Linux, package managers (apt, pacman, dnf) require `sudo` privileges. You may be prompted for your password when installing dependencies.
+
 ### Manual Installation
 
 #### PostgreSQL
 
 ```bash
-# macOS (Homebrew)
+# macOS (Homebrew) - use the latest PostgreSQL version (currently 17)
 brew install postgresql@17
 brew link --overwrite postgresql@17
 
@@ -194,15 +212,59 @@ mysql -u root -h 127.0.0.1 -P 3306 mydb
 
 ### Manage installed engines
 
-The Engines menu shows installed PostgreSQL versions with disk usage:
+View installed engines with disk usage (PostgreSQL) and system detection (MySQL):
+
+```bash
+spindb engines
+```
 
 ```
-ENGINE      VERSION     PLATFORM            SIZE
+ENGINE        VERSION     SOURCE            SIZE
 ────────────────────────────────────────────────────────
-postgresql  17          darwin-arm64        45.2 MB
-postgresql  16          darwin-arm64        44.8 MB
+🐘 postgresql 17.7        darwin-arm64      45.2 MB
+🐘 postgresql 16.8        darwin-arm64      44.8 MB
+🐬 mysql      8.0.35      system            (system-installed)
 ────────────────────────────────────────────────────────
-2 version(s)                                90.0 MB
+
+PostgreSQL: 2 version(s), 90.0 MB
+MySQL: system-installed at /opt/homebrew/bin/mysqld
+```
+
+Delete unused PostgreSQL versions to free disk space:
+
+```bash
+spindb engines delete postgresql 16
+```
+
+### Container info and connection strings
+
+```bash
+# View all container details
+spindb info
+
+# View specific container
+spindb info mydb
+
+# Get connection string for scripting
+spindb url mydb
+export DATABASE_URL=$(spindb url mydb)
+psql $(spindb url mydb)
+
+# Copy connection string to clipboard
+spindb url mydb --copy
+```
+
+### Edit containers
+
+```bash
+# Rename a container (must be stopped)
+spindb edit mydb --name newname
+
+# Change port
+spindb edit mydb --port 5433
+
+# Interactive mode
+spindb edit mydb
 ```
 
 ## Running Tests
@@ -251,6 +313,73 @@ cat ~/.spindb/containers/mysql/mydb/mysql.log
 rm -rf ~/.spindb
 ```
 
+## Project Structure
+
+```
+spindb/
+├── bin.ts                      # Entry point (#!/usr/bin/env tsx)
+├── cli/
+│   ├── index.ts                # Commander setup, routes to commands
+│   ├── commands/               # CLI commands
+│   │   ├── menu.ts             # Interactive arrow-key menu
+│   │   ├── create.ts           # Create container command
+│   │   ├── delete.ts           # Delete container command
+│   │   └── ...                 # Other commands
+│   └── ui/
+│       ├── prompts.ts          # Inquirer prompts
+│       ├── spinner.ts          # Ora spinner helpers
+│       └── theme.ts            # Chalk color theme
+├── core/
+│   ├── binary-manager.ts       # Downloads PostgreSQL from zonky.io
+│   ├── config-manager.ts       # Manages ~/.spindb/config.json
+│   ├── container-manager.ts    # CRUD for containers
+│   ├── port-manager.ts         # Port availability checking
+│   ├── process-manager.ts      # Process start/stop wrapper
+│   ├── dependency-manager.ts   # Client tool detection
+│   ├── error-handler.ts        # Centralized error handling
+│   └── transaction-manager.ts  # Rollback support for operations
+├── config/
+│   ├── paths.ts                # ~/.spindb/ path definitions
+│   ├── defaults.ts             # Default values, platform mappings
+│   └── os-dependencies.ts      # OS-specific dependency definitions
+├── engines/
+│   ├── base-engine.ts          # Abstract base class
+│   ├── index.ts                # Engine registry
+│   ├── postgresql/
+│   │   ├── index.ts            # PostgreSQL engine implementation
+│   │   ├── binary-urls.ts      # Zonky.io URL builder
+│   │   ├── restore.ts          # Backup detection and restore
+│   │   └── version-validator.ts # Version compatibility checks
+│   └── mysql/
+│       ├── index.ts            # MySQL engine implementation
+│       ├── binary-detection.ts # MySQL binary path detection
+│       ├── restore.ts          # Backup detection and restore
+│       └── version-validator.ts # Version compatibility checks
+├── types/
+│   └── index.ts                # TypeScript interfaces
+└── tests/
+    ├── unit/                   # Unit tests
+    ├── integration/            # Integration tests
+    └── fixtures/               # Test data
+        ├── postgresql/
+        │   └── seeds/
+        └── mysql/
+            └── seeds/
+```
+
+## Contributing
+
+### Version Updates
+
+SpinDB uses versioned PostgreSQL packages from Homebrew (e.g., `postgresql@17`). When new major versions are released:
+
+1. Check [PostgreSQL releases](https://www.postgresql.org/docs/release/) and [Homebrew formulae](https://formulae.brew.sh/formula/postgresql)
+2. Update `config/engine-defaults.ts`:
+   - Change `latestVersion` to the new version
+   - Add the new version to `supportedVersions`
+
+See `CLAUDE.md` for detailed maintenance instructions.
+
 ## License
 
 MIT

package/cli/commands/connect.ts

@@ -55,7 +55,8 @@ export const connectCommand = new Command('connect')
       const engineDefaults = getEngineDefaults(engineName)
 
       // Default database: container's database or superuser
-      const database = options.database ?? config.database ?? engineDefaults.superuser
+      const database =
+        options.database ?? config.database ?? engineDefaults.superuser
 
       // Check if running
       const running = await processManager.isRunning(containerName, {
@@ -83,9 +84,12 @@ export const connectCommand = new Command('connect')
         // MySQL: mysql -h 127.0.0.1 -P port -u root database
         clientCmd = 'mysql'
         clientArgs = [
-          '-h', '127.0.0.1',
-          '-P', String(config.port),
-          '-u', engineDefaults.superuser,
+          '-h',
+          '127.0.0.1',
+          '-P',
+          String(config.port),
+          '-u',
+          engineDefaults.superuser,
           database,
         ]
       } else {

package/cli/commands/create.ts

@@ -16,9 +16,10 @@ import { createSpinner } from '../ui/spinner'
 import { header, error, connectionBox } from '../ui/theme'
 import { tmpdir } from 'os'
 import { join } from 'path'
-import { spawn } from 'child_process'
-import { platform } from 'os'
 import { getMissingDependencies } from '../../core/dependency-manager'
+import { platformService } from '../../core/platform-service'
+import { startWithRetry } from '../../core/start-with-retry'
+import { TransactionManager } from '../../core/transaction-manager'
 import type { EngineName } from '../../types'
 
 /**
@@ -244,28 +245,50 @@ export const createCommand = new Command('create')
           containerName = await promptContainerName()
         }
 
+        // Create transaction manager for rollback support
+        const tx = new TransactionManager()
+
         // Create container
         const createSpinnerInstance = createSpinner('Creating container...')
         createSpinnerInstance.start()
 
-        await containerManager.create(containerName, {
-          engine: dbEngine.name as EngineName,
-          version,
-          port,
-          database,
-        })
+        try {
+          await containerManager.create(containerName, {
+            engine: dbEngine.name as EngineName,
+            version,
+            port,
+            database,
+          })
+
+          // Register rollback action for container deletion
+          tx.addRollback({
+            description: `Delete container "${containerName}"`,
+            execute: async () => {
+              await containerManager.delete(containerName, { force: true })
+            },
+          })
 
-        createSpinnerInstance.succeed('Container created')
+          createSpinnerInstance.succeed('Container created')
+        } catch (err) {
+          createSpinnerInstance.fail('Failed to create container')
+          throw err
+        }
 
         // Initialize database cluster
         const initSpinner = createSpinner('Initializing database cluster...')
         initSpinner.start()
 
-        await dbEngine.initDataDir(containerName, version, {
-          superuser: engineDefaults.superuser,
-        })
-
-        initSpinner.succeed('Database cluster initialized')
+        try {
+          await dbEngine.initDataDir(containerName, version, {
+            superuser: engineDefaults.superuser,
+          })
+          // Note: initDataDir is covered by the container delete rollback
+          initSpinner.succeed('Database cluster initialized')
+        } catch (err) {
+          initSpinner.fail('Failed to initialize database cluster')
+          await tx.rollback()
+          throw err
+        }
 
         // Determine if we should start the container
         // If --from is specified, we must start to restore
@@ -281,10 +304,7 @@ export const createCommand = new Command('create')
         } else {
           // Ask the user
           console.log()
-          shouldStart = await promptConfirm(
-            `Start ${containerName} now?`,
-            true,
-          )
+          shouldStart = await promptConfirm(`Start ${containerName} now?`, true)
         }
 
         // Get container config for starting and restoration
@@ -292,34 +312,63 @@ export const createCommand = new Command('create')
 
         // Start container if requested
         if (shouldStart && config) {
-          // Check port availability before starting
-          const portAvailable = await portManager.isPortAvailable(config.port)
-          if (!portAvailable) {
-            // Find a new available port
-            const { port: newPort } = await portManager.findAvailablePort({
-              portRange: engineDefaults.portRange,
-            })
-            console.log(
-              chalk.yellow(
-                `  ⚠ Port ${config.port} is in use, switching to port ${newPort}`,
-              ),
-            )
-            config.port = newPort
-            port = newPort
-            await containerManager.updateConfig(containerName, { port: newPort })
-          }
-
           const startSpinner = createSpinner(
             `Starting ${dbEngine.displayName}...`,
           )
           startSpinner.start()
 
-          await dbEngine.start(config)
-          await containerManager.updateConfig(containerName, {
-            status: 'running',
-          })
+          try {
+            // Use startWithRetry to handle port race conditions
+            const result = await startWithRetry({
+              engine: dbEngine,
+              config,
+              onPortChange: (oldPort, newPort) => {
+                startSpinner.text = `Port ${oldPort} was in use, retrying with port ${newPort}...`
+                port = newPort
+              },
+            })
 
-          startSpinner.succeed(`${dbEngine.displayName} started`)
+            if (!result.success) {
+              startSpinner.fail(`Failed to start ${dbEngine.displayName}`)
+              await tx.rollback()
+              if (result.error) {
+                throw result.error
+              }
+              throw new Error('Failed to start container')
+            }
+
+            // Register rollback action for stopping the container
+            tx.addRollback({
+              description: `Stop container "${containerName}"`,
+              execute: async () => {
+                try {
+                  await dbEngine.stop(config)
+                } catch {
+                  // Ignore stop errors during rollback
+                }
+              },
+            })
+
+            await containerManager.updateConfig(containerName, {
+              status: 'running',
+            })
+
+            if (result.retriesUsed > 0) {
+              startSpinner.warn(
+                `${dbEngine.displayName} started on port ${result.finalPort} (original port was in use)`,
+              )
+            } else {
+              startSpinner.succeed(`${dbEngine.displayName} started`)
+            }
+          } catch (err) {
+            if (!startSpinner.isSpinning) {
+              // Error was already handled above
+            } else {
+              startSpinner.fail(`Failed to start ${dbEngine.displayName}`)
+            }
+            await tx.rollback()
+            throw err
+          }
 
           // Create the user's database (if different from default)
           const defaultDb = engineDefaults.superuser // postgres or root
@@ -329,9 +378,14 @@ export const createCommand = new Command('create')
             )
             dbSpinner.start()
 
-            await dbEngine.createDatabase(config, database)
-
-            dbSpinner.succeed(`Database "${database}" created`)
+            try {
+              await dbEngine.createDatabase(config, database)
+              dbSpinner.succeed(`Database "${database}" created`)
+            } catch (err) {
+              dbSpinner.fail(`Failed to create database "${database}"`)
+              await tx.rollback()
+              throw err
+            }
           }
         }
 
@@ -431,13 +485,18 @@ export const createCommand = new Command('create')
           }
         }
 
+        // Commit the transaction - all operations succeeded
+        tx.commit()
+
         // Show success message
         const finalConfig = await containerManager.getConfig(containerName)
         if (finalConfig) {
           const connectionString = dbEngine.getConnectionString(finalConfig)
 
           console.log()
-          console.log(connectionBox(containerName, connectionString, finalConfig.port))
+          console.log(
+            connectionBox(containerName, connectionString, finalConfig.port),
+          )
           console.log()
 
           if (shouldStart) {
@@ -445,30 +504,10 @@ export const createCommand = new Command('create')
             console.log(chalk.cyan(`  spindb connect ${containerName}`))
 
             // Copy connection string to clipboard
-            try {
-              const cmd = platform() === 'darwin' ? 'pbcopy' : 'xclip'
-              const args =
-                platform() === 'darwin' ? [] : ['-selection', 'clipboard']
-
-              await new Promise<void>((resolve, reject) => {
-                const proc = spawn(cmd, args, {
-                  stdio: ['pipe', 'inherit', 'inherit'],
-                })
-                proc.stdin?.write(connectionString)
-                proc.stdin?.end()
-                proc.on('close', (code) => {
-                  if (code === 0) resolve()
-                  else
-                    reject(
-                      new Error(`Clipboard command exited with code ${code}`),
-                    )
-                })
-                proc.on('error', reject)
-              })
-
+            const copied =
+              await platformService.copyToClipboard(connectionString)
+            if (copied) {
               console.log(chalk.gray('  Connection string copied to clipboard'))
-            } catch {
-              // Ignore clipboard errors
             }
           } else {
             console.log(chalk.gray('  Start the container:'))

package/cli/commands/deps.ts

@@ -188,7 +188,11 @@ depsCommand
 
       if (succeeded.length > 0) {
         console.log()
-        console.log(success(`Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`))
+        console.log(
+          success(
+            `Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`,
+          ),
+        )
       }
     } else if (options.engine) {
       // Install dependencies for specific engine
@@ -254,7 +258,11 @@ depsCommand
 
       if (succeeded.length > 0) {
         console.log()
-        console.log(success(`Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`))
+        console.log(
+          success(
+            `Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`,
+          ),
+        )
       }
     } else {
       // Default: install PostgreSQL dependencies (most common use case)
@@ -278,7 +286,10 @@ depsCommand
       const spinner = createSpinner('Installing PostgreSQL dependencies...')
       spinner.start()
 
-      const results = await installEngineDependencies('postgresql', packageManager)
+      const results = await installEngineDependencies(
+        'postgresql',
+        packageManager,
+      )
 
       const succeeded = results.filter((r) => r.success)
       const failed = results.filter((r) => !r.success)
@@ -295,7 +306,11 @@ depsCommand
 
       if (succeeded.length > 0) {
         console.log()
-        console.log(success(`Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`))
+        console.log(
+          success(
+            `Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`,
+          ),
+        )
       }
     }
   })