Aphelion Documentation

The only synthetic data generator that respects your schema constraints, respects your privacy, and integrates with your workflow.

Overview

Aphelion is a constraint-safe, deterministic synthetic data generator for **PostgreSQL and MySQL/MariaDB**. It intelligently introspects your database schema, respects all foreign key relationships (including circular dependencies), and generates realistic test data that actually works.

100% Coverage

Support for exotic types like PostGIS, ltree, hstore, and Range types.

Constraint-Safe

Zero foreign key violations. Guaranteed data integrity across complex tables and circular references.

Weighted Distributions

New in v1.7.8: Model real-world skew, Pareto/Zipfian distributions, and custom category frequencies.

Temporal Constraints

New in v1.7.8: Guaranteed chronological consistency across timestamps, audit trails, and event sequences.

Quick Start

1. Prepare the Binary

Download the standalone Rust binary for your platform and make it executable.

# Make the downloaded binary executable
chmod +x aphelion

# Verify version
./aphelion --version
# Output: aphelion 1.7.8

# (Optional) Install system-wide
sudo mv aphelion /usr/local/bin/

2. Introspect & Clone (1-Step)

Create a perfect replica of your production schema structure with synthetic data in one command.

# PostgreSQL
./aphelion clone --url "postgresql://user:pass@localhost:5432/prod" --schema public --count 1000

# MySQL
./aphelion clone --url "mysql://user:pass@localhost:3306/prod" --schema prod --count 1000

3. Or Use the 2-Step Workflow (Introspect → Generate)

Export your schema to a portable JSON blueprint, tune distributions or constraints, and generate deterministically.

# Step A: Introspect database into schema file
./aphelion introspect --url "postgresql://user:pass@localhost:5432/prod" --schema public --output schema.json

# Step B: Generate constraint-safe SQL datasets from the blueprint
./aphelion generate schema.json --output ./output --rows 1000 --seed 42

4. Load and Test

Aphelion automatically generates dependency-ordered SQL files and executable load scripts (`load.sh` and `load.bat`).

cd output
./load.sh target_db
Core Capabilities

Core Capabilities

Aphelion couples deep AST-level database introspection with deterministic constraint solvers and portable blueprints to eliminate foreign key violations, resolve circular dependencies, and accurately model complex business logic.

Blueprint Customization

Declarative JSON blueprints, distributions, and temporal rules.

Database Coverage

100% type support for PostgreSQL, MySQL, and SQLite.

Cycle Resolution

Tarjan SCC graph topological sorting and 2-phase load.
Core Engine

Key Features & Blueprint Customization

Aphelion couples deep AST-level database introspection with a declarative JSON schema blueprint. Introspected blueprints capture table hierarchies, primary key registries, check constraints, foreign keys, and column distributions.

Portable Blueprint (schema.json)

When using the 2-step workflow, aphelion introspect outputs a structured blueprint. You can tune table generation rules, weighted distributions, and temporal bounds before running generate: 

{
  "name": "ecommerce_schema",
  "tables": [
    {
      "name": "orders",
      "columns": [
        { "name": "order_id", "data_type": "Uuid", "is_primary_key": true },
        { "name": "customer_id", "data_type": "Uuid", "foreign_key": { "table": "customers", "column": "id" } },
        { "name": "status", "data_type": "Enum", "distribution": { "type": "weighted", "weights": { "completed": 0.70, "pending": 0.20, "cancelled": 0.10 } } },
        { "name": "created_at", "data_type": "Timestamp", "temporal": { "after": "customers.created_at", "before": "orders.shipped_at" } }
      ]
    }
  ]
}

Database Coverage & Exotic Types

PostgreSQL
  • Native JSONB & Composite Arrays
  • PostGIS (Geometry, Geography)
  • Hierarchical Trees (ltree)
  • Partitioned Tables (Range, List, Hash)
  • Generated Stored & Identity Columns
MySQL & MariaDB
  • AUTO_INCREMENT Primary Keys
  • ENUM and SET Data Types
  • Unsigned Integers & Decimals
  • Multi-database & Cross-schema FKs
  • Bulk Multi-row Batch SQL Inserts
SQLite
  • Type Affinity Dynamic Mapping
  • PRAGMA Foreign Keys Compliance
  • In-Memory & File-based DB Cloning
  • Without ROWID Optimization
  • Single-file Self-contained Testing

Circular Dependencies & Graph Resolution

Real-world production databases often have self-referencing tables (e.g. employee manager hierarchies) or circular foreign key cycles (e.g., users → teams → users). Standard tools crash or produce foreign key constraint violations during loading.

