spindb 0.8.2 → 0.9.1

package/README.md

@@ -6,7 +6,7 @@
 
 **Local databases without the Docker baggage.**
 
-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.
+Spin up PostgreSQL, MySQL, and SQLite instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
 
 ---
 
@@ -176,11 +176,37 @@ spindb deps check --engine mysql
 
 **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.
 
+#### SQLite
+
+| | |
+|---|---|
+| Version | 3 (system) |
+| Default port | N/A (file-based) |
+| Data location | Project directory (CWD) |
+| Binary source | System installation |
+
+SQLite is a file-based database—no server process, no ports. Databases are stored in your project directory by default, not `~/.spindb/`. SpinDB tracks registered SQLite databases in a registry file.
+
+```bash
+# Create in current directory
+spindb create mydb --engine sqlite
+
+# Create with custom path
+spindb create mydb --engine sqlite --path ./data/mydb.sqlite
+
+# Connect to it
+spindb connect mydb
+
+# Use litecli for enhanced experience
+spindb connect mydb --litecli
+```
+
+**Note:** Unlike server databases, SQLite databases don't need to be "started" or "stopped"—they're always available as long as the file exists.
+
 ### Planned Engines
 
 | 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 |
 
@@ -195,10 +221,17 @@ spindb deps check --engine mysql
 ```bash
 spindb create mydb                           # PostgreSQL (default)
 spindb create mydb --engine mysql            # MySQL
+spindb create mydb --engine sqlite           # SQLite (file-based)
 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
+
+# Create, start, and connect in one command
+spindb create mydb --start --connect
+
+# SQLite with custom path
+spindb create mydb --engine sqlite --path ./data/app.sqlite
 ```
 
 Create and restore in one command:
@@ -213,13 +246,16 @@ spindb create mydb --from "postgresql://user:pass@host:5432/production"
 
 | Option | Description |
 |--------|-------------|
-| `--engine`, `-e` | Database engine (`postgresql`, `mysql`) |
+| `--engine`, `-e` | Database engine (`postgresql`, `mysql`, `sqlite`) |
 | `--version`, `-v` | Engine version |
-| `--port`, `-p` | Port number |
+| `--port`, `-p` | Port number (not applicable for SQLite) |
 | `--database`, `-d` | Primary database name |
+| `--path` | File path for SQLite databases |
 | `--max-connections` | Maximum database connections (default: 200) |
 | `--from` | Restore from backup file or connection string |
+| `--start` | Start container after creation (skip prompt) |
 | `--no-start` | Create without starting |
+| `--connect` | Open a shell connection after creation |
 
 </details>
 
@@ -333,11 +369,12 @@ spindb clone source-db new-db
 spindb start new-db
 ```
 
-#### `edit` - Rename, change port, or edit database config
+#### `edit` - Rename, change port, relocate, or edit database config
 
 ```bash
 spindb edit mydb --name newname              # Must be stopped
 spindb edit mydb --port 5433
+spindb edit mydb --relocate ~/new/path       # Move SQLite database file
 spindb edit mydb --set-config max_connections=300   # PostgreSQL config
 spindb edit mydb                             # Interactive mode
 ```
@@ -368,10 +405,12 @@ ENGINE        VERSION     SOURCE            SIZE
 🐘 postgresql 17.7        darwin-arm64      45.2 MB
 🐘 postgresql 16.8        darwin-arm64      44.8 MB
 🐬 mysql      8.0.35      system            (system-installed)
+🪶 sqlite     3.43.2      system            (system-installed)
 ────────────────────────────────────────────────────────
 
 PostgreSQL: 2 version(s), 90.0 MB
 MySQL: system-installed at /opt/homebrew/bin/mysqld
+SQLite: system-installed at /usr/bin/sqlite3
 ```
 
 #### `deps` - Manage client tools
