spindb 0.6.0 → 0.7.3

package/README.md

@@ -1,33 +1,103 @@
 # SpinDB
 
-Spin up local PostgreSQL and MySQL databases without Docker. A lightweight alternative to DBngin and Postgres.app.
+[![npm version](https://img.shields.io/npm/v/spindb.svg)](https://www.npmjs.com/package/spindb)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](LICENSE)
+[![Platform: macOS | Linux](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey.svg)](#supported-platforms)
 
-## Features
+**Local databases without the Docker baggage.**
 
-- **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** - 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
+Spin up PostgreSQL and MySQL instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
+
+---
+
+## Why SpinDB?
+
+Docker is great for production parity and complex multi-service setups. But for local development databases, it's often overkill:
+
+- **Resource overhead** - Docker Desktop runs a Linux VM on macOS/Windows
+- **Complexity** - Volumes, networks, compose files for a single database
+- **Startup time** - Container initialization vs native process launch
+- **Licensing** - Docker Desktop requires a paid subscription for larger organizations
+
+Sometimes you just want PostgreSQL on `localhost:5432` without the ceremony.
+
+SpinDB runs databases as native processes with isolated data directories. No VM, no daemon, no container networking. Just databases.
+
+### SpinDB vs Alternatives
+
+| Feature | SpinDB | Docker | DBngin | Postgres.app |
+|---------|--------|--------|--------|--------------|
+| No Docker required | ✅ | ❌ | ✅ | ✅ |
+| Multiple DB engines | ✅ | ✅ | ✅ | ❌ |
+| CLI-first | ✅ | ✅ | ❌ | ❌ |
+| Multiple versions | ✅ | ✅ | ✅ | ✅ |
+| Clone databases | ✅ | Manual | ✅ | ❌ |
+| Low resource usage | ✅ | ❌ | ✅ | ✅ |
+| Linux support | ✅ | ✅ | ❌ | ❌ |
+| Free | ✅ | ⚠️ | ✅ | ✅ |
+
+### How It Works
+
+SpinDB uses the term "container" loosely—there's no Docker involved. When you create a container, SpinDB:
+
+1. Downloads the database server binary (or uses your system's installation)
+2. Creates an isolated data directory at `~/.spindb/containers/{engine}/{name}/`
+3. Runs the database as a native process on your machine
+
+Each "container" is just:
+- A configuration file (`container.json`)
+- A data directory (`data/`)
+- A log file (`postgres.log` or `mysql.log`)
+
+Native processes mean instant startup and no virtualization overhead.
+
+---
+
+## The Interactive Menu
+
+Most of the time, you don't need to remember commands. Just run:
+
+```bash
+spindb
+```
+
+You'll get an interactive menu with arrow-key navigation:
+
+```
+? What would you like to do?
+❯ Create a new container
+  Manage containers
+  View installed engines
+  Check dependencies
+  Settings
+  Exit
+```
+
+**Everything in the menu is also available as a CLI command.** The menu is just a friendlier interface for the same operations. If you prefer typing commands or scripting, SpinDB has full CLI support.
+
+---
 
 ## Installation
 
+SpinDB is distributed via npm. A global install is recommended so you can run `spindb` from anywhere.
+
+We recommend [pnpm](https://pnpm.io/) as a faster, more disk-efficient alternative to npm.
+
 ```bash
-# Install globally (recommended)
+# Using pnpm (recommended)
+pnpm add -g spindb
+
+# Using npm
 npm install -g spindb
 
-# Or run directly with pnpx (no install needed)
+# Or run directly without installing
 pnpx spindb
+npx spindb
 ```
 
 ### Updating
 
-SpinDB checks for updates automatically and will notify you when a new version is available:
+SpinDB checks for updates automatically and notifies you when a new version is available.
 
 ```bash
 # Update to latest version
@@ -35,256 +105,261 @@ spindb self-update
 
 # Or check manually
 spindb version --check
+
+# Disable automatic update checks
+spindb config update-check off
 ```
 
+---
+
 ## Quick Start
 
 ```bash
-# Launch interactive menu
-spindb
+# Create and start a PostgreSQL database
+spindb create myapp
 
-# Or use commands directly
-spindb create mydb                    # PostgreSQL (default)
-spindb create mydb --engine mysql     # MySQL
-spindb list
-spindb connect mydb
+# Connect to it
+spindb connect myapp
+
+# You're in! Run some SQL:
+# postgres=# CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
 ```
 
-## Commands
+That's it. Your database is running on `localhost:5432`, and your data persists in `~/.spindb/containers/postgresql/myapp/`.
 
-| Command | Description |
-|---------|-------------|
-| `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 (`--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 |
-| `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 |
-| `spindb deps install` | Install missing client tools |
-| `spindb version` | Show current version |
-| `spindb version --check` | Check for available updates |
-| `spindb self-update` | Update to latest version |
-| `spindb config update-check [on\|off]` | Enable/disable update notifications |
-
-## 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 🐬
-
-- 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
-```
+## Database Engines
 
-## How It Works
+### Supported Engines
 
-Data is stored in `~/.spindb/`:
-```
-~/.spindb/
-├── 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
 
-## How Data Persists
+| | |
+|---|---|
+| Versions | 14, 15, 16, 17 |
+| Default port | 5432 |
+| Default user | `postgres` |
+| Binary source | [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) |
 
-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.
+SpinDB downloads PostgreSQL server binaries automatically. These are pre-compiled binaries from the zonky.io project, hosted on Maven Central. They're extracted from official PostgreSQL distributions and work on macOS and Linux (x64 and ARM64).
 
-### What happens when you start a container
+**Why download binaries instead of using system PostgreSQL?** You might want PostgreSQL 14 for one project and 17 for another. SpinDB lets you run different versions side-by-side without conflicts.
 
-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
+**Client tools required:** You still need `psql`, `pg_dump`, and `pg_restore` installed on your system for some operations (connecting, backups, restores). SpinDB can install these for you:
 
-### What happens when you stop a container
+```bash
+spindb deps install --engine postgresql
+```
 
-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
+#### MySQL
 
-### Where your data lives
+| | |
+|---|---|
+| Versions | Depends on system installation |
+| Default port | 3306 |
+| Default user | `root` |
+| Binary source | System installation |
 
-All database files persist in the container's `data/` directory:
+Unlike PostgreSQL, SpinDB uses your system's MySQL installation. This is because MySQL doesn't have a nice cross-platform binary distribution like zonky.io provides for PostgreSQL.
 
-```
-~/.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
-    └── ...
+```bash
+# macOS
+brew install mysql
+
+# Ubuntu/Debian
+sudo apt install mysql-server
+
+# Check if SpinDB can find MySQL
+spindb deps check --engine mysql
 ```
 
-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.
+**Linux users:** MariaDB works as a drop-in replacement for MySQL. If you have MariaDB installed, SpinDB will detect and use it automatically. In a future release, MariaDB will be available as its own engine with support for MariaDB-specific features.
 
-### How SpinDB knows if a container is running
+### Planned Engines
 
-SpinDB checks for the PID file and verifies the process is still alive. No PID file (or dead process) = stopped container.
+| Engine | Type | Status |
+|--------|------|--------|
+| SQLite | File-based | Planned for v1.2 |
+| Redis | In-memory key-value | Planned for v1.2 |
+| MongoDB | Document database | Planned for v1.2 |
 
-## Client Tools
+---
 
-SpinDB bundles the PostgreSQL **server** but not client tools. For `connect` and `restore` commands, you need client tools installed.
+## Commands
+
+### Container Lifecycle
 
-### Automatic Installation
+#### `create` - Create a new container
 
 ```bash
-# Check status of all client tools
-spindb deps check
+spindb create mydb                           # PostgreSQL (default)
+spindb create mydb --engine mysql            # MySQL
+spindb create mydb --version 16              # Specific PostgreSQL version
+spindb create mydb --port 5433               # Custom port
+spindb create mydb --database my_app         # Custom database name
+spindb create mydb --no-start                # Create without starting
+```
 
-# Install missing tools
-spindb deps install
+Create and restore in one command:
 
-# Install for a specific engine
-spindb deps install --engine postgresql
-spindb deps install --engine mysql
+```bash
+spindb create mydb --from ./backup.dump
+spindb create mydb --from "postgresql://user:pass@host:5432/production"
 ```
 
-**Note:** On Linux, package managers (apt, pacman, dnf) require `sudo` privileges. You may be prompted for your password when installing dependencies.
+<details>
+<summary>All options</summary>
 
-### Manual Installation
+| Option | Description |
+|--------|-------------|
+| `--engine`, `-e` | Database engine (`postgresql`, `mysql`) |
+| `--version`, `-v` | Engine version |
+| `--port`, `-p` | Port number |
+| `--database`, `-d` | Primary database name |
+| `--from` | Restore from backup file or connection string |
+| `--no-start` | Create without starting |
 
-#### PostgreSQL
+</details>
+
+#### `start` - Start a container
 
 ```bash
-# macOS (Homebrew) - use the latest PostgreSQL version (currently 17)
-brew install postgresql@17
-brew link --overwrite postgresql@17
+spindb start mydb
+```
 
-# Ubuntu/Debian
-sudo apt install postgresql-client
+#### `stop` - Stop a container
 
-# Arch
-sudo pacman -S postgresql-libs
+```bash
+spindb stop mydb
 ```
 
-#### MySQL
+#### `delete` - Delete a container
 
 ```bash
-# macOS (Homebrew)
-brew install mysql
+spindb delete mydb
+spindb delete mydb --force    # Skip confirmation
+```
 
-# Ubuntu/Debian
-sudo apt install mysql-server
+### Data Operations
+
+#### `connect` - Open database shell
 
-# Arch
-sudo pacman -S mysql
+```bash
+spindb connect mydb                 # Standard shell (psql/mysql)
+spindb connect mydb --pgcli         # Enhanced PostgreSQL shell
+spindb connect mydb --mycli         # Enhanced MySQL shell
+spindb connect mydb --tui           # Universal SQL client (usql)
 ```
 
-## Supported Platforms
+Install enhanced shells on-the-fly:
 
-- macOS (Apple Silicon & Intel)
-- Linux (x64 & ARM64)
+```bash
+spindb connect mydb --install-pgcli
+spindb connect mydb --install-mycli
+spindb connect mydb --install-tui
+```
 
-## Examples
+#### `run` - Execute SQL
 
-### Create databases
+```bash
+spindb run mydb script.sql                    # Run a SQL file
+spindb run mydb --sql "SELECT * FROM users"   # Run inline SQL
+spindb run mydb seed.sql --database my_app    # Target specific database
+```
+
+#### `url` - Get connection string
 
 ```bash
-# PostgreSQL with specific version and port
-spindb create mydb --engine postgresql --version 16 --port 5433
+spindb url mydb                    # postgresql://postgres@localhost:5432/mydb
+spindb url mydb --copy             # Copy to clipboard
+spindb url mydb --json             # JSON output with details
+
+# Use in scripts
+export DATABASE_URL=$(spindb url mydb)
+psql $(spindb url mydb)
+```
 
-# MySQL
-spindb create mydb --engine mysql --port 3307
+#### `backup` - Create a backup
 
-# With custom database name
-spindb create mydb --database my_app_db
+```bash
+spindb backup mydb                          # Auto-generated filename
+spindb backup mydb --name my-backup         # Custom name
+spindb backup mydb --output ./backups/      # Custom directory
+spindb backup mydb --database my_app        # Backup specific database
 ```
 
-### Create and restore in one command
+Backup formats:
 
 ```bash
-# Create and restore from a dump file
-spindb create mydb --from ./backup.dump
+spindb backup mydb --format sql     # Plain SQL (.sql)
+spindb backup mydb --format dump    # Compressed (.dump for PG, .sql.gz for MySQL)
 
-# Create and pull from a remote database
-spindb create mydb --from "postgresql://user:pass@remote-host:5432/production_db"
+# Shorthand
+spindb backup mydb --sql
+spindb backup mydb --dump
 ```
 
-### Clone for testing
+#### `restore` - Restore from backup
 
 ```bash
-# Stop the source container
-spindb stop production-copy
+spindb restore mydb backup.dump
+spindb restore mydb backup.sql --database my_app
+```
 
-# Clone it
-spindb clone production-copy test-branch
+### Container Management
 
-# Start the clone
-spindb start test-branch
+#### `list` - List all containers
+
+```bash
+spindb list
+spindb list --json
 ```
 
-### Connect to databases
+#### `info` - Show container details
 
 ```bash
-# Interactive shell (auto-detects engine)
-spindb connect mydb
+spindb info              # All containers
+spindb info mydb         # Specific container
+spindb info mydb --json
+```
 
-# Use pgcli/mycli for enhanced shell (dropdown auto-completion)
-spindb connect mydb --pgcli     # PostgreSQL
-spindb connect mydb --mycli     # MySQL
+#### `clone` - Clone a container
 
-# Install pgcli/mycli and connect in one command
-spindb connect mydb --install-pgcli
-spindb connect mydb --install-mycli
+```bash
+spindb stop source-db           # Source must be stopped
+spindb clone source-db new-db
+spindb start new-db
+```
 
-# Use usql for universal SQL client (works with both engines)
-spindb connect mydb --tui
-spindb connect mydb --install-tui
+#### `edit` - Rename or change port
+
+```bash
+spindb edit mydb --name newname   # Must be stopped
+spindb edit mydb --port 5433
+spindb edit mydb                  # Interactive mode
+```
 
-# Or use connection string directly
-psql postgresql://postgres@localhost:5432/mydb
-mysql -u root -h 127.0.0.1 -P 3306 mydb
+#### `logs` - View container logs
+
+```bash
+spindb logs mydb
+spindb logs mydb --follow       # Follow mode (like tail -f)
+spindb logs mydb -n 50          # Last 50 lines
+spindb logs mydb --editor       # Open in $EDITOR
 ```
 
-### Manage installed engines
+### Engine & System
 
-View installed engines with disk usage (PostgreSQL) and system detection (MySQL):
+#### `engines` - Manage installed engines
 
 ```bash
-spindb engines
+spindb engines                           # List installed engines
+spindb engines delete postgresql 16      # Delete a version (frees ~45MB)
 ```
 
+Example output:
+
 ```
 ENGINE        VERSION     SOURCE            SIZE
 ────────────────────────────────────────────────────────
@@ -297,84 +372,170 @@ PostgreSQL: 2 version(s), 90.0 MB
 MySQL: system-installed at /opt/homebrew/bin/mysqld
 ```
 
-Delete unused PostgreSQL versions to free disk space:
+#### `deps` - Manage client tools
 
 ```bash
-spindb engines delete postgresql 16
+spindb deps check                      # Check all dependencies
+spindb deps check --engine postgresql  # Check specific engine
+spindb deps install                    # Install missing tools
+spindb deps install --engine mysql     # Install for specific engine
 ```
 
-### Container info and connection strings
+#### `config` - Configuration
 
 ```bash
-# View all container details
-spindb info
+spindb config show                     # Show current configuration
+spindb config detect                   # Re-detect tool paths
+spindb config update-check on          # Enable update notifications
+spindb config update-check off         # Disable update notifications
+```
 
-# View specific container
-spindb info mydb
+#### `version` - Version info
 
-# 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
+```bash
+spindb version
+spindb version --check    # Check for updates
 ```
 
-### Backup databases
+#### `self-update` - Update SpinDB
 
 ```bash
-# Backup with default settings (SQL format, auto-generated filename)
-spindb backup mydb
+spindb self-update
+```
 
-# 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/
+## Enhanced CLI Tools
 
-# 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)
+SpinDB supports enhanced database shells that provide features like auto-completion, syntax highlighting, and better output formatting.
 
-# Shorthand flags
-spindb backup mydb --sql            # Same as --format sql
-spindb backup mydb --dump           # Same as --format dump
-```
+| Engine | Standard | Enhanced | Universal |
+|--------|----------|----------|-----------|
+| PostgreSQL | `psql` | `pgcli` | `usql` |
+| MySQL | `mysql` | `mycli` | `usql` |
+| SQLite (planned) | `sqlite3` | `litecli` | `usql` |
+| Redis (planned) | `redis-cli` | `iredis` | - |
+| MongoDB (planned) | `mongosh` | - | - |
+
+**pgcli / mycli** provide:
+- Intelligent auto-completion (tables, columns, keywords)
+- Syntax highlighting
+- Multi-line editing
+- Query history with search
 
-**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`)
+**usql** is a universal SQL client that works with any database. Great if you work with multiple engines.
 
-### Edit containers
+Install and connect in one command:
 
 ```bash
-# Rename a container (must be stopped)
-spindb edit mydb --name newname
+spindb connect mydb --install-pgcli
+spindb connect mydb --install-mycli
+spindb connect mydb --install-tui      # usql
+```
 
-# Change port
-spindb edit mydb --port 5433
+---
+
+## Architecture
+
+### Storage Layout
 
-# Interactive mode
-spindb edit mydb
+```
+~/.spindb/
+├── bin/                                    # Downloaded server binaries
+│   └── postgresql-17.7.0-darwin-arm64/     # ~45 MB per version
+├── containers/
+│   ├── postgresql/
+│   │   └── mydb/
+│   │       ├── container.json              # Configuration
+│   │       ├── data/                       # Database files
+│   │       └── postgres.log                # Server logs
+│   └── mysql/
+│       └── mydb/
+│           ├── container.json
+│           ├── data/
+│           └── mysql.log
+├── logs/                                   # Error logs
+└── config.json                             # Tool paths cache
 ```
 
-## Running Tests
+### How Data Persists
 
-```bash
-# Run all tests (PostgreSQL + MySQL)
-pnpm test
+SpinDB runs databases as **native processes** on your machine. When you start a container:
 
-# Run individual test suites
-pnpm test:pg
-pnpm test:mysql
-```
+1. SpinDB launches the database server binary (`pg_ctl start` or `mysqld`)
+2. The server binds to `127.0.0.1` on your configured port
+3. A PID file tracks the running process
+4. Logs are written to the container's log file
+
+When you stop a container:
+
+1. SpinDB sends a graceful shutdown signal
+2. The database flushes pending writes to disk
+3. The PID file is removed
+4. Your data remains in the `data/` directory
+
+**Your data is never deleted unless you explicitly delete the container.**
+
+### Binary Sources
+
+**PostgreSQL:** Server binaries are downloaded from [zonky.io/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries), a project that packages official PostgreSQL releases for embedding in applications. The binaries are hosted on Maven Central and support:
+- macOS (Apple Silicon and Intel)
+- Linux (x64 and ARM64)
+
+**MySQL:** Uses your system's MySQL installation. SpinDB detects binaries from Homebrew, apt, pacman, or custom paths.
+
+---
+
+## Supported Platforms
+
+| Platform | Architecture | Status |
+|----------|-------------|--------|
+| macOS | Apple Silicon (ARM64) | ✅ Supported |
+| macOS | Intel (x64) | ✅ Supported |
+| Linux | x64 | ✅ Supported |
+| Linux | ARM64 | ✅ Supported |
+| Windows | Any | ❌ Not supported |
+
+**Why no Windows?** The zonky.io project doesn't provide Windows binaries for PostgreSQL. Windows support would require a different binary source and significant testing.
+
+---
+
+## Limitations
+
+- **No Windows support** - zonky.io doesn't provide Windows PostgreSQL binaries
+- **Client tools required** - `psql` and `mysql` must be installed separately for some operations
+- **Local only** - Databases bind to `127.0.0.1`; remote connections planned for v1.1
+- **MySQL requires system install** - Unlike PostgreSQL, we don't download MySQL binaries
+
+---
+
+## Roadmap
+
+See [TODO.md](TODO.md) for the full roadmap.
+
+### v1.1 - Remote Connections & Secrets
+- Connect to remote databases
+- Environment variable support in connection strings
+- Secrets management (macOS Keychain)
+
+### v1.2 - Additional Engines
+- SQLite (file-based, no server)
+- Redis (in-memory key-value)
+- MongoDB (document database)
+- MariaDB as standalone engine
+
+### v1.3 - Advanced Features
+- Container templates
+- Scheduled backups
+- Import from Docker
+
+---
 
 ## Troubleshooting
 
 ### Port already in use
 
-SpinDB automatically finds an available port. You can also specify one:
+SpinDB automatically finds an available port. To specify one:
 
 ```bash
 spindb create mydb --port 5433
@@ -382,7 +543,7 @@ spindb create mydb --port 5433
 
 ### Client tool not found
 
-Install client tools or configure the path:
+Install client tools or configure manually:
 
 ```bash
 spindb deps install
@@ -395,8 +556,9 @@ spindb config set psql /path/to/psql
 Check the logs:
 
 ```bash
+spindb logs mydb
+# or read directly
 cat ~/.spindb/containers/postgresql/mydb/postgres.log
-cat ~/.spindb/containers/mysql/mydb/mysql.log
 ```
 
 ### Reset everything
@@ -405,73 +567,38 @@ 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
+See [CLAUDE.md](CLAUDE.md) for development setup and architecture documentation.
+
+### Running Tests
+
+```bash
+pnpm test           # All tests
+pnpm test:unit      # Unit tests only
+pnpm test:pg        # PostgreSQL integration
+pnpm test:mysql     # MySQL integration
+```
+
+---
+
+## Acknowledgments
 
-SpinDB uses versioned PostgreSQL packages from Homebrew (e.g., `postgresql@17`). When new major versions are released:
+SpinDB wouldn't be possible without:
 
-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`
+- **[zonky.io/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries)** - Pre-compiled PostgreSQL binaries that make Docker-free PostgreSQL possible. These binaries are extracted from official PostgreSQL distributions and hosted on Maven Central.
 
-See `CLAUDE.md` for detailed maintenance instructions.
+---
 
 ## License
 
-MIT
+[PolyForm Noncommercial 1.0.0](LICENSE)
+
+SpinDB is free for:
+- Personal use and hobby projects
+- Educational and research purposes
+- Nonprofit organizations, educational institutions, and government
+
+**SpinDB may not be used for commercial purposes.**