spindb 0.4.1 → 0.5.3

package/README.md

@@ -1,18 +1,19 @@
 # SpinDB
 
-Spin up local PostgreSQL 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
 
-- **No Docker required** - Downloads and runs PostgreSQL binaries directly
-- **Multiple containers** - Run multiple isolated PostgreSQL instances on different ports
+- **No Docker required** - Downloads PostgreSQL binaries directly, uses system MySQL
+- **Multiple engines** - PostgreSQL and MySQL support
+- **Multiple containers** - Run multiple isolated database instances on different ports
 - **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 backups (requires system PostgreSQL client tools)
+- **Backup restore** - 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 all available versions from Maven Central
+- **Dynamic version selection** - Fetches available PostgreSQL versions from Maven Central
 
 ## Installation
 
@@ -31,7 +32,8 @@ pnpm add -g spindb
 spindb
 
 # Or use commands directly
-spindb create mydb
+spindb create mydb                    # PostgreSQL (default)
+spindb create mydb --engine mysql     # MySQL
 spindb list
 spindb connect mydb
 ```
@@ -43,96 +45,115 @@ 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 |
+| `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 PostgreSQL tools |
+| `spindb config detect` | Auto-detect database tools |
 | `spindb deps check` | Check status of client tools |
 | `spindb deps install` | Install missing client tools |
 
-## How It Works
+## Supported Engines
+
+### PostgreSQL 🐘
+
+- 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 🐬
 
-SpinDB downloads pre-built PostgreSQL binaries from [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) on first use. These are the same binaries used by embedded-postgres for Java testing.
+- 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/`:
 ```
 ~/.spindb/
-├── bin/                    # PostgreSQL server binaries
-│   └── postgresql-16-darwin-arm64/
-├── containers/             # Container data
-│   └── mydb/
-│       ├── container.json  # Container config
-│       ├── data/           # PostgreSQL data directory
-│       └── postgres.log    # Server logs
-└── config.json             # SpinDB configuration
+├── bin/                              # PostgreSQL server binaries
+│   └── postgresql-17-darwin-arm64/
+├── containers/
+│   ├── postgresql/                   # PostgreSQL containers
+│   │   └── mydb/
+│   │       ├── container.json
+│   │       ├── data/
+│   │       └── postgres.log
+│   └── mysql/                        # MySQL containers
+│       └── mydb/
+│           ├── container.json
+│           ├── data/
+│           └── mysql.log
+└── config.json
 ```
 
-## PostgreSQL Client Tools
+## Client Tools
 
-SpinDB bundles the PostgreSQL **server** (postgres, pg_ctl, initdb) but not client tools (psql, pg_dump, pg_restore). For `connect` and `restore` commands, you need PostgreSQL client tools installed.
+SpinDB bundles the PostgreSQL **server** but not client tools. For `connect` and `restore` commands, you need client tools installed.
 
 ### Automatic Installation
 
-SpinDB can check and install client tools automatically:
-
 ```bash
 # Check status of all client tools
 spindb deps check
 
-# Install missing tools (uses Homebrew, apt, yum, dnf, or pacman)
+# Install missing tools
 spindb deps install
 
 # Install for a specific engine
 spindb deps install --engine postgresql
 spindb deps install --engine mysql
-
-# Install all missing dependencies for all engines
-spindb deps install --all
-
-# List all supported dependencies
-spindb deps list
 ```
 
+**Note:** On Linux, package managers (apt, pacman, dnf) require `sudo` privileges. You may be prompted for your password when installing dependencies.
+
 ### Manual Installation
 
-If automatic installation doesn't work, install manually:
+#### PostgreSQL
 
 ```bash
-# macOS (Homebrew)
+# macOS (Homebrew) - use the latest PostgreSQL version (currently 17)
 brew install postgresql@17
 brew link --overwrite postgresql@17
 
 # Ubuntu/Debian
 sudo apt install postgresql-client
 
-# CentOS/RHEL
-sudo yum install postgresql
-
-# Fedora
-sudo dnf install postgresql
-
 # Arch
 sudo pacman -S postgresql-libs
-
-# Or use Postgres.app (macOS)
-# Client tools are automatically detected
 ```
 
-SpinDB auto-detects installed tools. Check what's configured:
+#### MySQL
 
 ```bash