@@ -405,6 +444,43 @@ spindb version --check    # Check for updates
 spindb self-update
 ```
 
+#### `doctor` - System health check
+
+```bash
+spindb doctor            # Interactive health check
+spindb doctor --json     # JSON output for scripting
+```
+
+Checks performed:
+- Configuration file validity and binary cache freshness
+- Container status across all engines
+- SQLite registry for orphaned entries (files deleted outside SpinDB)
+- Database tool availability
+
+Example output:
+
+```
+SpinDB Health Check
+═══════════════════
+
+✓ Configuration
+  └─ Configuration valid, 12 tools cached
+
+✓ Containers
+  └─ 4 container(s)
+     postgresql: 2 running, 0 stopped
+     mysql: 0 running, 1 stopped
+     sqlite: 1 exist, 0 missing
+
+⚠ SQLite Registry
+  └─ 1 orphaned entry found
+     "old-project" → /path/to/missing.sqlite
+
+? What would you like to do?
+❯ Remove orphaned entries from registry
+  Skip (do nothing)
+```
+
 ---
 
 ## Enhanced CLI Tools
@@ -415,7 +491,7 @@ SpinDB supports enhanced database shells that provide features like auto-complet
 |--------|----------|----------|-----------|
 | PostgreSQL | `psql` | `pgcli` | `usql` |
 | MySQL | `mysql` | `mycli` | `usql` |
-| SQLite (planned) | `sqlite3` | `litecli` | `usql` |
+| SQLite | `sqlite3` | `litecli` | `usql` |
 | Redis (planned) | `redis-cli` | `iredis` | - |
 | MongoDB (planned) | `mongosh` | - | - |
 
@@ -456,8 +532,13 @@ spindb connect mydb --install-tui      # usql
 │           ├── container.json
 │           ├── data/
 │           └── mysql.log
+├── sqlite-registry.json                    # Tracks SQLite file locations
 ├── logs/                                   # Error logs
 └── config.json                             # Tool paths cache
+
+# SQLite databases are stored in project directories, not ~/.spindb/
+./myproject/
+└── mydb.sqlite                             # Created with: spindb create mydb -e sqlite
 ```
 
 ### How Data Persists
@@ -521,7 +602,6 @@ See [TODO.md](TODO.md) for the full roadmap.
 - 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

package/cli/commands/clone.ts

@@ -71,6 +71,12 @@ export const cloneCommand = new Command('clone')
         targetName = await promptContainerName(`${sourceName}-copy`)
       }
 
+      // Check if target container already exists
+      if (await containerManager.exists(targetName, { engine: sourceConfig.engine })) {
+        console.error(error(`Container "${targetName}" already exists`))
+        process.exit(1)
+      }
+
       const cloneSpinner = createSpinner(
         `Cloning ${sourceName} to ${targetName}...`,
       )

package/cli/commands/connect.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
+import { existsSync } from 'fs'
 import chalk from 'chalk'
 import { containerManager } from '../../core/container-manager'
 import { processManager } from '../../core/process-manager'
@@ -7,18 +8,22 @@ import {
   isUsqlInstalled,
   isPgcliInstalled,
   isMycliInstalled,
+  isLitecliInstalled,
   detectPackageManager,
   installUsql,
   installPgcli,
   installMycli,
+  installLitecli,
   getUsqlManualInstructions,
   getPgcliManualInstructions,
   getMycliManualInstructions,
+  getLitecliManualInstructions,
 } from '../../core/dependency-manager'
 import { getEngine } from '../../engines'
 import { getEngineDefaults } from '../../config/defaults'
 import { promptContainerSelect } from '../ui/prompts'
 import { error, warning, info, success } from '../ui/theme'
+import { Engine } from '../../types'
 
 export const connectCommand = new Command('connect')
   .alias('shell')
@@ -37,6 +42,11 @@ export const connectCommand = new Command('connect')
     'Use mycli for enhanced MySQL shell (dropdown auto-completion)',
   )
   .option('--install-mycli', 'Install mycli if not present, then connect')
