spindb 0.5.3 → 0.5.5

package/core/dependency-manager.ts

@@ -15,8 +15,12 @@ import {
   packageManagers,
   getEngineDependencies,
   getUniqueDependencies,
+  usqlDependency,
+  pgcliDependency,
+  mycliDependency,
 } from '../config/os-dependencies'
 import { platformService } from './platform-service'
+import { configManager } from './config-manager'
 
 const execAsync = promisify(exec)
 
@@ -265,6 +269,10 @@ export async function installDependency(
       execWithInheritedStdio(cmd)
     }
 
+    // Refresh config cache after package manager interaction
+    // This ensures newly installed tools are detected with correct versions
+    await configManager.refreshAllBinaries()
+
     // Verify installation
     const status = await checkDependency(dependency)
     if (!status.installed) {
@@ -421,3 +429,135 @@ export async function getAllDependencyReports(): Promise<
   )
   return reports
 }
+
+// =============================================================================
+// usql (Enhanced Shell) Support
+// =============================================================================
+
+/**
+ * Check if usql is installed
+ */
+export async function isUsqlInstalled(): Promise<boolean> {
+  const status = await checkDependency(usqlDependency)
+  return status.installed
+}
+
+/**
+ * Get usql dependency status
+ */
+export async function getUsqlStatus(): Promise<DependencyStatus> {
+  return checkDependency(usqlDependency)
+}
+
+/**
+ * Install usql using the detected package manager
+ */
+export async function installUsql(
+  packageManager: DetectedPackageManager,
+): Promise<InstallResult> {
+  return installDependency(usqlDependency, packageManager)
+}
+
+/**
+ * Get usql manual installation instructions
+ */
+export function getUsqlManualInstructions(
+  platform: Platform = getCurrentPlatform(),
+): string[] {
+  return getManualInstallInstructions(usqlDependency, platform)
+}
+
+/**
+ * Get the usql dependency definition
+ */
+export function getUsqlDependency(): Dependency {
+  return usqlDependency
+}
+
+// =============================================================================
+// pgcli (PostgreSQL Enhanced Shell) Support
+// =============================================================================
+
+/**
+ * Check if pgcli is installed
+ */
+export async function isPgcliInstalled(): Promise<boolean> {
+  const status = await checkDependency(pgcliDependency)
+  return status.installed
+}
+
+/**
+ * Get pgcli dependency status
+ */
+export async function getPgcliStatus(): Promise<DependencyStatus> {
+  return checkDependency(pgcliDependency)
+}
+
+/**
+ * Install pgcli using the detected package manager
+ */
+export async function installPgcli(
+  packageManager: DetectedPackageManager,
+): Promise<InstallResult> {
+  return installDependency(pgcliDependency, packageManager)
+}
+
+/**
+ * Get pgcli manual installation instructions
+ */
+export function getPgcliManualInstructions(
+  platform: Platform = getCurrentPlatform(),
+): string[] {
+  return getManualInstallInstructions(pgcliDependency, platform)
+}
+
+/**
+ * Get the pgcli dependency definition
+ */
+export function getPgcliDependency(): Dependency {
+  return pgcliDependency
+}
+
+// =============================================================================
+// mycli (MySQL Enhanced Shell) Support
+// =============================================================================
+
+/**
+ * Check if mycli is installed
+ */
+export async function isMycliInstalled(): Promise<boolean> {
+  const status = await checkDependency(mycliDependency)
+  return status.installed
+}
+
+/**
+ * Get mycli dependency status
+ */
+export async function getMycliStatus(): Promise<DependencyStatus> {
+  return checkDependency(mycliDependency)
+}
+
+/**
+ * Install mycli using the detected package manager
+ */
+export async function installMycli(
+  packageManager: DetectedPackageManager,
+): Promise<InstallResult> {
+  return installDependency(mycliDependency, packageManager)
+}
+
+/**
+ * Get mycli manual installation instructions
+ */
+export function getMycliManualInstructions(
+  platform: Platform = getCurrentPlatform(),
+): string[] {
+  return getManualInstallInstructions(mycliDependency, platform)
+}
+
+/**
+ * Get the mycli dependency definition
+ */
+export function getMycliDependency(): Dependency {
+  return mycliDependency
+}

