Skip to content

README.md

Latest commit

 

History

History
159 lines (123 loc) · 4.02 KB

README.md

File metadata and controls

159 lines (123 loc) · 4.02 KB

Fakestack Logo

Fakestack

Python wrapper for the high-performance Fakestack database generator.

Installation

pip install fakestack

Note: The package automatically downloads the appropriate binary for your platform on first run (~10-20MB) and checks for updates on subsequent runs. The binary is cached in ~/.cache/fakestack/bin/ (Linux/macOS) or %LOCALAPPDATA%\fakestack\bin\ (Windows).

Features

  • Zero Dependencies: No runtime dependencies, binary downloaded on first run
  • Tiny Package: <100KB package size (binary downloaded separately)
  • Auto-Updates: Checks for latest version on each run
  • 116+ Fake Data Generators: Built on gofakeit (financial, localization, products, animals, food, vehicles, books, and more)
  • Template Generator: Create custom data patterns (SKUs, IDs, codes) with modifiers
  • Interactive Schema Generator: Built-in generator with 10 pre-built templates
  • Multi-Database Support: SQLite, MySQL, PostgreSQL, MariaDB, MS SQL Server, CockroachDB
  • Fast: 10-50x faster than pure Python implementations
  • Cross-Platform: Works on Linux, macOS, Windows (x64 & ARM64)
  • Python 3.8+: Compatible with Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13

Quick Start

Command Line

# Generate schema interactively
python -m fakestack.runner -g .

# Download example schema
python -m fakestack.runner -d .

# Create database and populate with fake data
python -m fakestack.runner -c -p -f schema.json

Or use the installed command:

fakestack -g .              # Interactive schema generator
fakestack -d .              # Download example
fakestack -c -p -f schema.json

Python API

from fakestack import fakestack

# Download schema
fakestack(['-d', '.'])

# Create and populate database
fakestack(['-c', '-p', '-f', 'schema.json'])

Schema Example

{
  "database": {
    "db_type": "sqlite",
    "db_name": "test.db"
  },
  "tables": [
    {
      "name": "users",
      "count": 50,
      "columns": [
        {"name": "id", "type": "INTEGER PRIMARY KEY AUTOINCREMENT"},
        {"name": "name", "type": "TEXT", "fake": "name"},
        {"name": "email", "type": "TEXT", "fake": "email"},
        {"name": "phone", "type": "TEXT", "fake": "phoneformatted"},
        {"name": "address", "type": "TEXT", "fake": "address"},
        {"name": "created_at", "type": "TEXT", "fake": "date"}
      ]
    }
  ]
}

Available Options

  • -g <file> - Generate schema interactively (use '.' for default filename)
  • -d <path> - Download example schema
  • -c - Create database tables
  • -p - Populate tables with fake data
  • -f <file> - Schema file path

Available Fake Data Types

See golang/README.md for complete list of 116+ fake data generators across 12 categories:

  • Personal Data & Identifiers
  • Financial & Payment
  • Address & Location
  • Company & Job
  • Internet & Technology
  • Dates & Times
  • Products & E-commerce
  • Files & Media
  • Books & Entertainment
  • Animals & Nature
  • Food & Drink
  • Vehicles & Transportation

Development

Setup

cd python
pip install -e ".[dev]"

Run Tests

pytest tests/ -v

Code Quality

black fakestack/
isort fakestack/
flake8 fakestack/

How It Works

This package bundles pre-compiled Go binaries for all major platforms. When you run fakestack, the Python wrapper:

  1. Detects your OS and architecture
  2. Selects the appropriate binary from fakestack/bin/
  3. Executes it with your arguments
  4. Returns the exit code

This approach provides:

  • ✅ Zero runtime dependencies
  • ✅ Native performance
  • ✅ Easy installation
  • ✅ Cross-platform compatibility

License

MIT - See LICENSE file in root directory

Links