spindb 0.30.1 → 0.30.7

package/README.md

@@ -386,6 +386,36 @@ Generated files:
 - `entrypoint.sh` - Startup script
 - `README.md` - Instructions
 
+### Deploying Your Container
+
+**SpinDB doesn't require Docker for local development**, but it can repackage your database as a Docker image for deployment to cloud servers, EC2 instances, Kubernetes clusters, or any Docker-compatible environment.
+
+```bash
+# Export your local database to Docker
+spindb export docker mydb -o ./mydb-deploy
+
+# Build and run
+cd ./mydb-deploy
+docker compose build --no-cache
+docker compose up -d
+
+# Connect from host (credentials in .env)
+source .env
+psql "postgresql://$SPINDB_USER:$SPINDB_PASSWORD@localhost:$PORT/$DATABASE"
+```
+
+**Schema-only vs Full Data:**
+```bash
+spindb export docker mydb                    # Include all data (default)
+spindb export docker mydb --no-data          # Schema only (empty tables)
+```
+
+> **Development Tool Notice:** SpinDB is currently a development tool. While Docker exports include TLS encryption and authentication, they are intended for staging and testing—not production workloads. For production databases, consider managed services.
+
+**Future Export Options:** Additional export targets are planned for future releases, including direct deployment to managed database services like Neon, Supabase, and PlanetScale.
+
+See [DEPLOY.md](DEPLOY.md) for comprehensive deployment documentation.
+
 ### Container Management
 
 ```bash
@@ -433,7 +463,8 @@ spindb deps install                             # Install missing tools
 # Configuration
 spindb config show                              # Show current config
 spindb config detect                            # Re-detect tool paths
-spindb config update-check on                   # Enable update notifications
+spindb config update-check on                   # Enable update checks
+spindb config update-check off                  # Disable update checks
 
 # Doctor
 spindb doctor                                   # Interactive health check

package/cli/commands/menu/container-handlers.ts

@@ -66,7 +66,7 @@ import { Engine, isFileBasedEngine } from '../../../types'
 import { type MenuChoice, pressEnterToContinue } from './shared'
 import { getEngineIcon } from '../../constants'
 
-export async function handleCreate(): Promise<'main' | void> {
+export async function handleCreate(): Promise<'main' | string | void> {
   console.log()
   console.log(header('Create New Database Container'))
   console.log()
@@ -342,11 +342,11 @@ export async function handleCreate(): Promise<'main' | void> {
         {
           type: 'input',
           name: 'continue',
-          message: chalk.gray('Press Enter to return to the main menu...'),
+          message: chalk.gray('Press Enter to continue...'),
         },
       ])
     }
-    return
+    return containerNameFinal
   }
 
   // Server databases: start and create database
@@ -410,7 +410,7 @@ export async function handleCreate(): Promise<'main' | void> {
         {
           type: 'input',
           name: 'continue',
-          message: chalk.gray('Press Enter to return to the main menu...'),
+          message: chalk.gray('Press Enter to continue...'),
         },
       ])
     }
@@ -426,7 +426,18 @@ export async function handleCreate(): Promise<'main' | void> {
         `Start it later with: ${chalk.cyan(`spindb start ${containerNameFinal}`)}`,
       ),
     )
+    console.log()
+
+    await escapeablePrompt([
+      {
+        type: 'input',
+        name: 'continue',
+        message: chalk.gray('Press Enter to continue...'),
+      },
+    ])
   }
+
+  return containerNameFinal
 }
 
 export async function handleList(
@@ -557,14 +568,13 @@ export async function handleList(
     (c) => !isFileBasedEngine(c.engine),
   )
 
-  // Build hints string (bottom of list)
-  const hints = hasServerContainers ? chalk.gray('[Shift]+[Tab] - toggle') : ''
-
-  // Build the full choice list with footer items
-  const summary = hints
-    ? `${containers.length} container(s): ${parts.join('; ')} — ${hints}`
-    : `${containers.length} container(s): ${parts.join('; ')}`
+  // Build the full choice list with header hint and footer items
+  const summary = `${containers.length} container(s): ${parts.join('; ')}`
   const allChoices: (FilterableChoice | inquirer.Separator)[] = [
+    // Show toggle hint at top when server-based containers exist
+    ...(hasServerContainers
+      ? [new inquirer.Separator(chalk.cyan('── [Shift+Tab] toggle start/stop ──'))]
+      : []),
     ...containerChoices,
     new inquirer.Separator(),
     new inquirer.Separator(summary),
@@ -694,12 +704,14 @@ export async function showContainerSubmenu(
   // Build action choices based on engine type
   const actionChoices: MenuChoice[] = []
 
-  // Helper for disabled menu items - passes hint to inquirer's disabled property
-  const disabledItem = (icon: string, label: string, hint: string) => ({
-    name: chalk.gray(`${icon} ${label}`),
-    value: '_disabled_',
-    disabled: chalk.gray(hint), // String value shows as the reason instead of "(Disabled)"
-  })
+  // Helper for disabled menu items (hint shown in separator, not on each item)
+  function disabledItem(icon: string, label: string) {
+    return {
+      name: chalk.gray(`${icon} ${label}`),
+      value: '_disabled_',
+      disabled: '', // Empty string hides the "(Disabled)" text
+    }
+  }
 
   // Determine if database-specific actions can be performed
   // Requires: database selected + (running for server DBs OR file exists for file-based DBs)
@@ -707,13 +719,25 @@ export async function showContainerSubmenu(
   const hasMultipleDatabases = databases.length > 1
   const canDoDbAction = !!activeDatabase && containerReady
 
-  // Hint for disabled database actions
-  const getDbActionHint = () => {
-    if (!activeDatabase && hasMultipleDatabases) return 'Select database first'
+  // Label for data section separator - shows state or required action
+  function getDataSectionLabel(): string {
     if (!containerReady) {
       return isFileBasedDB ? 'Database file missing' : 'Start container first'
     }
-    return 'Select database first'
+    if (!activeDatabase && hasMultipleDatabases) {
+      return 'Select database first'
+    }
+    // Show positive state when actions are available
+    return isFileBasedDB ? 'Available' : 'Running'
+  }
+
+  // Label for management section separator - shows state or required action
+  function getManageSectionLabel(): string {
+    if (!isFileBasedDB && isRunning) {
+      return 'Stop container first'
+    }
+    // Show positive state when actions are available
+    return isFileBasedDB ? 'Available' : 'Stopped'
   }
 
   // ─────────────────────────────────────────────────────────────────────────────
@@ -733,6 +757,12 @@ export async function showContainerSubmenu(
         value: 'stop',
       })
     }
+
+    // View logs - available anytime for server-based DBs
+    actionChoices.push({
+      name: `${chalk.gray('☰')} View logs`,
+      value: 'logs',
+    })
   }
 
   // Database selection - show current selection or prompt to select
@@ -748,18 +778,20 @@ export async function showContainerSubmenu(
     })
   }
 
-  actionChoices.push(new inquirer.Separator())
-
   // ─────────────────────────────────────────────────────────────────────────────
   // SECTION 2: Data Operations
+  // Separator shows current state or required action
   // ─────────────────────────────────────────────────────────────────────────────
+  const dataSectionLabel = getDataSectionLabel()
+  actionChoices.push(
+    new inquirer.Separator(chalk.gray(`── ${dataSectionLabel} ──`)),
+  )
 
   // Open shell - requires database selection for multi-db containers
-  const shellHint = getDbActionHint()
   actionChoices.push(
     canDoDbAction
       ? { name: `${chalk.blue('>')} Open shell`, value: 'shell' }
-      : disabledItem('>', 'Open shell', shellHint),
+      : disabledItem('>', 'Open shell'),
   )
 
   // Run SQL/script - requires database selection for multi-db containers
@@ -778,66 +810,64 @@ export async function showContainerSubmenu(
           : config.engine === Engine.SurrealDB
             ? 'Run SurrealQL file'
             : 'Run SQL file'
-    const runSqlHint = getDbActionHint()
     actionChoices.push(
       canDoDbAction
         ? { name: `${chalk.yellow('▷')} ${runScriptLabel}`, value: 'run-sql' }
-        : disabledItem('▷', runScriptLabel, runSqlHint),
+        : disabledItem('▷', runScriptLabel),
     )
   }
 
   // Copy connection string - requires database selection for multi-db containers
-  const copyHint = getDbActionHint()
   actionChoices.push(
     canDoDbAction
       ? { name: `${chalk.magenta('⊕')} Copy connection string`, value: 'copy' }
-      : disabledItem('⊕', 'Copy connection string', copyHint),
+      : disabledItem('⊕', 'Copy connection string'),
   )
 
   // Backup - requires database selection for multi-db containers
-  const backupHint = getDbActionHint()
   actionChoices.push(
     canDoDbAction
       ? { name: `${chalk.magenta('↓')} Backup database`, value: 'backup' }
-      : disabledItem('↓', 'Backup database', backupHint),
+      : disabledItem('↓', 'Backup database'),
   )
 
   // Restore - requires database selection for multi-db containers
-  const restoreHint = getDbActionHint()
   actionChoices.push(
     canDoDbAction
       ? { name: `${chalk.magenta('↑')} Restore from backup`, value: 'restore' }
-      : disabledItem('↑', 'Restore from backup', restoreHint),
+      : disabledItem('↑', 'Restore from backup'),
   )
 
-  // View logs - not available for file-based DBs (no log file)
-  if (!isFileBasedDB) {
-    actionChoices.push({
-      name: `${chalk.gray('☰')} View logs`,
-      value: 'logs',
-    })
-  }
-
-  actionChoices.push(new inquirer.Separator())
+  // Export - server-based DBs must be running, file-based must have the file
+  actionChoices.push(
+    containerReady
+      ? { name: `${chalk.cyan('⬆')} Export`, value: 'export' }
+      : disabledItem('⬆', 'Export'),
+  )
 
   // ─────────────────────────────────────────────────────────────────────────────
-  // SECTION 3: Container Management (requires stopped)
+  // SECTION 3: Container Management (requires stopped for server-based)
+  // Separator shows current state or required action
   // ─────────────────────────────────────────────────────────────────────────────
+  const manageSectionLabel = getManageSectionLabel()
+  actionChoices.push(
+    new inquirer.Separator(chalk.gray(`── ${manageSectionLabel} ──`)),
+  )
 
   // Edit container - file-based DBs can always edit (no running state), server databases must be stopped
-  const canEdit = isFileBasedDB ? true : !isRunning
+  const canEdit = isFileBasedDB || !isRunning
   actionChoices.push(
     canEdit
       ? { name: `${chalk.yellow('⚙')} Edit container`, value: 'edit' }
-      : disabledItem('⚙', 'Edit container', 'Stop container first'),
+      : disabledItem('⚙', 'Edit container'),
   )
 
   // Clone container - file-based DBs can always clone, server databases must be stopped
-  const canClone = isFileBasedDB ? true : !isRunning
+  const canClone = isFileBasedDB || !isRunning
   actionChoices.push(
     canClone
       ? { name: `${chalk.cyan('◇')} Clone container`, value: 'clone' }
-      : disabledItem('◇', 'Clone container', 'Stop container first'),
+      : disabledItem('◇', 'Clone container'),
   )
 
   // Detach - only for file-based DBs (unregisters without deleting file)
@@ -849,22 +879,11 @@ export async function showContainerSubmenu(
   }
 
   // Delete container - file-based DBs can always delete, server databases must be stopped
-  const canDelete = isFileBasedDB ? true : !isRunning
+  const canDelete = isFileBasedDB || !isRunning
   actionChoices.push(
     canDelete
       ? { name: `${chalk.red('✕')} Delete container`, value: 'delete' }
-      : disabledItem('✕', 'Delete container', 'Stop container first'),
-  )
-
-  // Export - server-based DBs must be running, file-based must have the file
-  const canExport = containerReady
-  const exportHint = isFileBasedDB
-    ? 'Database file missing'
-    : 'Start container first'
-  actionChoices.push(
-    canExport
-      ? { name: `${chalk.cyan('↑')} Export`, value: 'export' }
-      : disabledItem('⬆', 'Export', exportHint),
+      : disabledItem('✕', 'Delete container'),
   )
 
   actionChoices.push(new inquirer.Separator())

package/cli/commands/menu/index.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander'
 import chalk from 'chalk'
 import inquirer from 'inquirer'
 import { containerManager } from '../../../core/container-manager'
+import { updateManager, type UpdateCheckResult } from '../../../core/update-manager'
 import {
   promptInstallDependencies,
   enableGlobalEscape,
@@ -9,35 +10,48 @@ import {
   escapeablePrompt,
   EscapeError,
 } from '../../ui/prompts'
-import { header, uiError } from '../../ui/theme'
+import { header, uiError, uiSuccess, uiWarning } from '../../ui/theme'
 import { MissingToolError } from '../../../core/error-handler'
-import { hasAnyInstalledEngines } from '../../helpers'
 import {
   handleCreate,
   handleList,
-  handleStart,
-  handleStop,
+  showContainerSubmenu,
 } from './container-handlers'
-import { handleBackup, handleRestore, handleClone } from './backup-handlers'
-import { handleEngines } from './engine-handlers'
-import { handleCheckUpdate, handleDoctor } from './update-handlers'
 import { handleSettings } from './settings-handlers'
 import { configManager } from '../../../core/config-manager'
-import { type MenuChoice } from './shared'
+import { createSpinner } from '../../ui/spinner'
+import { type MenuChoice, pressEnterToContinue } from './shared'
 import { getPageSize } from '../../constants'
 
+// Track update check state for this session (only check once on first menu load)
+let updateCheckPromise: Promise<UpdateCheckResult | null> | null = null
+let cachedUpdateResult: UpdateCheckResult | null = null
+
 async function showMainMenu(): Promise<void> {
   console.clear()
   console.log(header('SpinDB - Local Database Manager'))
   console.log()
 
-  // Parallelize container list, engine checks, and config loading for faster startup
-  const [containers, hasEngines, config] = await Promise.all([
+  // Parallelize container list and config loading for faster startup
+  const [containers, config] = await Promise.all([
     containerManager.list(),
-    hasAnyInstalledEngines(),
     configManager.getConfig(),
   ])
 
+  // Check for updates on first menu load only (if auto-check is enabled)
+  // The check runs in background and updates cachedUpdateResult when complete
+  const autoCheckEnabled = config.update?.autoCheckEnabled !== false
+  if (autoCheckEnabled && !updateCheckPromise) {
+    // Start update check in background - it will populate cachedUpdateResult when done
+    updateCheckPromise = updateManager
+      .checkForUpdate()
+      .then((result) => {
+        cachedUpdateResult = result
+        return result
+      })
+      .catch(() => null)
+  }
+
   // Check if icon mode preference is set
   const iconModeSet = config.preferences?.iconMode !== undefined
 
@@ -51,12 +65,7 @@ async function showMainMenu(): Promise<void> {
   )
   console.log()
 
-  const canStart = stopped > 0
-  const canStop = running > 0
-  const canRestore = running > 0
-  const canClone = containers.length > 0
-
-  // If containers exist, show List first; otherwise show Create first
+  // If containers exist, show Containers first; otherwise show Create first
   const hasContainers = containers.length > 0
 
   const choices: MenuChoice[] = [
@@ -69,53 +78,18 @@ async function showMainMenu(): Promise<void> {
           { name: `${chalk.green('+')} Create container`, value: 'create' },
           { name: `${chalk.cyan('◉')} Containers`, value: 'list' },
         ]),
-    {
-      name: canStart
-        ? `${chalk.green('▶')} Start container`
-        : chalk.gray('▶ Start container'),
-      value: 'start',
-      disabled: canStart ? false : 'No stopped containers',
-    },
-    {
-      name: canStop
-        ? `${chalk.red('■')} Stop container`
-        : chalk.gray('■ Stop container'),
-      value: 'stop',
-      disabled: canStop ? false : 'No running containers',
-    },
-    {
-      name: canRestore
-        ? `${chalk.magenta('↓')} Backup database`
-        : chalk.gray('↓ Backup database'),
-      value: 'backup',
-      disabled: canRestore ? false : 'No running containers',
-    },
-    {
-      name: canRestore
-        ? `${chalk.magenta('↑')} Restore backup`
-        : chalk.gray('↑ Restore backup'),
-      value: 'restore',
-      disabled: canRestore ? false : 'No running containers',
-    },
-    {
-      name: canClone
-        ? `${chalk.cyan('◇')} Clone container`
-        : chalk.gray('◇ Clone container'),
-      value: 'clone',
-      disabled: canClone ? false : 'No containers',
-    },
     new inquirer.Separator(),
-    {
-      name: hasEngines
-        ? `${chalk.magenta('⬢')} Manage engines`
-        : chalk.gray('⬢ Manage engines'),
-      value: 'engines',
-      disabled: hasEngines ? false : 'No engines installed',
-    },
-    { name: `${chalk.red.bold('+')} Health check`, value: 'doctor' },
-    { name: `${chalk.cyan('↑')} Check for updates`, value: 'check-update' },
     { name: `${chalk.yellow('⚙')} Settings`, value: 'settings' },
-    { name: `${chalk.gray('⏻')} Exit`, value: 'exit' },
+    // Show update option if a new version is available (only when auto-check enabled)
+    ...(cachedUpdateResult?.updateAvailable
+      ? [
+          {
+            name: `${chalk.green('↑')} Update to v${cachedUpdateResult.latestVersion}`,
+            value: 'update',
+          },
+        ]
+      : []),
+    { name: `${chalk.gray('⎋')} Exit`, value: 'exit' },
     new inquirer.Separator(),
   ]
 
@@ -150,45 +124,75 @@ async function showMainMenu(): Promise<void> {
   }
 
   switch (action) {
-    case 'create':
-      await handleCreate()
+    case 'create': {
+      const result = await handleCreate()
+      // If a container name is returned, navigate to its submenu
+      if (result && result !== 'main') {
+        await showContainerSubmenu(result, showMainMenu)
+      }
       break
+    }
     case 'list':
       await handleList(showMainMenu)
       break
-    case 'start':
-      await handleStart()
-      break
-    case 'stop':
-      await handleStop()
-      break
-    case 'restore':
-      await handleRestore()
-      break
-    case 'backup':
-      await handleBackup()
-      break
-    case 'clone':
-      await handleClone()
-      break
-    case 'engines':
-      await handleEngines()
-      break
-    case 'doctor':
-      await handleDoctor()
-      break
-    case 'check-update':
-      await handleCheckUpdate()
-      break
     case 'settings':
       await handleSettings()
       break
+    case 'update':
+      await handleUpdate()
+      break
     case 'exit':
       console.log(chalk.gray('\n  Goodbye!\n'))
       process.exit(0)
   }
+}
+
+async function handleUpdate(): Promise<void> {
+  console.clear()
+  console.log(header('Update SpinDB'))
+  console.log()
+
+  if (!cachedUpdateResult) {
+    console.log(uiError('No update information available'))
+    await pressEnterToContinue()
+    return
+  }
+
+  console.log(chalk.gray(`  Current version: ${cachedUpdateResult.currentVersion}`))
+  console.log(
+    chalk.gray(`  Latest version:  ${chalk.green(cachedUpdateResult.latestVersion)}`),
+  )
+  console.log()
+
+  const spinner = createSpinner('Updating spindb...')
+  spinner.start()
+
+  const result = await updateManager.performUpdate()
+
+  if (result.success) {
+    spinner.succeed('Update complete')
+    console.log()
+    console.log(
+      uiSuccess(`Updated from ${result.previousVersion} to ${result.newVersion}`),
+    )
+    console.log()
+    if (result.previousVersion !== result.newVersion) {
+      console.log(uiWarning('Please restart spindb to use the new version.'))
+      console.log()
+    }
+    // Clear cached result so the update option disappears
+    cachedUpdateResult = null
+    updateCheckPromise = null
+  } else {
+    spinner.fail('Update failed')
+    console.log()
+    console.log(uiError(result.error || 'Unknown error'))
+    console.log()
+    const pm = await updateManager.detectPackageManager()
+    console.log(chalk.gray(`  Manual update: ${updateManager.getInstallCommand(pm)}`))
+  }
 
-  await showMainMenu()
+  await pressEnterToContinue()
 }
 
 export const menuCommand = new Command('menu')

package/cli/commands/menu/settings-handlers.ts

@@ -4,9 +4,12 @@ import { configManager } from '../../../core/config-manager'
 import { updateManager } from '../../../core/update-manager'
 import { escapeablePrompt } from '../../ui/prompts'
 import { header, uiSuccess, uiInfo } from '../../ui/theme'
-import { setCachedIconMode, ENGINE_BRAND_COLORS } from '../../constants'
+import { setCachedIconMode, ENGINE_BRAND_COLORS, getPageSize } from '../../constants'
+import { hasAnyInstalledEngines } from '../../helpers'
 import { Engine, type IconMode } from '../../../types'
 import { type MenuChoice, pressEnterToContinue } from './shared'
+import { handleEngines } from './engine-handlers'
+import { handleCheckUpdate, handleDoctor } from './update-handlers'
 
 // Sample engines for icon preview
 const PREVIEW_ENGINES = [
@@ -178,6 +181,7 @@ async function handleIconModeSettings(): Promise<void> {
       name: 'iconMode',
       message: 'Select icon mode:',
       choices,
+      pageSize: getPageSize(),
     },
   ])
 
@@ -244,6 +248,7 @@ async function handleUpdateCheckSettings(): Promise<void> {
       name: 'action',
       message: 'Update check setting:',
       choices,
+      pageSize: getPageSize(),
     },
   ])
 
@@ -273,9 +278,12 @@ async function handleUpdateCheckSettings(): Promise<void> {
  */
 export async function handleSettings(): Promise<void> {
   while (true) {
-    const config = await configManager.getConfig()
+    const [config, hasEngines, cached] = await Promise.all([
+      configManager.getConfig(),
+      hasAnyInstalledEngines(),
+      updateManager.getCachedUpdateInfo(),
+    ])
     const currentIconMode = config.preferences?.iconMode || 'ascii'
-    const cached = await updateManager.getCachedUpdateInfo()
     const updateCheckEnabled = cached.autoCheckEnabled !== false
 
     console.clear()
@@ -283,6 +291,16 @@ export async function handleSettings(): Promise<void> {
     console.log()
 
     const choices: MenuChoice[] = [
+      {
+        name: hasEngines
+          ? `${chalk.magenta('⬢')} Manage engines`
+          : chalk.gray('⬢ Manage engines'),
+        value: 'engines',
+        disabled: hasEngines ? false : 'No engines installed',
+      },
+      { name: `${chalk.red.bold('+')} Health check`, value: 'doctor' },
+      { name: `${chalk.cyan('↑')} Check for updates`, value: 'check-update' },
+      new inquirer.Separator(),
       {
         name: `Icon mode: ${chalk.cyan(currentIconMode)}`,
         value: 'icon-mode',
@@ -293,7 +311,7 @@ export async function handleSettings(): Promise<void> {
       },
       new inquirer.Separator(),
       {
-        name: `${chalk.blue('\u2190')} Back`,
+        name: `${chalk.blue('←')} Back`,
         value: 'back',
       },
     ]
@@ -304,10 +322,20 @@ export async function handleSettings(): Promise<void> {
         name: 'action',
         message: 'What would you like to configure?',
         choices,
+        pageSize: getPageSize(),
       },
     ])
 
     switch (action) {
+      case 'engines':
+        await handleEngines()
+        break
+      case 'doctor':
+        await handleDoctor()
+        break
+      case 'check-update':
+        await handleCheckUpdate()
+        break
       case 'icon-mode':
         await handleIconModeSettings()
         break

package/cli/commands/restore.ts

@@ -380,7 +380,7 @@ export const restoreCommand = new Command('restore')
             }
           }
 
-          // Drop existing database
+          // Drop existing database (tracking entry stays - we're recreating same name)
           const dropSpinner = createSpinner(
             `Dropping existing database "${databaseName}"...`,
           )
@@ -388,7 +388,8 @@ export const restoreCommand = new Command('restore')
 
           try {
             await engine.dropDatabase(config, databaseName)
-            await containerManager.removeDatabase(containerName, databaseName)
+            // Don't remove from tracking - the database name stays the same
+            // and addDatabase() is idempotent, so tracking remains valid
             dropSpinner.succeed(`Dropped database "${databaseName}"`)
           } catch (dropErr) {
             dropSpinner.fail('Failed to drop database')

package/core/docker-exporter.ts

@@ -159,9 +159,9 @@ function generateDockerfile(
   // Server-based engines check for running status
   const healthcheck = isFileBased
     ? `HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \\