package/engines/base-engine.ts

@@ -2,6 +2,8 @@ import type {
   ContainerConfig,
   ProgressCallback,
   BackupFormat,
+  BackupOptions,
+  BackupResult,
   RestoreResult,
   DumpResult,
   StatusResult,
@@ -131,4 +133,22 @@ export abstract class BaseEngine {
     connectionString: string,
     outputPath: string,
   ): Promise<DumpResult>
+
+  /**
+   * Get the size of a database in bytes
+   * Returns null if the container is not running or size cannot be determined
+   */
+  abstract getDatabaseSize(container: ContainerConfig): Promise<number | null>
+
+  /**
+   * Create a backup of a database
+   * @param container - The container configuration
+   * @param outputPath - Path to write the backup file
+   * @param options - Backup options including database name and format
+   */
+  abstract backup(
+    container: ContainerConfig,
+    outputPath: string,
+    options: BackupOptions,
+  ): Promise<BackupResult>
 }

package/engines/mysql/backup.ts

@@ -0,0 +1,159 @@
+/**
+ * MySQL Backup
+ *
+ * Creates database backups in SQL or compressed (.dump = gzipped SQL) format using mysqldump.
+ */
+
+import { spawn } from 'child_process'
+import { createWriteStream } from 'fs'
+import { stat } from 'fs/promises'
+import { createGzip } from 'zlib'
+import { pipeline } from 'stream/promises'
+import { getMysqldumpPath } from './binary-detection'
+import { getEngineDefaults } from '../../config/defaults'
+import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
+
+const engineDef = getEngineDefaults('mysql')
+
+/**
+ * Create a backup of a MySQL database
+ *
+ * CLI equivalent:
+ * - SQL format: mysqldump -h 127.0.0.1 -P {port} -u root --result-file={outputPath} {database}
+ * - Dump format: mysqldump -h 127.0.0.1 -P {port} -u root {database} | gzip > {outputPath}
+ */
+export async function createBackup(
+  container: ContainerConfig,
+  outputPath: string,
+  options: BackupOptions,
+): Promise<BackupResult> {
+  const { port } = container
+  const { database, format } = options
+
+  const mysqldump = await getMysqldumpPath()
+  if (!mysqldump) {
+    throw new Error(
+      'mysqldump not found. Install MySQL client tools:\n' +
+        '  macOS: brew install mysql-client\n' +
+        '  Ubuntu/Debian: sudo apt install mysql-client',
+    )
+  }
+
+  if (format === 'sql') {
+    return createSqlBackup(mysqldump, port, database, outputPath)
+  } else {
+    return createCompressedBackup(mysqldump, port, database, outputPath)
+  }
+}
+
+/**
+ * Create a plain SQL backup
+ */
+async function createSqlBackup(
+  mysqldump: string,
+  port: number,
+  database: string,
+  outputPath: string,
+): Promise<BackupResult> {
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-P',
+      String(port),
+      '-u',
+      engineDef.superuser,
+      '--result-file',
+      outputPath,
+      database,
+    ]
+
+    const proc = spawn(mysqldump, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    let stderr = ''
+
+    proc.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    proc.on('error', (err: NodeJS.ErrnoException) => {
+      reject(err)
+    })
+
+    proc.on('close', async (code) => {
+      if (code === 0) {
+        const stats = await stat(outputPath)
+        resolve({
+          path: outputPath,
+          format: 'sql',
+          size: stats.size,
+        })
+      } else {
+        const errorMessage = stderr || `mysqldump exited with code ${code}`
+        reject(new Error(errorMessage))
+      }
+    })
+  })
+}
+
+/**
+ * Create a compressed (gzipped) backup
+ * Uses Node's zlib for compression instead of relying on system gzip
+ */
+async function createCompressedBackup(
+  mysqldump: string,
+  port: number,
+  database: string,
+  outputPath: string,
+): Promise<BackupResult> {
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-P',
+      String(port),
+      '-u',
+      engineDef.superuser,
+      database,
+    ]
+
+    const proc = spawn(mysqldump, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    const gzip = createGzip()
+    const output = createWriteStream(outputPath)
+
+    let stderr = ''
+
+    proc.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    // Pipe mysqldump stdout -> gzip -> file
+    pipeline(proc.stdout!, gzip, output)
+      .then(async () => {
+        const stats = await stat(outputPath)
+        resolve({
+          path: outputPath,
+          format: 'compressed',
+          size: stats.size,
+        })
+      })
+      .catch(reject)
+
+    proc.on('error', (err: NodeJS.ErrnoException) => {
+      reject(err)
+    })
+
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        const errorMessage = stderr || `mysqldump exited with code ${code}`
+        reject(new Error(errorMessage))
+      }
+      // If code is 0, the pipeline promise will resolve
+    })
+  })
+}

