katcha 0.1.0
Schema-aware seed-data orchestrator
Requires Python: >=3.11
Keywords: cli, data-generation, database, faker, seeding, sqlalchemy, testing

# 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

```bash
pip install katcha
```

## Quick Start

### 1. Initialize configuration

Point katcha at your database to generate a configuration file:

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

This creates a `katcha.yml` file:

```yaml
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:

```yaml
schema:
  users: 50
  posts: 200
  comments: 500
```

### 3. Seed your database

```bash
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](LICENSE) for details.