-    CMD gosu spindb spindb list --json | grep -q '"engine":"${engine}"'`
+    CMD gosu spindb spindb list --json | grep -q '"engine":.*"${engine}"'`
     : `HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \\
-    CMD gosu spindb spindb list --json | grep -q '"status":"running"'`
+    CMD gosu spindb spindb list --json | grep -q '"status":.*"running"'`
 
   // Only copy TLS certificates if they were generated
   const copyCerts = useTLS
@@ -248,6 +248,37 @@ function generateEntrypoint(
 ): string {
   const isFileBased = isFileBasedEngine(engine)
 
+  // Engine-specific network configuration (run after create, before start)
+  // This configures databases to accept connections from Docker network
+  let networkConfig = ''
+
+  switch (engine) {
+    case Engine.PostgreSQL:
+    case Engine.CockroachDB:
+      // PostgreSQL/CockroachDB need to listen on all interfaces and allow network connections
+      networkConfig = `
+# Configure PostgreSQL to accept connections from Docker network
+echo "Configuring network access..."
+PG_CONF="/home/spindb/.spindb/containers/${engine}/\${CONTAINER_NAME}/data/postgresql.conf"
+PG_HBA="/home/spindb/.spindb/containers/${engine}/\${CONTAINER_NAME}/data/pg_hba.conf"
+
+# Set listen_addresses to allow connections from any interface
+if [ -f "$PG_CONF" ]; then
+    sed -i "s/^#*listen_addresses.*/listen_addresses = '*'/" "$PG_CONF"
+fi
+
+# Add rule to allow password-authenticated connections from any IP
+if [ -f "$PG_HBA" ] && ! grep -q "0.0.0.0/0" "$PG_HBA"; then
+    echo "host    all             all             0.0.0.0/0               scram-sha-256" >> "$PG_HBA"
+fi
+`
+      break
+
+    default:
+      // Other engines don't need special network config (they listen on all interfaces by default)
+      break
+  }
+
   // Engine-specific user creation commands
   let userCreationCommands = ''
 
@@ -256,7 +287,7 @@ function generateEntrypoint(
       userCreationCommands = `
 # Create user with password
 echo "Creating database user..."