package/engines/mysql/index.ts

@@ -33,10 +33,13 @@ import {
   restoreBackup,
   parseConnectionString,
 } from './restore'
+import { createBackup } from './backup'
 import type {
   ContainerConfig,
   ProgressCallback,
   BackupFormat,
+  BackupOptions,
+  BackupResult,
   RestoreResult,
   DumpResult,
   StatusResult,
@@ -734,6 +737,31 @@ export class MySQLEngine extends BaseEngine {
     }
   }
 
+  /**
+   * Get the size of the container's database in bytes
+   * Uses information_schema.tables to sum data_length + index_length
+   * Returns null if container is not running or query fails
+   */
+  async getDatabaseSize(container: ContainerConfig): Promise<number | null> {
+    const { port, database } = container
+    const db = database || 'mysql'
+
+    try {
+      const mysql = await getMysqlClientPath()
+      if (!mysql) return null
+
+      // Query information_schema for total data + index size
+      const { stdout } = await execAsync(
+        `"${mysql}" -h 127.0.0.1 -P ${port} -u ${engineDef.superuser} -N -e "SELECT COALESCE(SUM(data_length + index_length), 0) FROM information_schema.tables WHERE table_schema = '${db}'"`,
+      )
+      const size = parseInt(stdout.trim(), 10)
+      return isNaN(size) ? null : size
+    } catch {
+      // Container not running or query failed
+      return null
+    }
+  }
+
   /**
    * Create a dump from a remote database using a connection string
    * CLI wrapper: mysqldump -h {host} -P {port} -u {user} -p{pass} {db} > {file}
@@ -803,6 +831,17 @@ export class MySQLEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * Create a backup of a MySQL database
+   */
+  async backup(
+    container: ContainerConfig,
+    outputPath: string,
+    options: BackupOptions,
+  ): Promise<BackupResult> {
+    return createBackup(container, outputPath, options)
+  }
 }
 
 export const mysqlEngine = new MySQLEngine()

package/engines/mysql/restore.ts

@@ -7,6 +7,7 @@
 import { spawn } from 'child_process'
 import { createReadStream } from 'fs'
 import { open } from 'fs/promises'
+import { createGunzip } from 'zlib'
 import { getMysqlClientPath } from './binary-detection'
 import { validateRestoreCompatibility } from './version-validator'
 import { getEngineDefaults } from '../../config/defaults'
