@launch77/database-dev

Development-time database infrastructure utilities for Launch77 apps. This library provides tools for managing Docker containers, PostgreSQL databases, user prompts, and validation during development.

Note: This is a development-only library. Do not use in production code.

Features

• Docker Management - Port checking, container operations, health monitoring
• PostgreSQL Operations - Container lifecycle, connection testing, health checks
• User Prompts - Interactive confirmations and input collection
• Validation - Environment variables, dependencies, naming conventions

Installation

npm install --save-dev @launch77/database-dev

Usage

Docker Utilities

import {
  checkPortAvailability,
  isDockerRunning,
  findContainerByName,
  waitForContainerHealthy,
} from '@launch77/database-dev'

// Check if a port is available
const portCheck = await checkPortAvailability('5432')
if (!portCheck.available) {
  console.log(`Port in use by: ${portCheck.usedBy}`)
  console.log(`Project: ${portCheck.projectPath}`)
}

// Check if Docker is running
const dockerRunning = await isDockerRunning()

// Find a container
const container = await findContainerByName('my-postgres')
if (container) {
  console.log(`Status: ${container.status}`)
}

// Wait for container to be healthy
await waitForContainerHealthy('my-postgres', 30, 1000)

PostgreSQL Container Operations

import {
  checkPostgresContainerExists,
  startPostgresContainer,
  waitForPostgresReady,
  destroyPostgresContainer,
} from '@launch77/database-dev'

const composeFile = 'docker-compose.db.yml'

// Check if container exists
const exists = await checkPostgresContainerExists(composeFile)

// Start container
await startPostgresContainer(composeFile)

// Wait for database to be ready
await waitForPostgresReady(
  'postgres://user:pass@localhost:5432/mydb',
  60, // max attempts
  1000 // interval ms
)

// Destroy container and volumes
await destroyPostgresContainer(composeFile)

User Prompts

import { confirmAction, promptForInput, selectFromList } from '@launch77/database-dev'

// Confirm action
const confirmed = await confirmAction('Delete database?', false)

// Get user input
const name = await promptForInput('Database name:', 'default_db')

// Select from list
const option = await selectFromList(
  'Choose environment:',
  ['development', 'staging', 'production'],
  0 // default index
)

Validation

import {
  validateEnvironment,
  validateDependencies,
  validateConnectionString,
  validateMigrationName,
} from '@launch77/database-dev'

// Validate environment variables
const envResult = validateEnvironment({
  required: ['DATABASE_URL', 'API_KEY'],
  optional: ['DEBUG'],
  validateFormat: true,
})

if (!envResult.valid) {
  console.error('Errors:', envResult.errors)
}

// Validate dependencies
const depResult = await validateDependencies(['docker', 'docker-compose'])

// Validate connection string
const connResult = validateConnectionString('postgres://user:pass@localhost:5432/mydb')

// Validate migration name
const validName = validateMigrationName('add_user_table') // true
const invalidName = validateMigrationName('Add User Table') // false

API Reference

Docker Utilities

• checkPortAvailability(port) - Check if port is available
• isDockerRunning() - Check if Docker daemon is running
• findContainerByName(name) - Find container by name
• getContainerStatus(name) - Get container status
• startContainer(name) - Start a container
• stopContainer(name) - Stop a container
• removeContainer(name, force?) - Remove a container
• waitForContainerHealthy(name, maxAttempts?, intervalMs?) - Wait for container health
• execInContainer(name, command) - Execute command in container
• getContainerLogs(name, tail?) - Get container logs

PostgreSQL Container Utilities

• checkPostgresContainerExists(composeFilePath) - Check if container exists
• startPostgresContainer(composeFilePath) - Start PostgreSQL container
• stopPostgresContainer(composeFilePath) - Stop PostgreSQL container
• destroyPostgresContainer(composeFilePath) - Destroy container and volumes
• waitForPostgresReady(connectionString, maxAttempts?, intervalMs?) - Wait for database
• testPostgresConnection(connectionString) - Test database connection
• getPostgresVersion(connectionString) - Get PostgreSQL version

Prompt Utilities

• confirmAction(question, defaultValue?) - Yes/no confirmation
• promptForInput(question, defaultValue?) - Text input
• selectFromList(question, options, defaultIndex?) - List selection
• promptForPassword(question) - Password input (note: not hidden in basic Node.js)

Validation Utilities

• validateEnvironment(options) - Validate environment variables
• checkCommandExists(command) - Check if command is available
• validateDependencies(dependencies) - Validate required commands
• checkPrerequisites() - Run all prerequisite checks
• validateMigrationName(name) - Validate migration name format
• validateDatabaseName(name) - Validate database name format
• validatePort(port) - Validate port number
• validateConnectionString(connectionString) - Validate PostgreSQL connection string

Type Exports

import type {
  PortCheckResult,
  ContainerInfo,
  PostgresContainerConfig,
  PostgresConnectionError,
  ValidationResult,
  EnvironmentValidationOptions,
} from '@launch77/database-dev'

Error Handling

All functions that interact with external systems (Docker, filesystem) can throw errors. Always wrap in try/catch:

try {
  await startPostgresContainer('docker-compose.yml')
} catch (error) {
  console.error('Failed to start container:', error.message)
}

PostgreSQL connection functions provide classified errors:

try {
  await waitForPostgresReady(connectionString)
} catch (error) {
  if (error.isAuthError) {
    console.error('Authentication failed')
  } else if (error.isDatabaseMissingError) {
    console.error('Database does not exist')
  }
}

Testing

All utilities include comprehensive unit tests. Run tests with:

npm test

License

UNLICENSED - Internal Launch77 use only