spindb 0.1.0 → 0.2.0

package/.claude/settings.local.json

@@ -12,7 +12,12 @@
       "Bash(node bin/cli.js:*)",
       "Bash(pnpm add:*)",
       "Bash(pnpm run format:*)",
-      "Bash(pnpm run lint:*)"
+      "Bash(pnpm run lint:*)",
+      "Bash(node /Users/bob/dev/db-container/bin/cli.js:*)",
+      "Bash(node -e \"\nconst { fetchAvailableVersions, SUPPORTED_MAJOR_VERSIONS } = require(''./src/engines/postgresql/binary-urls.ts'');\n\")",
+      "Bash(node --import tsx bin/cli.js:*)",
+      "Bash(node --import tsx:*)",
+      "Bash(cat:*)"
     ],
     "deny": [],
     "ask": []

package/CLAUDE.md

@@ -78,6 +78,28 @@ Client tools (psql, pg_restore) are detected from the system. The `config-manage
 ### Interactive Menu
 When `spindb` is run with no arguments, it shows an interactive menu (`src/cli/commands/menu.ts`) using Inquirer's list prompt. Users navigate with arrow keys.
 
+**Menu Navigation Rules:**
+- Any submenu with a "Back" button that goes to a parent menu (not main menu) MUST also have a "Back to main menu" option
+- Back buttons use blue color: `${chalk.blue('←')} Back to...`
+- Main menu buttons use house emoji: `${chalk.blue('🏠')} Back to main menu`
+
+### Container Config
+Each container has a `container.json` with:
+```typescript
+type ContainerConfig = {
+  name: string
+  engine: string
+  version: string
+  port: number
+  database: string      // User's database name (separate from container name)
+  created: string
+  status: 'created' | 'running' | 'stopped'
+  clonedFrom?: string
+}
+```
+
+The `database` field allows users to specify a custom database name in the connection string (e.g., `postgresql://postgres@localhost:5432/my-app-db`).
+
 ## Common Tasks
 
 ### Running the CLI
@@ -112,17 +134,24 @@ import { platform, arch } from 'os';
 // Mapped to zonky.io names in defaults.ts platformMappings
 ```
 
-### Version Mapping
-Major versions (14, 15, 16, 17) map to full versions in `src/engines/postgresql/binary-urls.ts`:
+### Version Fetching
+PostgreSQL versions are fetched dynamically from Maven Central with a 5-minute cache. Falls back to `FALLBACK_VERSION_MAP` if network fails. See `src/engines/postgresql/binary-urls.ts`:
+
 ```typescript
-const VERSION_MAP = {
-  '14': '14.15.0',
-  '15': '15.10.0',
-  '16': '16.6.0',
-  '17': '17.2.0'
-};
+// Fallback versions (used when Maven is unreachable)
+export const FALLBACK_VERSION_MAP: Record<string, string> = {
+  '14': '14.20.0',
+  '15': '15.15.0',
+  '16': '16.11.0',
+  '17': '17.7.0',
+}
+
+// Dynamic fetching from Maven
+export async function fetchAvailableVersions(): Promise<Record<string, string[]>>
 ```
 
+The create flow uses two-step version selection: first major version (14, 15, 16, 17), then specific minor version within that major.
+
 ### Port Management
 - Default port: 5432
 - If busy, scans 5432-5500 for available port
@@ -142,15 +171,16 @@ PID file location: `~/.spindb/containers/{name}/data/postmaster.pid`
 1. **No client tools bundled** - psql/pg_restore must be installed separately
 2. **macOS/Linux only** - No Windows support (zonky.io doesn't provide Windows binaries)
 3. **No backup command** - pg_dump must be run manually with system tools
-4. **No automatic updates** - Binary versions are hardcoded in VERSION_MAP
+4. **Database names immutable** - Cannot rename database after creation (would require `ALTER DATABASE`)
 
-## Future Improvements (Not Implemented)
+## Future Improvements
 
+See `TODO.md` for full list. Key items:
 - [ ] Add `spindb backup` command (wrapper around pg_dump)
-- [ ] Support MySQL/SQLite engines (architecture supports it)
 - [ ] Add `spindb logs` command to tail postgres.log
 - [ ] Add `spindb exec` for running SQL files
-- [ ] Automatic binary version updates
+- [ ] Database rename support
+- [ ] Support MySQL/SQLite engines (architecture supports it)
 - [ ] Windows support (would need different binary source)
 
 ## Code Style Notes

package/README.md

@@ -10,6 +10,9 @@ Spin up local PostgreSQL databases without Docker. A lightweight alternative to
 - **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)
+- **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
 
 ## Installation
 
@@ -109,10 +112,15 @@ spindb config set pg_restore /path/to/pg_restore
 
 ## Examples
 
-### Create a database with specific version
+### Create a database with specific version and name
 
 ```bash
+# Specify PostgreSQL version and port
 spindb create mydb --pg-version 15 --port 5433
