spindb 0.5.2 → 0.5.4

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 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 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/`:
@@ -91,6 +107,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.
@@ -109,12 +163,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
 
@@ -187,6 +243,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
@@ -194,15 +262,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 +363,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