Basic Workflow

# Step 1: Clone production schema (read-only, safe)
aphelion clone postgres://readonly:pass@prod.example.com:5432/myapp \
  --output myapp-schema.json \
  --rows 10000 \
  --exclude audit_logs,sessions

# Step 2: Generate test data
# Step 2: Generate test data
aphelion generate myapp-schema.json --output ./output --overwrite

# Step 3: Load into database
cd ./output && ./load.sh postgres://testuser:testpass@localhost:5432/myapp_test

Using Environment Variables

Keep sensitive credentials out of command history:

# Set environment variables
export DB_USER="myuser"
export DB_PASS="mypassword"
export DB_HOST="localhost"
export DB_NAME="mydb"

# Use them in connection strings
aphelion clone "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:5432/${DB_NAME}" \
  --output schema.json

aphelion generate schema.json --output ./output

# Load using environment variables
cd ./output && ./load.sh "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:5432/test_${DB_NAME}"

# Method 1: URL-encode special characters
# $ becomes %24, @ becomes %40, # becomes %23
export DB_PASS="my%24pass%40word"  # For password: my$pass@word

# Method 2: Use single quotes to prevent shell expansion
export DB_PASS='my$pass@word'  # Single quotes preserve literal values

# Method 3: Escape special characters
export DB_PASS="my\$pass@word"  # Backslash escapes the $

# Then use in connection string (always use double quotes)
aphelion clone "postgres://user:${DB_PASS}@localhost:5432/db" \
  --output schema.json

Reproducible Data (Same Seed)

Generate identical data every time for consistent testing:

# Generate with seed 42
# Generate with seed 42
aphelion generate schema.json --output ./output --seed 42

# Load data (deterministic)
cd ./output && ./load.sh postgres://user:pass@localhost:5432/test_db

# Running again with same seed produces identical data
aphelion generate schema.json --output ./output2 --seed 42
cd ./output2 && ./load.sh postgres://user:pass@localhost:5432/test_db2

CI/CD Integration (Team/Enterprise)

Automated test data refresh in your pipeline:

#!/bin/bash
# .github/workflows/test-data.sh

# Use pipeline ID as seed for reproducibility
# Use pipeline ID as seed for reproducibility
aphelion generate schema.json \
  --output ./output \
  --seed $CI_PIPELINE_ID \
  --auto-approve \
  --overwrite

# Load data
cd ./output && ./load.sh $TEST_DB_URL

# Run your tests
npm test

Controlling Data Volume

Ways to control how much data is generated:

aphelion clone postgres://... \
  --output schema.json \
  --rows 5000  # Each table gets 5,000 rows by default

{
  "tables": {
    "users": {
      "rowCount": 10000,    // 10k users
      ...
    },
    "orders": {
      "rowCount": 100000,   // 100k orders
      ...
    }
  }
}

aphelion introspect

Inspect database schema and output as JSON (no data generation)

Basic Usage:

aphelion introspect --url <connection-string> [--output schema.json]

Options:

• --url - Database connection string (required)
• --schema - Schema name (default: "public")
• --output - Output file path (optional, prints to stdout if not provided)

Examples:

# Introspect and save to file
aphelion introspect --url postgres://user:pass@localhost:5432/mydb \
  --schema public \
  --output schema.json

# Print to stdout for piping
aphelion introspect --url postgres://user:pass@localhost:5432/mydb

# Introspect MySQL database
aphelion introspect --url mysql://user:pass@localhost:3306/mydb \
  --output mysql-schema.json

# Introspect specific schema
aphelion introspect --url postgres://user:pass@localhost:5432/mydb \
  --schema analytics \
  --output analytics-schema.json

aphelion clone

Extract schema from an existing database and save it as JSON

Basic Usage:

aphelion clone <connection-string> --output schema.json

Options:

• --output, -o - Output file path (required)
• --rows, -r - Default row count for generation (default: 100)
• --tables, -t - Specific tables to clone (comma-separated)
• --exclude - Tables to exclude (comma-separated)

Examples:

# Clone entire database
aphelion clone postgres://user:pass@localhost:5432/mydb \\
  --output schema.json

# Clone specific tables only
aphelion clone postgres://user:pass@localhost:5432/mydb \\
  --output schema.json \\
  --tables users,orders,products

# Clone with custom row count
aphelion clone postgres://user:pass@localhost:5432/mydb \\
  --output schema.json \\
  --rows 5000

aphelion generate

Generate synthetic data from a schema file

Basic Usage:

aphelion generate <schema-file> --output <dir>
cd <dir> && ./load.sh <connection-string>

Options:

• --output, -o - Output directory (required)
• --seed, -s - Random seed for deterministic output (default: random)
• --auto-approve - Skip confirmation prompts (Team/Enterprise only)
• --overwrite - Overwrite existing files

Examples:

# Basic generation
aphelion generate schema.json --output ./output
cd ./output && ./load.sh postgres://user:pass@localhost:5432/test_db

# Deterministic generation with seed
aphelion generate schema.json --output ./output --seed 12345
cd ./output && ./load.sh postgres://user:pass@localhost:5432/test_db

# CI/CD mode (Team/Enterprise)
aphelion generate schema.json \
  --output ./output \
  --auto-approve \
  --overwrite
cd ./output && ./load.sh postgres://user:pass@localhost:5432/test_db