@@ -200,6 +201,7 @@ export async function restoreBackup(
 
   // Restore using mysql client
   // CLI: mysql -h 127.0.0.1 -P {port} -u root {db} < {file}
+  // For compressed files: gunzip -c {file} | mysql ...
   return new Promise((resolve, reject) => {
     const args = ['-h', '127.0.0.1', '-P', String(port), '-u', user, database]
 
@@ -207,9 +209,21 @@ export async function restoreBackup(
       stdio: ['pipe', 'pipe', 'pipe'],
     })
 
-    // Pipe backup file to stdin
+    // Pipe backup file to stdin, decompressing if necessary
     const fileStream = createReadStream(backupPath)
-    fileStream.pipe(proc.stdin)
+
+    if (format.format === 'compressed') {
+      // Decompress gzipped file before piping to mysql
+      const gunzip = createGunzip()
+      fileStream.pipe(gunzip).pipe(proc.stdin)
+
+      // Handle gunzip errors
+      gunzip.on('error', (err) => {
+        reject(new Error(`Failed to decompress backup file: ${err.message}`))
+      })
+    } else {
+      fileStream.pipe(proc.stdin)
+    }
 
     let stdout = ''
     let stderr = ''

package/engines/postgresql/backup.ts

@@ -0,0 +1,93 @@
+/**
+ * PostgreSQL Backup
+ *
+ * Creates database backups in SQL or custom (.dump) format using pg_dump.
+ */
+
+import { spawn } from 'child_process'
+import { stat } from 'fs/promises'
+import { configManager } from '../../core/config-manager'
+import { defaults } from '../../config/defaults'
+import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
+
+/**
+ * Get pg_dump path from config, with helpful error message
+ */
+async function getPgDumpPath(): Promise<string> {
+  const pgDumpPath = await configManager.getBinaryPath('pg_dump')
+  if (!pgDumpPath) {
+    throw new Error(
+      'pg_dump not found. Install PostgreSQL client tools:\n' +
+        '  macOS: brew install libpq && brew link --force libpq\n' +
+        '  Ubuntu/Debian: apt install postgresql-client\n\n' +
+        'Or configure manually: spindb config set pg_dump /path/to/pg_dump',
+    )
+  }
+  return pgDumpPath
+}
+
+/**
+ * Create a backup of a PostgreSQL database
+ *
+ * CLI equivalent:
+ * - SQL format: pg_dump -Fp -h 127.0.0.1 -p {port} -U postgres -d {database} -f {outputPath}
+ * - Dump format: pg_dump -Fc -h 127.0.0.1 -p {port} -U postgres -d {database} -f {outputPath}
+ */
+export async function createBackup(
+  container: ContainerConfig,
+  outputPath: string,
+  options: BackupOptions,
+): Promise<BackupResult> {
+  const { port } = container
+  const { database, format } = options
+
+  const pgDumpPath = await getPgDumpPath()
+
+  // -Fp = plain SQL format, -Fc = custom format
+  const formatFlag = format === 'sql' ? '-Fp' : '-Fc'
+
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-p',
+      String(port),
+      '-U',
+      defaults.superuser,
+      '-d',
+      database,
+      formatFlag,
+      '-f',
+      outputPath,
+    ]
+
+    const proc = spawn(pgDumpPath, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    let stderr = ''
+
+    proc.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    proc.on('error', (err: NodeJS.ErrnoException) => {
+      reject(err)
+    })
+
+    proc.on('close', async (code) => {
+      if (code === 0) {
+        // Get file size
+        const stats = await stat(outputPath)
+        resolve({
+          path: outputPath,
+          format: format === 'sql' ? 'sql' : 'custom',
+          size: stats.size,
+        })
+      } else {
+        const errorMessage = stderr || `pg_dump exited with code ${code}`
+        reject(new Error(errorMessage))
+      }
+    })
+  })
+}

package/engines/postgresql/index.ts

@@ -12,12 +12,17 @@ import {
   getBinaryUrl,
   SUPPORTED_MAJOR_VERSIONS,
   fetchAvailableVersions,
+  getLatestVersion,
+  FALLBACK_VERSION_MAP,
 } from './binary-urls'
 import { detectBackupFormat, restoreBackup } from './restore'
+import { createBackup } from './backup'
 import type {
   ContainerConfig,
   ProgressCallback,
   BackupFormat,
+  BackupOptions,
+  BackupResult,
   RestoreResult,
   DumpResult,
   StatusResult,
@@ -50,14 +55,42 @@ export class PostgreSQLEngine extends BaseEngine {
     }
   }
 