-run_as_spindb spindb run "$CONTAINER_NAME" --database postgres <<EOF
+cat > /tmp/create-user.sql <<EOSQL
 DO \\$\\$
 BEGIN
   IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '$SPINDB_USER') THEN
@@ -267,7 +298,9 @@ BEGIN
 END
 \\$\\$;
 GRANT ALL PRIVILEGES ON DATABASE "$DATABASE" TO "$SPINDB_USER";
-EOF
+EOSQL
+run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.sql --database postgres
+rm -f /tmp/create-user.sql
 `
       break
 
@@ -276,11 +309,13 @@ EOF
       userCreationCommands = `
 # Create user with password
 echo "Creating database user..."
-run_as_spindb spindb run "$CONTAINER_NAME" --database mysql <<EOF
+cat > /tmp/create-user.sql <<EOSQL
 CREATE USER IF NOT EXISTS '$SPINDB_USER'@'%' IDENTIFIED BY '$SPINDB_PASSWORD';
 GRANT ALL PRIVILEGES ON \\\`$DATABASE\\\`.* TO '$SPINDB_USER'@'%';
 FLUSH PRIVILEGES;
-EOF
+EOSQL
+run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.sql --database mysql
+rm -f /tmp/create-user.sql
 `
       break
 
@@ -289,13 +324,15 @@ EOF
       userCreationCommands = `
 # Create user with password
 echo "Creating database user..."
-run_as_spindb spindb run "$CONTAINER_NAME" --database admin <<EOF
+cat > /tmp/create-user.js <<EOJS
 db.createUser({
   user: "$SPINDB_USER",
   pwd: "$SPINDB_PASSWORD",
   roles: [{ role: "readWrite", db: "$DATABASE" }]
 });
-EOF
+EOJS
+run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.js --database admin
+rm -f /tmp/create-user.js
 `
       break
 