Strongly Connected Components (SCC)

Aphelion builds a topological graph of foreign key dependencies using Tarjan's algorithm to identify strongly connected components and cycle boundaries.

Two-Phase Insert Strategy

Cycles are broken cleanly: nullable foreign keys are initially inserted as NULL during seed generation, followed by automated secondary UPDATE statements once all parent rows are verified.

Industry Verticals

Healthcare & Life Sciences

Verified support for OMOP CDM (v5.4) and OpenMRS EAV models. Includes HIPAA-compliant PII masking.

11.6M
Rows Supported
100k
Unique MRNs
SNOMED
Terminology Hub

Clinical Databases

  • ICD-10 (55 Categories)
  • RxNorm (190 Meds)
  • FHIR R4 Resources
  • RxClaims (Pharmacy)

Finance & Banking

Matches or exceeds all 6 industry-standard financial datasets including TPC-E, PaySim, and IEEE-CIS.

Feature TPC-E IEEE-CIS Aphelion
Fraud Detection Partial Full Full
PCI-DSS Tokenization No Partial Full
Multi-Currency Partial No Full

E-commerce & Retail

Full synthetic benchmarking validated on complex retail architectures including Magento 2 EAV (Entity-Attribute-Value) schemas, Shopify-style multi-tenant catalogs, and high-frequency order processing pipelines.

EAV Validated
Magento 2 Compatible
Hierarchical
Category Tree Integrity
Full Lifecycle
Cart → Payment → Fulfillment

Retail Domain Engine

  • Dynamic SKU and Barcode (UPC/EAN) Generators
  • Consistent Inventory Stocks & Multi-Warehouse Allocation
  • Tiered Pricing, Discount Coupons, and Jurisdictional Tax
  • Chronological Tracking: Order → Invoiced → Shipped

Command Reference

aphelion clone

1-Step Workflow

Introspects a source database and directly generates synthetic test data into dependency-ordered SQL files and executable load scripts.

aphelion clone --url <DATABASE_URL> [OPTIONS]
Option Default Description
--url <URL> required Database connection URL (postgresql://, mysql://, or sqlite://).
--schema <NAME> public Schema name to introspect and clone.
--count <N> 100 Number of rows to generate per table.
--tables <LIST> all Comma-separated tables to clone (e.g. "users,orders").
--exclude <LIST> none Comma-separated tables to exclude (e.g. "audit_log,film_text").
-o, --output <FILE> none Save extracted JSON schema blueprint to a file while cloning.

aphelion introspect

Blueprint Extraction

Reads the structure of a live database (PostgreSQL, MySQL, SQLite) and outputs a `.schema.json` blueprint.

aphelion introspect --url <DATABASE_URL> [--schema <NAME>] [-o <FILE>]
Option Default Description
--url <URL> required Database connection string.
--schema <NAME> public Target schema name.
-o, --output <FILE> stdout Output path for JSON blueprint (prints to stdout if omitted).

aphelion generate

Synthesis Engine

Transforms a schema blueprint into high-fidelity, constraint-safe SQL datasets and executable load scripts.

aphelion generate <SCHEMA_FILE> -o <OUTPUT_DIR> [OPTIONS]
Option Default Description
<FILE> positional Path to the schema JSON file.
-o, --output <DIR> required Output directory for SQL files and load scripts.
--rows <N> 100 Number of rows to generate per table.
-s, --seed <U64> random Deterministic seed for reproducible generation across CI/CD runs.
--overwrite false Overwrite existing files in output directory without prompting.

aphelion license

Entitlement Management

Inspect and verify active license tier, expiration status, and row volume entitlements.

# Show current license information and limits
aphelion license info

# Verify license cryptographic signature
aphelion license verify

CI/CD Automation

Automate your testing pipeline by generating fresh, constraint-safe test databases on every push. Using fixed seeds guarantees deterministic, reproducible integration test runs.

GitHub Actions Pattern (Pro)

# .github/workflows/test.yml
name: Test Suite with Synthetic Data
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Download Aphelion CLI
        run: |
          curl -L "https://algomimic.com/api/download/pro?key=${{ secrets.APHELION_LICENSE_KEY }}" -o aphelion
          chmod +x aphelion
          ./aphelion --version

      - name: Clone & Populate Test Database
        run: |
          ./aphelion clone \
            --url "${{ secrets.DATABASE_URL }}" \
            --schema public \
            --count 500 \
            --output ./test-fixtures/schema.json

      - name: Run Test Suite
        run: npm test