📖 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:

• Name: "Sarah Martinez"
• Email: "sarah.martinez@company.com"
• Username: "smartinez"

🏷️ Smart Categorization

Automatically detects and generates valid data across multiple domains:

🔗 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

⚡ 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

• Issues: GitHub Issues
• Discussions: GitHub Discussions