@@ -312,10 +349,12 @@ echo "Authentication configured via server settings"
       userCreationCommands = `
 # Create user with password
 echo "Creating database user..."
-run_as_spindb spindb run "$CONTAINER_NAME" <<EOF
+cat > /tmp/create-user.sql <<EOSQL
 CREATE USER IF NOT EXISTS $SPINDB_USER IDENTIFIED BY '$SPINDB_PASSWORD';
 GRANT ALL ON $DATABASE.* TO $SPINDB_USER;
-EOF
+EOSQL
+run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.sql
+rm -f /tmp/create-user.sql
 `
       break
 
@@ -330,10 +369,12 @@ echo "Admin credentials configured via server settings"
       userCreationCommands = `
 # Create user with password
 echo "Creating database user..."
-run_as_spindb spindb run "$CONTAINER_NAME" --database defaultdb <<EOF
+cat > /tmp/create-user.sql <<EOSQL
 CREATE USER IF NOT EXISTS $SPINDB_USER WITH PASSWORD '$SPINDB_PASSWORD';
 GRANT ALL ON DATABASE $DATABASE TO $SPINDB_USER;
-EOF
+EOSQL
+run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.sql --database defaultdb
+rm -f /tmp/create-user.sql
 `
       break
 
@@ -411,6 +452,40 @@ if ls ${initDir}/* 1> /dev/null 2>&1; then
 fi
 `
 
+  // Post-restore commands - grant table/sequence permissions to the spindb user
+  // Tables created during restore are owned by postgres, so spindb user needs grants
+  let postRestoreCommands = ''
+
+  switch (engine) {
+    case Engine.PostgreSQL:
+    case Engine.CockroachDB:
+      postRestoreCommands = `
+# Grant table and sequence permissions to spindb user
+# (Tables from restore are owned by postgres, spindb user needs access)
+echo "Granting table permissions..."
+cat > /tmp/grant-permissions.sql <<EOSQL
+GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO "$SPINDB_USER";
+GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO "$SPINDB_USER";
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO "$SPINDB_USER";
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO "$SPINDB_USER";
+EOSQL
+run_as_spindb spindb run "$CONTAINER_NAME" /tmp/grant-permissions.sql --database "$DATABASE" || echo "Permission grants completed with warnings"
+rm -f /tmp/grant-permissions.sql
+`
+      break
+
+    case Engine.MySQL:
+    case Engine.MariaDB:
+      // MySQL grants are already handled by GRANT ALL ON database.* in user creation
+      postRestoreCommands = ''
+      break
+
+    default:
+      // Other engines don't need post-restore permission grants
+      postRestoreCommands = ''
+      break
+  }
+
   return `#!/bin/bash
 set -e
 
@@ -442,6 +517,9 @@ FILE_DB_PATH="/home/spindb/.spindb/containers/${engine}/\${CONTAINER_NAME}/\${CO
 # Export environment variables for the spindb user
 export SPINDB_CONTAINER SPINDB_DATABASE SPINDB_ENGINE SPINDB_VERSION SPINDB_PORT SPINDB_USER SPINDB_PASSWORD
 
+# Add ~/.local/bin to PATH for symlinked database binaries
+export PATH="/home/spindb/.local/bin:$PATH"
+
 # Fix permissions on mounted volume (may have been created with root ownership)
 echo "Setting up directories..."
 chown -R spindb:spindb /home/spindb/.spindb 2>/dev/null || true
@@ -472,12 +550,27 @@ else
         : `run_as_spindb spindb create "$CONTAINER_NAME" --engine "$ENGINE" --db-version "$VERSION" --port "$PORT" --database "$DATABASE" --force`
     }
 fi
-${
-  isFileBased
-    ? `
+
+# Create symlinks for database binaries in ~/.local/bin
+# This allows users to run psql, mysql, etc. directly in the container
+echo "Creating binary symlinks..."
+mkdir -p /home/spindb/.local/bin
+BIN_DIR=$(ls -d /home/spindb/.spindb/bin/\${ENGINE}-*/bin 2>/dev/null | head -1)
+if [ -d "$BIN_DIR" ]; then
+    for binary in "$BIN_DIR"/*; do
+        if [ -x "$binary" ] && [ -f "$binary" ]; then
+            name=$(basename "$binary")
+            ln -sf "$binary" "/home/spindb/.local/bin/$name"
+        fi
+    done
+    echo "Binaries available: $(ls /home/spindb/.local/bin | tr '\\n' ' ')"
+fi
+${networkConfig}${
+    isFileBased
+      ? `
 # File-based database: no server to start, just verify file exists after restore
 `
-    : `
+      : `
 # Start the database
 echo "Starting database..."
 run_as_spindb spindb start "$CONTAINER_NAME"
@@ -485,7 +578,7 @@ run_as_spindb spindb start "$CONTAINER_NAME"
 # Wait for database to be ready
 echo "Waiting for database to be ready..."
 RETRIES=30
-until run_as_spindb spindb list --json 2>/dev/null | grep -q '"status":"running"' || [ $RETRIES -eq 0 ]; do
+until run_as_spindb spindb list --json 2>/dev/null | grep -q '"status":.*"running"' || [ $RETRIES -eq 0 ]; do
     echo "Waiting for database... ($RETRIES attempts remaining)"
     sleep 2
     RETRIES=$((RETRIES-1))
@@ -495,11 +588,12 @@ if [ $RETRIES -eq 0 ]; then
     echo "Error: Database failed to start"
     exit 1
 fi`
-}
+  }
 
 echo "Database is running!"
 ${userCreationCommands}
 ${restoreSection}
+${postRestoreCommands}
 echo "========================================"
 echo "SpinDB container ready!"
 echo ""
@@ -520,7 +614,7 @@ exec gosu spindb tail -f /dev/null &
 while true; do
     sleep 60
     # Check if database is still running
-    if ! run_as_spindb spindb list --json 2>/dev/null | grep -q '"status":"running"'; then
+    if ! run_as_spindb spindb list --json 2>/dev/null | grep -q '"status":.*"running"'; then
         echo "Database stopped unexpectedly, restarting..."
         run_as_spindb spindb start "$CONTAINER_NAME" || true
     fi
@@ -543,9 +637,10 @@ function generateDockerCompose(
   // Engine-aware healthcheck matching Dockerfile behavior
   // Server-based: check for running status
   // File-based: check that container exists (no server process to check)
+  // Note: Double quotes must be escaped for YAML string context
   const healthcheckCommand = isFileBased
-    ? `gosu spindb spindb list --json | grep -q '"engine":"${engine}"'`
-    : `gosu spindb spindb list --json | grep -q '"status":"running"'`
+    ? `gosu spindb spindb list --json | grep -q '\\"engine\\":.*\\"${engine}\\"'`
+    : `gosu spindb spindb list --json | grep -q '\\"status\\":.*\\"running\\"'`
 
   const startPeriod = isFileBased ? '30s' : '60s'
 
@@ -626,6 +721,29 @@ function generateReadme(
     useTLS,
   )
 
+  // TLS-conditional content
+  const tlsSecurityNote = useTLS
+    ? '- TLS certificates in `certs/` are self-signed. For production, replace with valid certificates.'
+    : '- TLS is disabled for this export. Consider enabling TLS for production use.'
+  const certsFileEntry = useTLS ? '| `certs/` | TLS certificates |\n' : ''
+  const tlsCustomization = useTLS
+    ? `
+### Use Custom Certificates
+
+Replace the files in \`certs/\`:
+- \`server.crt\` - TLS certificate
+- \`server.key\` - TLS private key
+
+### Disable TLS
+
+Edit \`entrypoint.sh\` and remove TLS-related flags (not recommended for production).
+`
+    : `
+### Enable TLS
+
+To enable TLS, re-export the container without the \`--skip-tls\` flag (requires OpenSSL).
+`
+
   return `# ${containerName} - SpinDB Docker Export
 
 This directory contains a Docker-ready package for running your SpinDB ${displayName} container.
@@ -664,7 +782,7 @@ Replace \`\${SPINDB_USER}\` and \`\${SPINDB_PASSWORD}\` with the values from \`.
 ## Security Notes
 
 - The \`.env\` file contains auto-generated credentials. **Change these in production.**
-- TLS certificates in \`certs/\` are self-signed. For production, replace with valid certificates.
+${tlsSecurityNote}
 - The default \`spindb\` user has full access to the database. Create restricted users for applications.
 
 ## Files
@@ -675,8 +793,7 @@ Replace \`\${SPINDB_USER}\` and \`\${SPINDB_PASSWORD}\` with the values from \`.
 | \`docker-compose.yml\` | Container orchestration |
 | \`.env\` | Environment variables and credentials |
 | \`entrypoint.sh\` | Container startup script |
-| \`certs/\` | TLS certificates |
-| \`data/\` | Database backup for initialization |
+${certsFileEntry}| \`data/\` | Database backup for initialization |
 
 ## Customization
 
@@ -686,17 +803,7 @@ Edit \`.env\`:
 \`\`\`
 PORT=5433
 \`\`\`
-
-### Use Custom Certificates
-
-Replace the files in \`certs/\`:
-- \`server.crt\` - TLS certificate
-- \`server.key\` - TLS private key
-
-### Disable TLS
-
-Edit \`entrypoint.sh\` and remove TLS-related flags (not recommended for production).
-
+${tlsCustomization}
 ---
 
 Generated by [SpinDB](https://github.com/robertjbass/spindb)
@@ -731,15 +838,16 @@ export async function exportToDocker(
     const outputDirExisted = existsSync(outputDir)
 
     if (outputDirExisted) {
-      // If it exists, check if it's empty
+      // If it exists, check if it's empty or only contains 'data' (from backup step)
       const existingFiles = await readdir(outputDir)
-      if (existingFiles.length > 0) {
+      const nonDataFiles = existingFiles.filter((f) => f !== 'data')
+      if (nonDataFiles.length > 0) {
         throw new Error(
           `Output directory "${outputDir}" already exists and is not empty. ` +
             `Please use an empty directory or remove the existing files.`,
         )
       }
-      // Directory exists but is empty - don't register rollback for it
+      // Directory exists but is empty or only has data/ - don't register rollback for it
     } else {
       // Directory doesn't exist - create it and register rollback
       await mkdir(outputDir, { recursive: true })

package/core/update-manager.ts

@@ -80,6 +80,7 @@ export class UpdateManager {
     try {
       const { stdout } = await execAsync('pnpm list -g spindb --json', {
         timeout: 5000,
+        cwd: '/',
       })
       const data = JSON.parse(stdout) as Array<{
         dependencies?: { spindb?: unknown }
@@ -94,6 +95,7 @@ export class UpdateManager {
     try {
       const { stdout } = await execAsync('yarn global list --json', {
         timeout: 5000,
+        cwd: '/',
       })
       // yarn outputs newline-delimited JSON, look for spindb in any line
       if (stdout.includes('"spindb@')) {
@@ -106,6 +108,7 @@ export class UpdateManager {
     try {
       const { stdout } = await execAsync('bun pm ls -g', {
         timeout: 5000,
+        cwd: '/',
       })
       if (stdout.includes('spindb@')) {
         return 'bun'
@@ -181,7 +184,7 @@ export class UpdateManager {
 
     // Run install command
     try {
-      await execAsync(installCmd, { timeout: 60000 })
+      await execAsync(installCmd, { timeout: 60000, cwd: '/' })
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
 

package/engines/qdrant/index.ts

@@ -710,9 +710,10 @@ export class QdrantEngine extends BaseEngine {
     }
 
     // Wait for process to fully terminate
-    if (isWindows()) {
-      await new Promise((resolve) => setTimeout(resolve, 3000))
-    }
+    // Windows needs longer due to file handle release
+    // Linux/macOS need a brief wait after SIGKILL before checking ports
+    const terminationWait = isWindows() ? 3000 : 1000
+    await new Promise((resolve) => setTimeout(resolve, terminationWait))
 
     // Kill any processes still listening on the ports
     // This handles cases where the PID file is stale, child processes exist,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.30.1",
+  "version": "0.30.7",
   "author": "Bob Bass <bob@bbass.co>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",