spindb 0.30.6 → 0.31.0

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
@@ -1047,6 +1077,8 @@ See [CLAUDE.md](CLAUDE.md) for AI-assisted development context.
 
 See [ENGINE_CHECKLIST.md](ENGINE_CHECKLIST.md) for adding new database engines.
 
+See [USE_CASES.md](USE_CASES.md) for detailed use cases and infrastructure opportunities.
+
 ---
 
 ## Acknowledgments

package/cli/commands/export.ts

@@ -5,7 +5,14 @@ import { containerManager } from '../../core/container-manager'
 import { processManager } from '../../core/process-manager'
 import { getEngine } from '../../engines'
 import { platformService } from '../../core/platform-service'
-import { exportToDocker, getExportBackupPath } from '../../core/docker-exporter'
+import {
+  exportToDocker,
+  getExportBackupPath,
+  dockerExportExists,
+  getDockerConnectionString,
+  getDockerCredentials,
+  getDefaultDockerExportPath,
+} from '../../core/docker-exporter'
 import { promptContainerSelect, promptConfirm } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
 import { uiSuccess, uiError, uiWarning, box, formatBytes } from '../ui/theme'
@@ -360,3 +367,178 @@ export const exportCommand = new Command('export')
         },
       ),
   )
+  .addCommand(
+    new Command('docker-url')
+      .description('Get connection string for an existing Docker export')
+      .argument('[container]', 'Container name')
+      .option('-c, --copy', 'Copy connection string to clipboard')
+      .option('-j, --json', 'Output result as JSON')
+      .option(
+        '--host <hostname>',
+        'Override hostname in connection string',
+        'localhost',
+      )
+      .action(
+        async (
+          containerArg: string | undefined,
+          options: {
+            copy?: boolean
+            json?: boolean
+            host?: string
+          },
+        ) => {
+          try {
+            let containerName = containerArg
+
+            // Select container if not provided
+            if (!containerName) {
+              if (options.json) {
+                console.log(
+                  JSON.stringify({ error: 'Container name is required' }),
+                )
+                process.exit(1)
+              }
+
+              const containers = await containerManager.list()
+
+              if (containers.length === 0) {
+                console.log(
+                  uiWarning(
+                    'No containers found. Create one with: spindb create',
+                  ),
+                )
+                return
+              }
+
+              // Filter to containers with Docker exports
+              const containersWithExports = containers.filter((c) =>
+                dockerExportExists(c.name, c.engine),
+              )
+
+              if (containersWithExports.length === 0) {
+                console.log(
+                  uiWarning(
+                    'No Docker exports found. Export a container first with: spindb export docker <container>',
+                  ),
+                )
+                return
+              }
+
+              const selected = await promptContainerSelect(
+                containersWithExports,
+                'Select container:',
+              )
+              if (!selected) return
+              containerName = selected
+            }
+
+            // Get container config
+            const config = await containerManager.getConfig(containerName)
+            if (!config) {
+              if (options.json) {
+                console.log(
+                  JSON.stringify({
+                    error: `Container "${containerName}" not found`,
+                  }),
+                )
+              } else {
+                console.error(uiError(`Container "${containerName}" not found`))
+              }
+              process.exit(1)
+            }
+
+            // Check if Docker export exists
+            if (!dockerExportExists(containerName, config.engine)) {
+              const exportPath = getDefaultDockerExportPath(
+                containerName,
+                config.engine,
+              )
+              if (options.json) {
+                console.log(
+                  JSON.stringify({
+                    error: `No Docker export found for "${containerName}". Export first with: spindb export docker ${containerName}`,
+                    exportPath,
+                  }),
+                )
+              } else {
+                console.error(
+                  uiError(
+                    `No Docker export found for "${containerName}".\nExport first with: spindb export docker ${containerName}`,
+                  ),
+                )
+              }
+              process.exit(1)
+            }
+
+            // Get credentials and connection string
+            const credentials = await getDockerCredentials(
+              containerName,
+              config.engine,
+            )
+            const connectionString = await getDockerConnectionString(
+              containerName,
+              config.engine,
+              { host: options.host },
+            )
+
+            if (!connectionString || !credentials) {
+              if (options.json) {
+                console.log(
+                  JSON.stringify({
+                    error: 'Could not read Docker export credentials',
+                  }),
+                )
+              } else {
+                console.error(
+                  uiError('Could not read Docker export credentials'),
+                )
+              }
+              process.exit(1)
+            }
+
+            // Copy to clipboard if requested
+            if (options.copy) {
+              const copied =
+                await platformService.copyToClipboard(connectionString)
+              if (!options.json) {
+                if (copied) {
+                  console.log(
+                    uiSuccess('Connection string copied to clipboard'),
+                  )
+                } else {
+                  console.log(uiWarning('Could not copy to clipboard'))
+                }
+              }
+            }
+
+            // Output
+            if (options.json) {
+              console.log(
+                JSON.stringify({
+                  connectionString,
+                  username: credentials.username,
+                  password: credentials.password,
+                  host: options.host || 'localhost',
+                  port: credentials.port,
+                  database: credentials.database,
+                  engine: credentials.engine,
+                  version: credentials.version,
+                }),
+              )
+            } else if (!options.copy) {
+              // Only print connection string if not copying (to allow piping)
+              console.log(connectionString)
+            }
+          } catch (error) {
+            const e = error as Error
+
+            if (options.json) {
+              console.log(JSON.stringify({ error: e.message }))
+            } else {
+              console.error(uiError(e.message))
+            }
+            process.exit(1)
+          }
+        },
+      ),
+  )

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