-spindb config show
-```
+# macOS (Homebrew)
+brew install mysql
 
-Manually configure tool paths:
+# Ubuntu/Debian
+sudo apt install mysql-server
 
-```bash
-spindb config set psql /path/to/psql
-spindb config set pg_restore /path/to/pg_restore
+# Arch
+sudo pacman -S mysql
 ```
 
 ## Supported Platforms
@@ -140,53 +161,31 @@ spindb config set pg_restore /path/to/pg_restore
 - macOS (Apple Silicon & Intel)
 - Linux (x64 & ARM64)
 
-## Supported PostgreSQL Versions
-
-- PostgreSQL 14
-- PostgreSQL 15
-- PostgreSQL 16
-- PostgreSQL 17
-
 ## Examples
 
-### Create a database with specific version and name
+### Create databases
 
 ```bash
-# Specify PostgreSQL version and port
-spindb create mydb --pg-version 15 --port 5433
+# PostgreSQL with specific version and port
+spindb create mydb --engine postgresql --version 16 --port 5433
 
-# Specify a custom database name (different from container name)
+# MySQL
+spindb create mydb --engine mysql --port 3307
+
+# With custom database name
 spindb create mydb --database my_app_db
-# Connection string: postgresql://postgres@localhost:5432/my_app_db
 ```
 
 ### Create and restore in one command
 
 ```bash
-# Create a container and restore from a dump file
+# Create and restore from a dump file
 spindb create mydb --from ./backup.dump
 
-# Create a container and pull from a remote database
+# Create and pull from a remote database
 spindb create mydb --from "postgresql://user:pass@remote-host:5432/production_db"
-
-# With specific version and database name
-spindb create mydb --pg-version 17 --database myapp --from ./backup.dump
-```
-
-The `--from` option auto-detects whether the location is a file path or connection string.
-
-### Restore to an existing container
-
-```bash
-# Restore from a dump file (supports .sql, custom format, and tar format)
-spindb restore mydb ./backup.dump -d myapp
-
-# Or pull directly from a remote database
-spindb restore mydb --from-url "postgresql://user:pass@remote-host:5432/production_db" -d myapp
 ```
 
-The interactive menu (`spindb` → "Restore backup") also offers an option to create a new container as part of the restore flow.
-
 ### Clone for testing
 
 ```bash
@@ -200,63 +199,102 @@ spindb clone production-copy test-branch
 spindb start test-branch
 ```
 
-### Connect and run queries
+### Connect to databases
 
 ```bash
-# Interactive psql session
+# Interactive shell (auto-detects engine)
 spindb connect mydb
 
-# Or use the connection string directly
+# Or use connection string directly
 psql postgresql://postgres@localhost:5432/mydb
+mysql -u root -h 127.0.0.1 -P 3306 mydb
 ```
 
 ### Manage installed engines
 
-The Engines menu (accessible from the main menu) shows all installed PostgreSQL versions with their disk usage. You can delete unused versions to free up space.
+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.9.0      darwin-arm64        44.8 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)
 ────────────────────────────────────────────────────────
-3 version(s)                                134.8 MB
+
+PostgreSQL: 2 version(s), 90.0 MB
+MySQL: system-installed at /opt/homebrew/bin/mysqld
 ```
 
-## Configuration
+Delete unused PostgreSQL versions to free disk space:
 
-Configuration is stored in `~/.spindb/config.json`. You can edit it directly or use the `config` commands:
+```bash
+spindb engines delete postgresql 16
+```
+
+### Container info and connection strings
 
 ```bash
-# Show all config
-spindb config show
+# View all container details
+spindb info
 
-# Re-detect system tools
-spindb config detect
+# View specific container
+spindb info mydb
 
-# Set custom binary path
-spindb config set psql /usr/local/bin/psql
+# Get connection string for scripting
+spindb url mydb
+export DATABASE_URL=$(spindb url mydb)
+psql $(spindb url mydb)
 
-# Get path for scripting
-spindb config path psql
+# 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
+
+```bash
+# Run all tests (PostgreSQL + MySQL)
+pnpm test
+
+# Run individual test suites
+pnpm test:pg
+pnpm test:mysql
 ```
 
 ## Troubleshooting
 
 ### Port already in use
 
-SpinDB automatically finds an available port if the default (5432) is in use. You can also specify a port:
+SpinDB automatically finds an available port. You can also specify one:
 
 ```bash
 spindb create mydb --port 5433
 ```
 
-### psql not found
+### Client tool not found
 
-Install PostgreSQL client tools (see above) or configure the path manually:
+Install client tools or configure the path:
 
 ```bash
+spindb deps install
+# or
 spindb config set psql /path/to/psql
 ```
 
@@ -265,7 +303,8 @@ spindb config set psql /path/to/psql
 Check the logs:
 
 ```bash