+  .option(
+    '--litecli',
+    'Use litecli for enhanced SQLite shell (auto-completion, syntax highlighting)',
+  )
+  .option('--install-litecli', 'Install litecli if not present, then connect')
   .action(
     async (
       name: string | undefined,
@@ -48,6 +58,8 @@ export const connectCommand = new Command('connect')
         installPgcli?: boolean
         mycli?: boolean
         installMycli?: boolean
+        litecli?: boolean
+        installLitecli?: boolean
       },
     ) => {
       try {
@@ -55,9 +67,15 @@ export const connectCommand = new Command('connect')
 
         if (!containerName) {
           const containers = await containerManager.list()
-          const running = containers.filter((c) => c.status === 'running')
+          // SQLite containers are always "available" if file exists, server containers need to be running
+          const connectable = containers.filter((c) => {
+            if (c.engine === Engine.SQLite) {
+              return existsSync(c.database)
+            }
+            return c.status === 'running'
+          })
 
-          if (running.length === 0) {
+          if (connectable.length === 0) {
             if (containers.length === 0) {
               console.log(
                 warning('No containers found. Create one with: spindb create'),
@@ -73,7 +91,7 @@ export const connectCommand = new Command('connect')
           }
 
           const selected = await promptContainerSelect(
-            running,
+            connectable,
             'Select container to connect to:',
           )
           if (!selected) return
@@ -92,16 +110,29 @@ export const connectCommand = new Command('connect')
         const database =
           options.database ?? config.database ?? engineDefaults.superuser
 
-        const running = await processManager.isRunning(containerName, {
-          engine: engineName,
-        })
-        if (!running) {
-          console.error(
-            error(
-              `Container "${containerName}" is not running. Start it first.`,
-            ),
-          )
-          process.exit(1)
+        // SQLite: check file exists instead of running status
+        if (engineName === Engine.SQLite) {
+          if (!existsSync(config.database)) {
+            console.error(
+              error(
+                `SQLite database file not found: ${config.database}`,
+              ),
+            )
+            process.exit(1)
+          }
+        } else {
+          // Server databases need to be running
+          const running = await processManager.isRunning(containerName, {
+            engine: engineName,
+          })
+          if (!running) {
+            console.error(
+              error(
+                `Container "${containerName}" is not running. Start it first.`,
+              ),
+            )
+            process.exit(1)
+          }
         }
 
         const engine = getEngine(engineName)
@@ -275,13 +306,74 @@ export const connectCommand = new Command('connect')
           }
         }
 
+        const useLitecli = options.litecli || options.installLitecli
+        if (useLitecli) {
+          if (engineName !== Engine.SQLite) {
+            console.error(error('litecli is only available for SQLite containers'))
+            if (engineName === 'postgresql') {
+              console.log(chalk.gray('For PostgreSQL, use: spindb connect --pgcli'))
+            } else if (engineName === 'mysql') {
+              console.log(chalk.gray('For MySQL, use: spindb connect --mycli'))
+            }
+            process.exit(1)
+          }
+
+          const litecliInstalled = await isLitecliInstalled()
+
+          if (!litecliInstalled) {
+            if (options.installLitecli) {
+              console.log(info('Installing litecli for enhanced SQLite shell...'))
+              const pm = await detectPackageManager()
+              if (pm) {
+                const result = await installLitecli(pm)
+                if (result.success) {
+                  console.log(success('litecli installed successfully!'))
+                  console.log()
+                } else {
+                  console.error(
+                    error(`Failed to install litecli: ${result.error}`),
+                  )
+                  console.log()
+                  console.log(chalk.gray('Manual installation:'))
+                  for (const instruction of getLitecliManualInstructions()) {
+                    console.log(chalk.cyan(`  ${instruction}`))
+                  }
+                  process.exit(1)
+                }
+              } else {
+                console.error(error('No supported package manager found'))
+                console.log()
+                console.log(chalk.gray('Manual installation:'))
+                for (const instruction of getLitecliManualInstructions()) {
+                  console.log(chalk.cyan(`  ${instruction}`))
+                }
+                process.exit(1)
+              }
+            } else {
+              console.error(error('litecli is not installed'))
+              console.log()
+              console.log(chalk.gray('Install litecli for enhanced SQLite shell:'))
+              console.log(chalk.cyan('  spindb connect --install-litecli'))
+              console.log()
+              console.log(chalk.gray('Or install manually:'))
+              for (const instruction of getLitecliManualInstructions()) {
+                console.log(chalk.cyan(`  ${instruction}`))
+              }
+              process.exit(1)
+            }
+          }
+        }
+
         console.log(info(`Connecting to ${containerName}:${database}...`))
         console.log()
 
         let clientCmd: string
         let clientArgs: string[]
 
-        if (usePgcli) {
+        if (useLitecli) {
+          clientCmd = 'litecli'
+          clientArgs = [config.database]
+        } else if (usePgcli) {
           clientCmd = 'pgcli'
           clientArgs = [connectionString]
         } else if (useMycli) {
@@ -298,6 +390,9 @@ export const connectCommand = new Command('connect')
         } else if (useUsql) {
           clientCmd = 'usql'
           clientArgs = [connectionString]
+        } else if (engineName === Engine.SQLite) {
+          clientCmd = 'sqlite3'
+          clientArgs = [config.database]
         } else if (engineName === 'mysql') {
           clientCmd = 'mysql'
           clientArgs = [
@@ -339,6 +434,12 @@ export const connectCommand = new Command('connect')
             } else if (clientCmd === 'mycli') {
               console.log(chalk.gray('  Install mycli:'))
               console.log(chalk.cyan('  brew install mycli'))
+            } else if (clientCmd === 'litecli') {
+              console.log(chalk.gray('  Install litecli:'))
+              console.log(chalk.cyan('  brew install litecli'))
+            } else if (clientCmd === 'sqlite3') {
+              console.log(chalk.gray('  sqlite3 comes with macOS.'))
+              console.log(chalk.gray('  If not available, check your PATH.'))
             } else if (engineName === 'mysql') {
               console.log(chalk.gray('  On macOS with Homebrew:'))
               console.log(chalk.cyan('  brew install mysql-client'))

package/cli/commands/create.ts

@@ -20,7 +20,109 @@ 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 { isValidDatabaseName } from '../../core/error-handler'
 import { Engine } from '../../types'
+import type { BaseEngine } from '../../engines/base-engine'
+import { resolve } from 'path'
+
+/**
+ * Simplified SQLite container creation flow
+ * SQLite is file-based, so no port, start/stop, or server management needed
+ */
+async function createSqliteContainer(
+  containerName: string,
+  dbEngine: BaseEngine,
+  version: string,
+  options: { path?: string; from?: string | null; connect?: boolean },
+): Promise<void> {
+  const { path: filePath, from: restoreLocation, connect } = options
+
+  // Check dependencies
+  const depsSpinner = createSpinner('Checking required tools...')
+  depsSpinner.start()
+
+  const missingDeps = await getMissingDependencies('sqlite')
+  if (missingDeps.length > 0) {
+    depsSpinner.warn(`Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`)
+    const installed = await promptInstallDependencies(missingDeps[0].binary, 'sqlite')
+    if (!installed) {
+      process.exit(1)
+    }
+  } else {
+    depsSpinner.succeed('Required tools available')
+  }
+
+  // Check if container already exists
+  while (await containerManager.exists(containerName)) {
+    console.log(chalk.yellow(`  Container "${containerName}" already exists.`))
+    containerName = await promptContainerName()
+  }
+
+  // Determine file path
+  const defaultPath = `./${containerName}.sqlite`
+  const absolutePath = resolve(filePath || defaultPath)
+
+  // Check if file already exists
+  if (existsSync(absolutePath)) {
+    console.error(error(`File already exists: ${absolutePath}`))
+    process.exit(1)
+  }
+
+  const createSpinnerInstance = createSpinner('Creating SQLite database...')
+  createSpinnerInstance.start()
+
+  try {
+    // Initialize the SQLite database file and register in registry
+    await dbEngine.initDataDir(containerName, version, { path: absolutePath })
+    createSpinnerInstance.succeed('SQLite database created')
+  } catch (err) {
+    createSpinnerInstance.fail('Failed to create SQLite database')
+    throw err
+  }
+
+  // Handle --from restore
+  if (restoreLocation) {
+    const config = await containerManager.getConfig(containerName)
+    if (config) {
+      const format = await dbEngine.detectBackupFormat(restoreLocation)
+      const restoreSpinner = createSpinner(`Restoring from ${format.description}...`)
+      restoreSpinner.start()
+
+      try {
+        await dbEngine.restore(config, restoreLocation)
+        restoreSpinner.succeed('Backup restored successfully')
+      } catch (err) {
+        restoreSpinner.fail('Failed to restore backup')
+        throw err
+      }
+    }
+  }
+
+  // Display success
+  console.log()
+  console.log(chalk.green('  ✓ SQLite database ready'))
+  console.log()
+  console.log(chalk.gray('  File path:'))
+  console.log(chalk.cyan(`    ${absolutePath}`))
+  console.log()
+  console.log(chalk.gray('  Connection string:'))
+  console.log(chalk.cyan(`    sqlite:///${absolutePath}`))
+  console.log()
+
+  // Connect if requested
+  if (connect) {
+    const config = await containerManager.getConfig(containerName)
+    if (config) {
+      console.log(chalk.gray('  Opening shell...'))
+      console.log()
+      await dbEngine.connect(config)
+    }
+  } else {
+    console.log(chalk.gray('  Connect with:'))
+    console.log(chalk.cyan(`    spindb connect ${containerName}`))
+    console.log()
+  }
+}
 
 function detectLocationType(location: string): {
   type: 'connection' | 'file' | 'not_found'
@@ -37,7 +139,16 @@ function detectLocationType(location: string): {
     return { type: 'connection', inferredEngine: Engine.MySQL }
   }
 
+  if (location.startsWith('sqlite://')) {
+    return { type: 'connection', inferredEngine: Engine.SQLite }
+  }
+
   if (existsSync(location)) {
+    // Check if it's a SQLite file (case-insensitive)
+    const lowerLocation = location.toLowerCase()
+    if (lowerLocation.endsWith('.sqlite') || lowerLocation.endsWith('.db') || lowerLocation.endsWith('.sqlite3')) {
+      return { type: 'file', inferredEngine: Engine.SQLite }
+    }
     return { type: 'file' }
   }
 
@@ -47,15 +158,21 @@ function detectLocationType(location: string): {
 export const createCommand = new Command('create')
   .description('Create a new database container')
   .argument('[name]', 'Container name')
-  .option('-e, --engine <engine>', 'Database engine (postgresql, mysql)')
+  .option('-e, --engine <engine>', 'Database engine (postgresql, mysql, sqlite)')
   .option('-v, --version <version>', 'Database version')
   .option('-d, --database <database>', 'Database name')
   .option('-p, --port <port>', 'Port number')
+  .option(
+    '--path <path>',
+    'Path for SQLite database file (default: ./<name>.sqlite)',
+  )
   .option(
     '--max-connections <number>',
     'Maximum number of database connections (default: 200)',
   )
+  .option('--start', 'Start the container after creation (skip prompt)')
   .option('--no-start', 'Do not start the container after creation')
+  .option('--connect', 'Open a shell connection after creation')
   .option(
     '--from <location>',
     'Restore from a dump file or connection string after creation',
@@ -68,8 +185,10 @@ export const createCommand = new Command('create')
         version?: string
         database?: string
         port?: string
+        path?: string
         maxConnections?: string
-        start: boolean
+        start?: boolean
+        connect?: boolean
         from?: string
       },
     ) => {
@@ -135,11 +254,41 @@ export const createCommand = new Command('create')
 
         database = database ?? containerName
 
+        // Validate database name to prevent SQL injection
+        if (!isValidDatabaseName(database)) {
+          console.error(
+            error(
+              'Database name must start with a letter and contain only letters, numbers, hyphens, and underscores',
+            ),
+          )
+          process.exit(1)
+        }
+
         console.log(header('Creating Database Container'))
         console.log()
 
         const dbEngine = getEngine(engine)
 
+        // SQLite has a simplified flow (no port, no start/stop)
+        if (engine === Engine.SQLite) {
+          await createSqliteContainer(containerName, dbEngine, version, {
+            path: options.path,
+            from: restoreLocation,
+            connect: options.connect,
+          })
+          return
+        }
+
+        // For server databases, validate --connect with --no-start
+        if (options.connect && options.start === false) {
+          console.error(
+            error(
+              'Cannot use --no-start with --connect (connection requires running container)',
+            ),
+          )
+          process.exit(1)
+        }
+
         const depsSpinner = createSpinner('Checking required tools...')
         depsSpinner.start()
 
@@ -272,9 +421,12 @@ export const createCommand = new Command('create')
           throw err
         }
 
-        // --from requires start, --no-start skips, otherwise ask user
+        // --from requires start, --start forces start, --no-start skips, otherwise ask user
+        // --connect implies --start for server databases
         let shouldStart = false
-        if (restoreLocation) {
+        if (restoreLocation || options.connect) {
+          shouldStart = true
+        } else if (options.start === true) {
           shouldStart = true
         } else if (options.start === false) {
           shouldStart = false
@@ -430,7 +582,7 @@ export const createCommand = new Command('create')
             createDatabase: false,
           })
 
-          if (result.code === 0 || !result.stderr) {
+          if (result.code === 0) {
             restoreSpinner.succeed('Backup restored successfully')
           } else {
             restoreSpinner.warn('Restore completed with warnings')
@@ -461,7 +613,17 @@ export const createCommand = new Command('create')
           )
           console.log()
 
-          if (shouldStart) {
+          if (options.connect && shouldStart) {
+            // --connect flag: open shell directly
+            const copied =
+              await platformService.copyToClipboard(connectionString)
+            if (copied) {
+              console.log(chalk.gray('  Connection string copied to clipboard'))
+            }
+            console.log(chalk.gray('  Opening shell...'))
+            console.log()
+            await dbEngine.connect(finalConfig, database)
+          } else if (shouldStart) {
             console.log(chalk.gray('  Connect with:'))
             console.log(chalk.cyan(`  spindb connect ${containerName}`))
 
@@ -470,12 +632,12 @@ export const createCommand = new Command('create')
             if (copied) {
               console.log(chalk.gray('  Connection string copied to clipboard'))
             }
+            console.log()
           } else {
             console.log(chalk.gray('  Start the container:'))
             console.log(chalk.cyan(`  spindb start ${containerName}`))
+            console.log()
           }
-
-          console.log()
         }
       } catch (err) {
         const e = err as Error