@@ -60,6 +60,8 @@ import {
 import {
   exportToDocker,
   getExportBackupPath,
+  dockerExportExists,
+  getDockerConnectionString,
 } from '../../../core/docker-exporter'
 import { getDefaultFormat } from '../../../config/backup-formats'
 import { Engine, isFileBasedEngine } from '../../../types'
@@ -573,7 +575,11 @@ export async function handleList(
   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 ──'))]
+      ? [
+          new inquirer.Separator(
+            chalk.cyan('── [Shift+Tab] toggle start/stop ──'),
+          ),
+        ]
       : []),
     ...containerChoices,
     new inquirer.Separator(),
@@ -820,8 +826,8 @@ export async function showContainerSubmenu(
   // Copy connection string - requires database selection for multi-db containers
   actionChoices.push(
     canDoDbAction
-      ? { name: `${chalk.magenta('⊕')} Copy connection string`, value: 'copy' }
-      : disabledItem('⊕', 'Copy connection string'),
+      ? { name: `${chalk.green('⎘')} Copy connection string`, value: 'copy' }
+      : disabledItem('⎘', 'Copy connection string'),
   )
 
   // Backup - requires database selection for multi-db containers
@@ -1746,30 +1752,85 @@ async function handleDelete(containerName: string): Promise<void> {
   deleteSpinner.succeed(`Container "${containerName}" deleted`)
 }
 
+async function isDockerContainerRunning(
+  containerName: string,
+): Promise<boolean> {
+  try {
+    const { execSync } = await import('child_process')
+    const result = execSync(
+      `docker ps --filter "name=spindb-${containerName}" --format "{{.Names}}"`,
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+    )
+    return result.trim().includes(`spindb-${containerName}`)
+  } catch {
+    return false
+  }
+}
+
 async function handleExportSubmenu(
   containerName: string,
   databases: string[],
   showMainMenu: () => Promise<void>,
 ): Promise<void> {
+  const config = await containerManager.getConfig(containerName)
+  if (!config) {
+    console.log(uiError(`Container "${containerName}" not found`))
+    await pressEnterToContinue()
+    return
+  }
+
+  // Check if Docker export already exists
+  const hasDockerExport = dockerExportExists(containerName, config.engine)
+
+  // Check if Docker container is running (only if export exists)
+  let dockerRunning = false
+  if (hasDockerExport) {
+    dockerRunning = await isDockerContainerRunning(containerName)
+  }
+
   console.log()
   console.log(header('Export'))
   console.log()
 
+  // Build choices based on whether export exists
+  const choices: MenuChoice[] = []
+
+  if (hasDockerExport) {
+    // Export exists: show option to get connection string with running status
+    const runningStatus = dockerRunning
+      ? chalk.green('running')
+      : chalk.gray('not running')
+    choices.push({
+      name: `${chalk.green('⎘')} Get Docker connection string ${chalk.gray(`(${runningStatus})`)}`,
+      value: 'docker-url',
+    })
+    choices.push({
+      name: `${chalk.cyan('▣')} Docker ${chalk.gray('(Re-export - invalidates original credentials)')}`,
+      value: 'docker',
+    })
+  } else {
+    // No export: just show Docker option
+    choices.push({ name: `${chalk.cyan('▣')} Docker`, value: 'docker' })
+  }
+
+  choices.push(new inquirer.Separator())
+  choices.push({ name: `${chalk.blue('←')} Back`, value: 'back' })
+  choices.push({ name: `${chalk.blue('⌂')} Back to main menu`, value: 'home' })
+
   const { action } = await escapeablePrompt<{ action: string }>([
     {
       type: 'list',
       name: 'action',
       message: 'Export format:',
-      choices: [
-        { name: `${chalk.cyan('▣')} Docker`, value: 'docker' },
-        new inquirer.Separator(),
-        { name: `${chalk.blue('←')} Back`, value: 'back' },
-        { name: `${chalk.blue('⌂')} Back to main menu`, value: 'home' },
-      ],
+      choices,
     },
   ])
 
   switch (action) {
+    case 'docker-url':
+      await handleGetDockerConnectionString(containerName, config.engine)
+      await handleExportSubmenu(containerName, databases, showMainMenu)
+      return
     case 'docker':
       await handleExportDocker(containerName, databases, showMainMenu)
       return
@@ -1782,6 +1843,39 @@ async function handleExportSubmenu(
   }
 }
 
+async function handleGetDockerConnectionString(
+  containerName: string,
+  engine: Engine,
+): Promise<void> {
+  const connectionString = await getDockerConnectionString(
+    containerName,
+    engine,
+  )
+
+  if (!connectionString) {
+    console.log()
+    console.log(uiError('Could not read Docker export credentials'))
+    await pressEnterToContinue()
+    return
+  }
+
+  // Copy to clipboard
+  const copied = await platformService.copyToClipboard(connectionString)
+
+  console.log()
+  if (copied) {
+    console.log(uiSuccess('Connection string copied to clipboard'))
+  } else {
+    console.log(uiWarning('Could not copy to clipboard'))
+  }
+  console.log()
+  console.log(chalk.gray('  Connection string:'))
+  console.log(chalk.cyan(`  ${connectionString}`))
+  console.log()
+
+  await pressEnterToContinue()
+}
+
 async function handleExportDocker(
   containerName: string,
   databases: string[],

package/cli/commands/menu/index.ts

@@ -2,7 +2,10 @@ 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 {
+  updateManager,
+  type UpdateCheckResult,
+} from '../../../core/update-manager'
 import {
   promptInstallDependencies,
   enableGlobalEscape,
@@ -158,9 +161,13 @@ async function handleUpdate(): Promise<void> {
     return
   }
 
-  console.log(chalk.gray(`  Current version: ${cachedUpdateResult.currentVersion}`))
   console.log(
-    chalk.gray(`  Latest version:  ${chalk.green(cachedUpdateResult.latestVersion)}`),
+    chalk.gray(`  Current version: ${cachedUpdateResult.currentVersion}`),
+  )
+  console.log(
+    chalk.gray(
+      `  Latest version:  ${chalk.green(cachedUpdateResult.latestVersion)}`,
+    ),
   )
   console.log()
 
@@ -173,7 +180,9 @@ async function handleUpdate(): Promise<void> {
     spinner.succeed('Update complete')
     console.log()
     console.log(
-      uiSuccess(`Updated from ${result.previousVersion} to ${result.newVersion}`),
+      uiSuccess(
+        `Updated from ${result.previousVersion} to ${result.newVersion}`,
+      ),
     )
     console.log()
     if (result.previousVersion !== result.newVersion) {
@@ -189,7 +198,9 @@ async function handleUpdate(): Promise<void> {
     console.log(uiError(result.error || 'Unknown error'))
     console.log()
     const pm = await updateManager.detectPackageManager()
-    console.log(chalk.gray(`  Manual update: ${updateManager.getInstallCommand(pm)}`))
+    console.log(
+      chalk.gray(`  Manual update: ${updateManager.getInstallCommand(pm)}`),
+    )
   }
 
   await pressEnterToContinue()

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

@@ -4,7 +4,11 @@ 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, getPageSize } 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'

package/core/docker-exporter.ts

@@ -8,9 +8,10 @@
  * using the same hostdb binaries as local development.
  */
 
-import { mkdir, writeFile, copyFile, rm, readdir } from 'fs/promises'
+import { mkdir, writeFile, copyFile, rm, readdir, readFile } from 'fs/promises'
 import { join, basename } from 'path'
 import { existsSync } from 'fs'
+import { homedir } from 'os'
 import {
   type ContainerConfig,
   Engine,
@@ -73,6 +74,71 @@ function getEngineDisplayName(engine: Engine): string {
   return displayNames[engine] || engine
 }
 
+/**
+ * Engine binary configuration for Docker exports
+ *
+ * Defines primary binaries per engine for PATH setup and documentation.
+ * This structure supports future enhancements:
+ * - excludedBinaries: binaries to omit from PATH (e.g., internal tools)
+ * - renamedBinaries: map of original -> renamed (e.g., for collision avoidance)
+ * - priority: for multi-engine containers, which engine's binary wins
+ */
+const _ENGINE_BINARY_CONFIG: Record<
+  Engine,
+  {
+    primaryBinaries: string[]
+  }
+> = {
+  [Engine.PostgreSQL]: {
+    primaryBinaries: ['psql', 'pg_dump', 'pg_restore', 'createdb', 'dropdb'],
+  },
+  [Engine.MySQL]: {
+    primaryBinaries: ['mysql', 'mysqldump', 'mysqladmin'],
+  },
+  [Engine.MariaDB]: {
+    primaryBinaries: ['mariadb', 'mariadb-dump', 'mariadb-admin'],
+  },
+  [Engine.SQLite]: {
+    primaryBinaries: ['sqlite3'],
+  },
+  [Engine.DuckDB]: {
+    primaryBinaries: ['duckdb'],
+  },
+  [Engine.MongoDB]: {
+    primaryBinaries: ['mongosh', 'mongodump', 'mongorestore'],
+  },
+  [Engine.FerretDB]: {
+    primaryBinaries: ['mongosh', 'psql'], // FerretDB uses mongosh + PostgreSQL backend
+  },
+  [Engine.Redis]: {
+    primaryBinaries: ['redis-cli', 'redis-server'],
+  },
+  [Engine.Valkey]: {
+    primaryBinaries: ['valkey-cli', 'valkey-server'],
+  },
+  [Engine.ClickHouse]: {
+    primaryBinaries: ['clickhouse', 'clickhouse-client'],
+  },
+  [Engine.Qdrant]: {
+    primaryBinaries: [], // REST API only, no CLI tools
+  },
+  [Engine.Meilisearch]: {
+    primaryBinaries: [], // REST API only, no CLI tools
+  },
+  [Engine.CouchDB]: {
+    primaryBinaries: [], // REST API only, no CLI tools
+  },
+  [Engine.CockroachDB]: {
+    primaryBinaries: ['cockroach'],
+  },
+  [Engine.SurrealDB]: {
+    primaryBinaries: ['surreal'],
+  },
+  [Engine.QuestDB]: {
+    primaryBinaries: [], // Uses psql from PostgreSQL for connections
+  },
+}
+
 /**
  * Get the connection string template for an engine
  * Includes placeholders for credentials and optionally TLS
@@ -181,6 +247,12 @@ ENV DEBIAN_FRONTEND=noninteractive
 
 # Install base dependencies
 # libnuma1: Required by PostgreSQL binaries
+# libxml2: XML library required by PostgreSQL
+# libicu70: ICU library required by PostgreSQL (Ubuntu 22.04 ships ICU 70)
+# libaio1: Async I/O library required by MySQL
+# libncurses6: Terminal library required by MariaDB
+# locales: Needed for PostgreSQL locale configuration
+# lsof: Needed by SpinDB's findProcessByPort()
 # gosu: For running commands as non-root user
 RUN apt-get update && apt-get install -y \\
     curl \\
@@ -188,9 +260,20 @@ RUN apt-get update && apt-get install -y \\
     ca-certificates \\
     gnupg \\
     libnuma1 \\
+    libxml2 \\
+    libicu70 \\
+    libaio1 \\
+    libncurses6 \\
+    locales \\
+    lsof \\
     gosu \\
+    && locale-gen en_US.UTF-8 \\
     && rm -rf /var/lib/apt/lists/*
 
+# Set locale environment variables
+ENV LANG=en_US.UTF-8
+ENV LC_ALL=en_US.UTF-8
+
 # Install Node.js 22 LTS (matches SpinDB's engine requirements)
 RUN mkdir -p /etc/apt/keyrings \\
     && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \\
@@ -286,7 +369,7 @@ fi
     case Engine.PostgreSQL:
       userCreationCommands = `
 # Create user with password
-echo "Creating database user..."
+echo "[$(date '+%H:%M:%S')] Creating database user '$SPINDB_USER'..."
 cat > /tmp/create-user.sql <<EOSQL
 DO \\$\\$
 BEGIN
@@ -299,8 +382,13 @@ END
 \\$\\$;
 GRANT ALL PRIVILEGES ON DATABASE "$DATABASE" TO "$SPINDB_USER";
 EOSQL
-run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.sql --database postgres
+if ! run_as_spindb spindb run "$CONTAINER_NAME" /tmp/create-user.sql --database postgres; then
+    echo "[$(date '+%H:%M:%S')] ERROR: Failed to create database user"
+    rm -f /tmp/create-user.sql
+    exit 1
+fi
 rm -f /tmp/create-user.sql
+echo "[$(date '+%H:%M:%S')] User '$SPINDB_USER' created successfully"
 `
       break
 
@@ -431,27 +519,83 @@ fi
     : databases.length > 1
       ? `
 # Restore data for all databases
+echo "[$(date '+%H:%M:%S')] Checking for backup files in ${initDir}..."
+ls -la ${initDir}/ 2>/dev/null || echo "  (directory empty or not found)"
 DATABASES="${databases.join(' ')}"
 for DB in $DATABASES; do
     # Find backup file for this database (pattern: containerName-dbName.*)
     BACKUP_FILE=$(ls ${initDir}/${containerName}-$DB.* 2>/dev/null | head -1)
     if [ -n "$BACKUP_FILE" ]; then
-        echo "Restoring database: $DB"
+        echo "[$(date '+%H:%M:%S')] Found backup for database '$DB': $BACKUP_FILE"
         # Add database to tracking if not already tracked
         run_as_spindb spindb databases add "$CONTAINER_NAME" "$DB" 2>/dev/null || true
-        run_as_spindb spindb restore "$CONTAINER_NAME" "$BACKUP_FILE" --database "$DB" --force || echo "Restore of $DB completed with warnings"
+        if ! run_as_spindb spindb restore "$CONTAINER_NAME" "$BACKUP_FILE" --database "$DB" --force; then
+            echo "[$(date '+%H:%M:%S')] ERROR: Restore of '$DB' failed"
+            exit 1
+        fi
+        echo "[$(date '+%H:%M:%S')] Restore of '$DB' completed successfully"
+    else
+        echo "[$(date '+%H:%M:%S')] WARNING: No backup file found for database '$DB'"
     fi
 done
 `
       : `
 # Restore data if backup exists
+echo "[$(date '+%H:%M:%S')] Checking for backup files in ${initDir}..."
+ls -la ${initDir}/ 2>/dev/null || echo "  (directory empty or not found)"
 if ls ${initDir}/* 1> /dev/null 2>&1; then
-    echo "Restoring data from backup..."
     BACKUP_FILE=$(ls ${initDir}/* | head -1)
-    run_as_spindb spindb restore "$CONTAINER_NAME" "$BACKUP_FILE" --database "$DATABASE" --force || echo "Restore completed with warnings"
+    echo "[$(date '+%H:%M:%S')] Found backup file: $BACKUP_FILE"
+    echo "[$(date '+%H:%M:%S')] Restoring to database '$DATABASE'..."
+    if ! run_as_spindb spindb restore "$CONTAINER_NAME" "$BACKUP_FILE" --database "$DATABASE" --force; then
+        echo "[$(date '+%H:%M:%S')] ERROR: Restore failed with exit code $?"
+        exit 1
+    fi
+    echo "[$(date '+%H:%M:%S')] Restore completed successfully"
+else
+    echo "[$(date '+%H:%M:%S')] WARNING: No backup files found in ${initDir}"
 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 "[$(date '+%H:%M:%S')] Granting table permissions to '$SPINDB_USER'..."
+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
+if ! run_as_spindb spindb run "$CONTAINER_NAME" /tmp/grant-permissions.sql --database "$DATABASE"; then
+    echo "[$(date '+%H:%M:%S')] ERROR: Failed to grant permissions"
+    rm -f /tmp/grant-permissions.sql
+    exit 1
+fi
+rm -f /tmp/grant-permissions.sql
+echo "[$(date '+%H:%M:%S')] Permissions granted successfully"
+`
+      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
 
@@ -483,6 +627,8 @@ 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
 
+# PATH will be updated after spindb downloads engine binaries
+
 # 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
@@ -502,16 +648,52 @@ run_as_spindb() {
 }
 
 # Check if container already exists
-if run_as_spindb spindb list --json 2>/dev/null | grep -q '"name":"'"$CONTAINER_NAME"'"'; then
-    echo "Container '$CONTAINER_NAME' already exists"
+if run_as_spindb spindb list --json 2>/dev/null | grep -q '"name": "'"$CONTAINER_NAME"'"'; then
+    echo "[$(date '+%H:%M:%S')] Container '$CONTAINER_NAME' already exists"
+    ${
+      isFileBased
+        ? `# File-based database: no server to start`
+        : `# Check if database is running, start if not (handles Docker restart)
+    if ! run_as_spindb spindb list --json 2>/dev/null | grep -q '"status":.*"running"'; then
+        echo "[$(date '+%H:%M:%S')] Database not running, starting..."
+        if ! run_as_spindb spindb start "$CONTAINER_NAME"; then
+            echo "[$(date '+%H:%M:%S')] ERROR: Failed to start database"
+            exit 1
+        fi
+    fi`
+    }
 else
-    echo "Creating container '$CONTAINER_NAME'..."
+    echo "[$(date '+%H:%M:%S')] Creating container '$CONTAINER_NAME'..."
     ${
       isFileBased
         ? `# File-based database: use deterministic path for database file
-    run_as_spindb spindb create "$CONTAINER_NAME" --engine "$ENGINE" --db-version "$VERSION" --path "$FILE_DB_PATH" --force`
-        : `run_as_spindb spindb create "$CONTAINER_NAME" --engine "$ENGINE" --db-version "$VERSION" --port "$PORT" --database "$DATABASE" --force`
+    if ! run_as_spindb spindb create "$CONTAINER_NAME" --engine "$ENGINE" --db-version "$VERSION" --path "$FILE_DB_PATH" --force; then
+        echo "[$(date '+%H:%M:%S')] ERROR: Failed to create container"
+        exit 1
+    fi`
+        : `# Use --start to ensure database is created (non-TTY defaults to no-start)
+    if ! run_as_spindb spindb create "$CONTAINER_NAME" --engine "$ENGINE" --db-version "$VERSION" --port "$PORT" --database "$DATABASE" --force --start; then
+        echo "[$(date '+%H:%M:%S')] ERROR: Failed to create container"
+        exit 1
+    fi`
     }
+    echo "[$(date '+%H:%M:%S')] Container created successfully"
+fi
+
+# Add engine binary directory to PATH (idempotent - only adds if not present)
+# This allows users to run psql, mysql, etc. directly in the container
+# Note: We add the actual bin directory to PATH instead of creating symlinks
+# because some binaries (like psql) are wrapper scripts that use relative paths
+echo "Setting up database binaries in PATH..."
+BIN_DIR=$(ls -d /home/spindb/.spindb/bin/\${ENGINE}-*/bin 2>/dev/null | head -1)
+if [ -d "$BIN_DIR" ]; then
+    export PATH="$BIN_DIR:$PATH"
+    # Create/overwrite script in /etc/profile.d for system-wide access (idempotent)
+    # This ensures PATH is set for login shells without duplication
+    echo "export PATH=\\"$BIN_DIR:\\$PATH\\"" > /etc/profile.d/spindb-bins.sh
+    echo "Binaries available in PATH: $(ls "$BIN_DIR" | tr '\\n' ' ')"
+else
+    echo "Warning: No engine binaries found"
 fi
 ${networkConfig}${
     isFileBased
@@ -519,29 +701,41 @@ ${networkConfig}${
 # 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"
-
-# Wait for database to be ready
-echo "Waiting for database to be ready..."
+# Database was started by 'spindb create --start' above
+# Wait for database to be fully ready for connections
+echo "[$(date '+%H:%M:%S')] 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
-    echo "Waiting for database... ($RETRIES attempts remaining)"
+    echo "[$(date '+%H:%M:%S')] Waiting for database... ($RETRIES attempts remaining)"
     sleep 2
     RETRIES=$((RETRIES-1))
 done
 
 if [ $RETRIES -eq 0 ]; then
-    echo "Error: Database failed to start"
+    echo "[$(date '+%H:%M:%S')] ERROR: Database failed to start"
     exit 1
 fi`
   }
 
-echo "Database is running!"
+echo "[$(date '+%H:%M:%S')] Database is running!"
+
+# Initialization marker file - ensures user creation and data restore only run once
+INIT_MARKER="/home/spindb/.spindb/.initialized-$CONTAINER_NAME"
+if [ ! -f "$INIT_MARKER" ]; then
+    echo "[$(date '+%H:%M:%S')] ======== FIRST-TIME INITIALIZATION ========"
 ${userCreationCommands}
 ${restoreSection}
+${postRestoreCommands}
+    # Mark initialization complete
+    touch "$INIT_MARKER"
+    chown spindb:spindb "$INIT_MARKER"
+    echo "[$(date '+%H:%M:%S')] ======== INITIALIZATION COMPLETE ========"
+else
+    echo "[$(date '+%H:%M:%S')] Container already initialized, skipping data restore."
+fi
+
 echo "========================================"
+echo "SPINDB_READY"
 echo "SpinDB container ready!"
 echo ""
 echo "Connection: ${getConnectionStringTemplate(engine, port, database, useTLS).replace(/\$/g, '\\$')}"
@@ -948,3 +1142,150 @@ export function getExportBackupPath(
   const extension = getBackupExtension(engine, format)
   return join(outputDir, 'data', `${containerName}-${database}${extension}`)
 }
+
+/**
+ * Get the default Docker export directory for a container
+ */
+export function getDefaultDockerExportPath(
+  containerName: string,
+  engine: Engine,
+): string {
+  return join(
+    homedir(),
+    '.spindb',
+    'containers',
+    engine,
+    containerName,
+    'docker',
+  )
+}
+
+/**
+ * Check if a Docker export already exists for a container
+ */
+export function dockerExportExists(
+  containerName: string,
+  engine: Engine,
+): boolean {
+  const exportPath = getDefaultDockerExportPath(containerName, engine)
+  const envPath = join(exportPath, '.env')
+  return existsSync(envPath)
+}
+
+export type DockerCredentials = {
+  username: string
+  password: string
+  port: number
+  database: string
+  engine: string
+  version: string
+  containerName: string
+}
+
+/**
+ * Read Docker credentials from an existing export's .env file
+ */
+export async function getDockerCredentials(
+  containerName: string,
+  engine: Engine,
+): Promise<DockerCredentials | null> {
+  const exportPath = getDefaultDockerExportPath(containerName, engine)
+  const envPath = join(exportPath, '.env')
+
+  if (!existsSync(envPath)) {
+    return null
+  }
+
+  try {
+    const envContent = await readFile(envPath, 'utf-8')
+    const lines = envContent.split('\n')
+
+    const values: Record<string, string> = {}
+    for (const line of lines) {
+      const match = line.match(/^([A-Z_]+)=(.*)$/)
+      if (match) {
+        values[match[1]] = match[2]
+      }
+    }
+
+    return {
+      username: values.SPINDB_USER || 'spindb',
+      password: values.SPINDB_PASSWORD || '',
+      port: parseInt(values.PORT || '0', 10),
+      database: values.DATABASE || '',
+      engine: values.ENGINE || engine,
+      version: values.VERSION || '',
+      containerName: values.CONTAINER_NAME || containerName,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Get the Docker connection string for an existing export
+ * Returns the connection string with actual credentials substituted
+ */
+export async function getDockerConnectionString(
+  containerName: string,
+  engine: Engine,
+  options: { host?: string } = {},
+): Promise<string | null> {
+  const credentials = await getDockerCredentials(containerName, engine)
+  if (!credentials) {
+    return null
+  }
+
+  const host = options.host || 'localhost'
+  const { username, password, port, database } = credentials
+
+  // URL-encode credentials to escape reserved URI characters
+  const encodedUsername = encodeURIComponent(username)
+  const encodedPassword = encodeURIComponent(password)
+  const encodedDatabase = encodeURIComponent(database)
+
+  // Build connection string based on engine type
+  switch (engine) {
+    case Engine.PostgreSQL:
+    case Engine.CockroachDB:
+    case Engine.QuestDB:
+      return `postgresql://${encodedUsername}:${encodedPassword}@${host}:${port}/${encodedDatabase}`
+
+    case Engine.MySQL:
+    case Engine.MariaDB:
+      return `mysql://${encodedUsername}:${encodedPassword}@${host}:${port}/${encodedDatabase}`
+
+    case Engine.MongoDB:
+    case Engine.FerretDB:
+      return `mongodb://${encodedUsername}:${encodedPassword}@${host}:${port}/${encodedDatabase}`
+
+    case Engine.Redis:
+    case Engine.Valkey:
+      return `redis://:${encodedPassword}@${host}:${port}`
+
+    case Engine.ClickHouse:
+      return `clickhouse://${encodedUsername}:${encodedPassword}@${host}:${port}/${encodedDatabase}`
+
+    case Engine.Qdrant:
+      return `http://${host}:${port}`
+
+    case Engine.Meilisearch:
+      return `http://${host}:${port}`
+
+    case Engine.CouchDB:
+      return `http://${username}:${password}@${host}:${port}/${database}`
+
+    case Engine.SurrealDB:
+      return `ws://${username}:${password}@${host}:${port}`
+
+    case Engine.SQLite:
+    case Engine.DuckDB:
+      return `File-based database (no network connection)`
+
+    default:
+      assertExhaustive(
+        engine,
+        `Unhandled engine in getDockerConnectionString: ${engine}`,
+      )
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.30.6",
+  "version": "0.31.0",
   "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.",