katcha 0.1.0

Schema-aware seed-data orchestrator

Katcha

A database schema-aware fake data seeding tool. Katcha inspects your database schema, understands foreign key relationships, and generates realistic test data in the correct order.

Features

• Schema-aware seeding: Automatically detects foreign key relationships and seeds tables in topological order
• Smart data generation: Uses column names and types to generate contextually appropriate fake data (emails, names, addresses, etc.)
• Configuration-driven: Control how many rows to seed per table via a simple YAML config
• Constraint handling: Respects unique constraints, composite primary keys, and nullable columns
• Self-referential support: Handles tables with self-referential foreign keys (e.g., parent-child relationships)

Installation

pip install katcha

Quick Start

1. Initialize configuration

Point katcha at your database to generate a configuration file:

katcha init postgresql://user:pass@localhost/mydb

This creates a katcha.yml file:

version: 1

database:
  engine: postgresql
  host: user:pass@localhost/mydb

schema:
  users: 10
  posts: 10
  comments: 10

2. Customize row counts

Edit katcha.yml to set how many rows you want per table:

schema:
  users: 50
  posts: 200
  comments: 500

3. Seed your database

katcha seed

Katcha will insert fake data in the correct order, respecting all foreign key relationships.

Commands

katcha init <database_url>

Initialize a new katcha configuration by inspecting a database schema.

Arguments:

• database_url: Database connection URL (e.g., postgresql://user:pass@host/db, sqlite:///test.db)

Options:

• -o, --output: Output file path (default: katcha.yml)
• -r, --rows: Default number of rows per table (default: 10)

katcha build

Re-inspect the database schema and update configuration with new tables.

Options:

• -c, --config: Path to config file (default: katcha.yml)
• -r, --rows: Default rows for new tables (default: 10)

katcha seed

Seed the database with fake data based on configuration.

Options:

• -c, --config: Path to config file (default: katcha.yml)

Supported Databases

Katcha works with any database supported by SQLAlchemy:

• PostgreSQL
• MySQL / MariaDB
• SQLite
• Microsoft SQL Server
• Oracle

Smart Data Generation

Katcha generates contextually appropriate data based on column names:

Column Pattern	Generated Data
email	Realistic email addresses
first_name, last_name	Human names
phone, mobile	Phone numbers
address, city, state	Location data
url, website	URLs
created_at, updated_at	Timestamps
price, cost, amount	Monetary values
description	Paragraphs of text
uuid, guid	UUIDs
password, hash	SHA256 hashes

For columns without name matches, data is generated based on SQL type.

Requirements

• Python 3.11+
• Database driver for your database (e.g., psycopg2 for PostgreSQL)

License

MIT License - see LICENSE for details.