-cat ~/.spindb/containers/mydb/postgres.log
+cat ~/.spindb/containers/postgresql/mydb/postgres.log
+cat ~/.spindb/containers/mysql/mydb/mysql.log
 ```
 
 ### Reset everything
@@ -274,6 +313,73 @@ cat ~/.spindb/containers/mydb/postgres.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/clone.ts

@@ -58,7 +58,9 @@ export const cloneCommand = new Command('clone')
       }
 
       // Check source is stopped
-      const running = await processManager.isRunning(sourceName)
+      const running = await processManager.isRunning(sourceName, {
+        engine: sourceConfig.engine,
+      })
       if (running) {
         console.error(
           error(

package/cli/commands/connect.ts

@@ -4,14 +4,15 @@ import chalk from 'chalk'
 import { containerManager } from '../../core/container-manager'
 import { processManager } from '../../core/process-manager'
 import { getEngine } from '../../engines'
+import { getEngineDefaults } from '../../config/defaults'
 import { promptContainerSelect } from '../ui/prompts'
 import { error, warning, info } from '../ui/theme'
 
 export const connectCommand = new Command('connect')
-  .description('Connect to a container with psql')
+  .description('Connect to a container with database client')
   .argument('[name]', 'Container name')
-  .option('-d, --database <name>', 'Database name', 'postgres')
-  .action(async (name: string | undefined, options: { database: string }) => {
+  .option('-d, --database <name>', 'Database name')
+  .action(async (name: string | undefined, options: { database?: string }) => {
     try {
       let containerName = name
 
@@ -50,8 +51,17 @@ export const connectCommand = new Command('connect')
         process.exit(1)
       }
 
+      const { engine: engineName } = config
+      const engineDefaults = getEngineDefaults(engineName)
+
+      // Default database: container's database or superuser
+      const database =
+        options.database ?? config.database ?? engineDefaults.superuser
+
       // Check if running
-      const running = await processManager.isRunning(containerName)
+      const running = await processManager.isRunning(containerName, {
+        engine: engineName,
+      })
       if (!running) {
         console.error(
           error(`Container "${containerName}" is not running. Start it first.`),
@@ -60,35 +70,55 @@ export const connectCommand = new Command('connect')
       }
 
       // Get engine
-      const engine = getEngine(config.engine)
-      const connectionString = engine.getConnectionString(
-        config,
-        options.database,
-      )
+      const engine = getEngine(engineName)
+      const connectionString = engine.getConnectionString(config, database)
 
-      console.log(info(`Connecting to ${containerName}:${options.database}...`))
+      console.log(info(`Connecting to ${containerName}:${database}...`))
       console.log()
 
-      // Try to use system psql (the bundled binaries don't include psql)
-      const psqlProcess = spawn('psql', [connectionString], {
+      // Build client command based on engine
+      let clientCmd: string
+      let clientArgs: string[]
+
+      if (engineName === 'mysql') {
+        // 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,
+          database,
+        ]
+      } else {
+        // PostgreSQL: psql connection_string
+        clientCmd = 'psql'
+        clientArgs = [connectionString]
+      }
+
+      const clientProcess = spawn(clientCmd, clientArgs, {
         stdio: 'inherit',
       })
 
-      psqlProcess.on('error', (err: NodeJS.ErrnoException) => {
+      clientProcess.on('error', (err: NodeJS.ErrnoException) => {
         if (err.code === 'ENOENT') {
-          console.log(warning('psql not found on your system.'))
+          console.log(warning(`${clientCmd} not found on your system.`))
           console.log()
-          console.log(
-            chalk.gray(
-              '  Install PostgreSQL client tools or connect manually:',
-            ),
-          )
+          console.log(chalk.gray('  Install client tools or connect manually:'))
           console.log(chalk.cyan(`  ${connectionString}`))
           console.log()
-          console.log(chalk.gray('  On macOS with Homebrew:'))
-          console.log(
-            chalk.cyan('  brew install libpq && brew link --force libpq'),
-          )
+
+          if (engineName === 'mysql') {
+            console.log(chalk.gray('  On macOS with Homebrew:'))
+            console.log(chalk.cyan('  brew install mysql-client'))
+          } else {
+            console.log(chalk.gray('  On macOS with Homebrew:'))
+            console.log(
+              chalk.cyan('  brew install libpq && brew link --force libpq'),
+            )
+          }
           console.log()
         } else {
           console.error(error(err.message))
@@ -96,7 +126,7 @@ export const connectCommand = new Command('connect')
       })
 
       await new Promise<void>((resolve) => {
-        psqlProcess.on('close', () => resolve())
+        clientProcess.on('close', () => resolve())
       })
     } catch (err) {
       const e = err as Error