synthdb 0.1.3

The Universal Database Seeder. Production-grade synthetic data generator for PostgreSQL. Zero config, context-aware.
synthdb-0.1.3 is not a library.

🦀 SynthDB

The Universal Database Seeder

Production-grade synthetic data. Zero config. Context-aware.

Crates.io Built with Rust License: MIT Documentation

Features • Quick Start • Examples • Contributing

📖 Overview

SynthDB is a next-generation database seeding engine that reads your existing PostgreSQL schema and generates statistically realistic, relational data automatically.

Unlike traditional tools that generate random gibberish, SynthDB employs a Deep Semantic Engine to understand your data model's context and relationships, producing data that looks and feels real.

-- Instead of this garbage:
INSERT INTO users VALUES ('XJ9K2', 'asdf@qwerty', '99999', 'ZZZ');

-- SynthDB generates this:
INSERT INTO users VALUES ('John Doe', 'john.doe@techcorp.com', '+1-555-0142', 'San Francisco, CA');

✨ Features

🧠 Deep Semantic Intelligence

SynthDB understands the meaning of your columns, not just their types.

🎯 Context-Aware Identity

If a table has first_name, last_name, and email, SynthDB ensures they match perfectly:

🏷️ Smart Categorization

Automatically detects and generates valid data across multiple domains:

💰 Finance

  • Credit Cards (valid Luhn)
  • IBANs & Swift Codes
  • Cryptocurrency Addresses
  • Currency Codes & Amounts

🌍 Geography

  • Coherent Addresses
  • Cities ↔ States ↔ Zip Codes
  • Latitude/Longitude Pairs
  • Time Zones

🔬 Science

  • Chemical Formulas
  • DNA Sequences
  • Medical/ICD Codes
  • Laboratory Values

💻 Technology

  • IPv4 & IPv6 Addresses
  • MAC Addresses
  • User Agents
  • File Paths & URLs

🏢 Business

  • Company Names
  • Job Titles
  • Department Names
  • Stock Tickers

📱 Personal

  • Phone Numbers
  • Social Security Numbers
  • Passport Numbers
  • Driver's License IDs

🔗 Referential Integrity

📊 Topological Sort

Automatically analyzes foreign key dependencies and inserts data in the correct order:

Users → Orders → OrderItems → Shipments

✅ Zero Broken Links

Generated foreign keys always reference valid, existing parent rows. No orphaned records, ever.

-- Parent record created first
INSERT INTO customers (id, name) VALUES (1, 'Acme Corp');

-- Child record references existing parent
INSERT INTO orders (id, customer_id, total) VALUES (101, 1, 1299.99);

🛡️ Production Ready

Feature Description
Strict Precision Respects NUMERIC(10,2), VARCHAR(15), and all constraint types
Smart Nulls Intelligently applies NULL values to optional fields while keeping critical data populated
Unique Constraints Guarantees uniqueness for columns with UNIQUE or PRIMARY KEY constraints
Check Constraints Honors CHECK constraints and enum types
Zero Configuration No YAML files, no mapping rules. Just point it at your database
Performance Written in Rust 🦀 for blazing-fast data generation

⚡ Quick Start

📥 Installation

# Via Cargo
cargo install synthdb

🎯 Basic Usage

Step 1: Create a target database with your schema (tables must exist)

Step 2: Run SynthDB

synthdb clone \
  --url "postgres://user:pass@localhost:5432/my_staging_db" \
  --rows 1000 \
  --output seed.sql

Step 3: Apply the generated data

psql -d my_staging_db -f seed.sql

🔧 Advanced Options

# Generate data directly to database (no SQL file)
synthdb clone --url "postgres://..." --rows 5000 --execute

# Specify custom row counts per table
synthdb clone --url "postgres://..." --config counts.json

# Exclude specific tables
synthdb clone --url "postgres://..." --exclude "logs,temp_*"

# Set data locale
synthdb clone --url "postgres://..." --locale "en_GB"

💡 Examples

🎨 How SynthDB Handles Data

🗂️ Real-World Schema Example

-- Your existing schema
CREATE TABLE companies (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    website VARCHAR(255),
    industry VARCHAR(50)
);

CREATE TABLE employees (
    id SERIAL PRIMARY KEY,
    company_id INTEGER REFERENCES companies(id),
    first_name VARCHAR(50) NOT NULL,
    last_name VARCHAR(50) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    phone VARCHAR(20),
    job_title VARCHAR(100),
    salary NUMERIC(10,2),
    hire_date DATE NOT NULL
);

SynthDB generates:

-- Coherent company data
INSERT INTO companies VALUES 
(1, 'TechVision Solutions', 'https://techvision.io', 'Software'),
(2, 'Global Logistics Inc', 'https://globallogistics.com', 'Transportation');

-- Employees with matching company context
INSERT INTO employees VALUES 
(1, 1, 'Alice', 'Chen', 'alice.chen@techvision.io', '+1-555-0123', 'Senior Software Engineer', 125000.00, '2022-03-15'),
(2, 1, 'Bob', 'Kumar', 'bob.kumar@techvision.io', '+1-555-0124', 'Product Manager', 135000.00, '2021-08-22'),
(3, 2, 'Carol', 'Rodriguez', 'carol.rodriguez@globallogistics.com', '+1-555-0198', 'Operations Director', 145000.00, '2020-01-10');

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     SynthDB Engine                      │
├─────────────────────────────────────────────────────────┤
│  1. Schema Introspection                                │
│     └─ Read tables, columns, constraints, relationships │
│                                                          │
│  2. Dependency Analysis                                 │
│     └─ Build dependency graph via topological sort      │
│                                                          │
│  3. Semantic Classification                             │
│     └─ Detect column meaning from names & types         │
│                                                          │
│  4. Context-Aware Generation                            │
│     └─ Generate coherent, relational data               │
│                                                          │
│  5. Constraint Validation                               │
│     └─ Ensure all DB constraints are satisfied          │
│                                                          │
│  6. Output                                              │
│     └─ SQL file or direct database insertion            │
└─────────────────────────────────────────────────────────┘

🗺️ Roadmap

  • PostgreSQL support
  • Semantic column detection
  • Foreign key resolution
  • MySQL/MariaDB support
  • SQLite support
  • Custom data providers
  • GraphQL schema support
  • Performance benchmarking suite
  • Web UI for configuration
  • Machine learning-based pattern detection

🤝 Contributing

We love Rustaceans! 🦀 Contributions are welcome and appreciated.

How to Contribute

  1. Fork the repository
  2. Create a feature branch 
    git checkout -b feature/amazing-feature
  3. Make your changes 
    cargo fmt
cargo clippy
cargo test
  4. Commit your changes 
    git commit -m 'Add amazing feature'
  5. Push to your fork 
    git push origin feature/amazing-feature
  6. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/yourusername/synthdb.git
cd synthdb

# Build the project
cargo build

# Run tests
cargo test

# Run with example
cargo run -- clone --url "postgres://localhost/testdb" --rows 100

Code of Conduct

Please read our Code of Conduct before contributing.

🙏 Acknowledgments

Built with ❤️ using:

  • Rust - Systems programming language
  • Tokio - Async runtime
  • SQLx - Database toolkit
  • Fake - Data generation library

📄 License

Distributed under the MIT License. See LICENSE for more information.

💬 Community & Support

If SynthDB helps your project, consider giving it a ⭐ on GitHub!

Made with 🦀 by the SynthDB team