+
+# Specify a custom database name (different from container name)
+spindb create mydb --database my_app_db
+# Connection string: postgresql://postgres@localhost:5432/my_app_db
 ```
 
 ### Restore a backup
@@ -145,7 +153,21 @@ spindb start test-branch
 spindb connect mydb
 
 # Or use the connection string directly
-psql postgresql://postgres@localhost:5432/postgres
+psql postgresql://postgres@localhost:5432/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.
+
+```
+ENGINE      VERSION     PLATFORM            SIZE
+────────────────────────────────────────────────────────
+postgresql  17          darwin-arm64        45.2 MB
+postgresql  16.9.0      darwin-arm64        44.8 MB
+postgresql  16          darwin-arm64        44.8 MB
+────────────────────────────────────────────────────────
+3 version(s)                                134.8 MB
 ```
 
 ## Configuration
@@ -201,4 +223,3 @@ rm -rf ~/.spindb
 ## License
 
 MIT
-# spindb

package/TODO.md

@@ -14,16 +14,25 @@ Similar to ngrok - free tier for individual developers with core functionality,
 - [ ] **Run SQL file** - Add menu option to run a `.sql` file against a container (wrapper around `psql -f`)
 - [ ] **Backup command** - Add `spindb backup` to create dumps using `pg_dump`
 - [ ] **Logs command** - Add `spindb logs <container>` to tail `postgres.log`
-- [ ] **Engine/binary management** - Menu to list installed PostgreSQL versions, install new versions, uninstall unused versions (free up disk space)
+- [x] **Engine/binary management** - Menu to list installed PostgreSQL versions, install new versions, uninstall unused versions (free up disk space)
 
 ### Medium Priority
-- [ ] **Container rename** - Rename a container without cloning/deleting
-- [ ] **Export connection string** - Copy connection string to clipboard
+- [x] **Container rename** - Rename a container without cloning/deleting (via Edit menu)
+- [ ] **Database rename** - Rename a database within a container (requires stopping container, running `ALTER DATABASE ... RENAME TO ...`, updating config)
+- [x] **Export connection string** - Copy connection string to clipboard (via container submenu)
 - [ ] **Multiple databases per container** - List/create/delete databases within a container
+- [x] **Fetch available versions** - Query Maven Central API to show all available PostgreSQL versions instead of hardcoded list
 
 ### Low Priority
 - [ ] **SQLite support** - Add SQLite engine
 - [ ] **Health checks** - Periodic connection tests to verify containers are responsive
+- [ ] **Offline Support** - Package binaries locally for offline installation
+- [ ] **Binary caching** - Cache downloaded binaries locally to avoid re-downloading
+- [ ] **Binary version management** - List, install, and remove different PostgreSQL versions
+- [ ] **Binary verification** - Verify downloaded binaries with checksums
+- [ ] **Binary cleanup** - Remove old cached binaries to free up disk space
+- [ ] **Binary space monitoring** - Show disk usage of cached binaries
+- [ ] **Binary auto-cleanup** - Automatically remove old versions after a retention period
 
 ---
 

package/eslint.config.js

@@ -5,9 +5,15 @@ export default tseslint.config(
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ['dist/', 'node_modules/', 'bin/'],
+    ignores: ['dist/', 'node_modules/', 'bin/', 'eslint.config.js'],
   },
   {
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
     rules: {
       '@typescript-eslint/no-unused-vars': [
         'error',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL.",
   "type": "module",
   "bin": {

package/src/cli/commands/create.ts

@@ -17,6 +17,7 @@ export const createCommand = new Command('create')
     'PostgreSQL version',
     defaults.postgresVersion,
   )
+  .option('-d, --database <database>', 'Database name')
   .option('-p, --port <port>', 'Port number')
   .option('--no-start', 'Do not start the container after creation')
   .action(
@@ -25,6 +26,7 @@ export const createCommand = new Command('create')
       options: {
         engine: string
         pgVersion: string
+        database?: string
         port?: string
         start: boolean
       },
@@ -33,6 +35,7 @@ export const createCommand = new Command('create')
         let containerName = name
         let engine = options.engine
         let version = options.pgVersion
+        let database = options.database
 
         // Interactive mode if no name provided
         if (!containerName) {
@@ -40,8 +43,12 @@ export const createCommand = new Command('create')
           containerName = answers.name
           engine = answers.engine
           version = answers.version
+          database = answers.database
         }
 
+        // Default database name to container name if not specified
+        database = database ?? containerName
+
         console.log(header('Creating Database Container'))
         console.log()
 
@@ -97,19 +104,20 @@ export const createCommand = new Command('create')
           engine: dbEngine.name,
           version,
           port,
+          database,
         })
 
         createSpinnerInstance.succeed('Container created')
 
-        // Initialize database
-        const initSpinner = createSpinner('Initializing database...')
+        // Initialize database cluster
+        const initSpinner = createSpinner('Initializing database cluster...')
         initSpinner.start()
 
         await dbEngine.initDataDir(containerName, version, {
           superuser: defaults.superuser,
         })
 
-        initSpinner.succeed('Database initialized')
+        initSpinner.succeed('Database cluster initialized')
 
         // Start container if requested
         if (options.start !== false) {
@@ -125,6 +133,18 @@ export const createCommand = new Command('create')
           }
 
           startSpinner.succeed('PostgreSQL started')
+
+          // Create the user's database (if different from 'postgres')
+          if (config && database !== 'postgres') {
+            const dbSpinner = createSpinner(
+              `Creating database "${database}"...`,
+            )
+            dbSpinner.start()
+
+            await dbEngine.createDatabase(config, database)
+
+            dbSpinner.succeed(`Database "${database}" created`)
+          }
         }
 
         // Show success message