+  /**
+   * Resolve a version string to a full version.
+   * If given a major version like '17', resolves to '17.7.0'.
+   * If already a full version like '17.7.0', returns as-is.
+   */
+  resolveFullVersion(version: string): string {
+    // Check if already a full version (has at least one dot with numbers after)
+    if (/^\d+\.\d+/.test(version)) {
+      return version
+    }
+    // It's a major version, resolve using fallback map (sync, no network)
+    return FALLBACK_VERSION_MAP[version] || `${version}.0.0`
+  }
+
+  /**
+   * Resolve version asynchronously (tries network first for latest)
+   */
+  async resolveFullVersionAsync(version: string): Promise<string> {
+    // Check if already a full version
+    if (/^\d+\.\d+/.test(version)) {
+      return version
+    }
+    // Resolve from network/cache
+    return getLatestVersion(version)
+  }
+
   /**
    * Get binary path for current platform
+   * Uses full version for directory naming (e.g., postgresql-17.7.0-darwin-arm64)
    */
   getBinaryPath(version: string): string {
+    const fullVersion = this.resolveFullVersion(version)
     const { platform: p, arch: a } = this.getPlatformInfo()
     return paths.getBinaryPath({
       engine: 'postgresql',
-      version,
+      version: fullVersion,
       platform: p,
       arch: a,
     })
@@ -339,6 +372,29 @@ export class PostgreSQLEngine extends BaseEngine {
     }
   }
 
+  /**
+   * Get the size of the container's database in bytes
+   * Uses pg_database_size() to get accurate data size
+   * Returns null if container is not running or query fails
+   */
+  async getDatabaseSize(container: ContainerConfig): Promise<number | null> {
+    const { port, database } = container
+    const db = database || 'postgres'
+
+    try {
+      const psqlPath = await this.getPsqlPath()
+      // Query pg_database_size for the specific database
+      const { stdout } = await execAsync(
+        `"${psqlPath}" -h 127.0.0.1 -p ${port} -U ${defaults.superuser} -d postgres -t -A -c "SELECT pg_database_size('${db}')"`,
+      )
+      const size = parseInt(stdout.trim(), 10)
+      return isNaN(size) ? null : size
+    } catch {
+      // Container not running or query failed
+      return null
+    }
+  }
+
   /**
    * Create a dump from a remote database using a connection string
    * @param connectionString PostgreSQL connection string (e.g., postgresql://user:pass@host:port/dbname)
@@ -390,6 +446,17 @@ export class PostgreSQLEngine extends BaseEngine {
       })
     })
   }
+
+  /**
+   * Create a backup of a PostgreSQL database
+   */
+  async backup(
+    container: ContainerConfig,
+    outputPath: string,
+    options: BackupOptions,
+  ): Promise<BackupResult> {
+    return createBackup(container, outputPath, options)
+  }
 }
 
 export const postgresqlEngine = new PostgreSQLEngine()

package/package.json

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

package/types/index.ts

@@ -4,6 +4,7 @@ export type ContainerConfig = {
   version: string
   port: number
   database: string
+  databases?: string[]
   created: string
   status: 'created' | 'running' | 'stopped'
   clonedFrom?: string
@@ -56,6 +57,17 @@ export type RestoreResult = {
   code?: number
 }
 
+export type BackupOptions = {
+  database: string
+  format: 'sql' | 'dump'
+}
+
+export type BackupResult = {
+  path: string
+  format: string
+  size: number
+}
+
 export type DumpResult = {
   filePath: string
   stdout?: string
@@ -85,6 +97,10 @@ export type BinaryTool =
   | 'mysqlpump'
   | 'mysqld'
   | 'mysqladmin'
+  // Enhanced shells (optional)
+  | 'pgcli'
+  | 'mycli'
+  | 'usql'
 
 /**
  * Source of a binary - bundled (downloaded by spindb) or system (found on PATH)
@@ -118,6 +134,10 @@ export type SpinDBConfig = {
     mysqlpump?: BinaryConfig
     mysqld?: BinaryConfig
     mysqladmin?: BinaryConfig
+    // Enhanced shells (optional)
+    pgcli?: BinaryConfig
+    mycli?: BinaryConfig
+    usql?: BinaryConfig
   }
   // Default settings
   defaults?: {