Metadata-Version: 2.4
Name: skogi
Version: 0.3.0
Summary: Thin API-contract CLI for syn-data-gen — generate synthetic data and seed it into a live database
Keywords: synthetic-data,test-data,database,postgres,seed,cli,fixtures
Author: Yashmeet Singh
Author-email: Yashmeet Singh <yashmeet.singh@outlook.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Testing
Requires-Dist: httpx>=0.28
Requires-Dist: psycopg[binary]>=3.2.0
Requires-Dist: pydantic>=2.13.4
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/ysk125103/skogi-cli
Project-URL: Repository, https://github.com/ysk125103/skogi-cli
Project-URL: Issues, https://github.com/ysk125103/skogi-cli/issues
Project-URL: Documentation, https://github.com/ysk125103/skogi-cli/blob/main/docs/usage.md
Description-Content-Type: text/markdown

# skogi

[![tests](https://github.com/ysk125103/skogi-cli/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ysk125103/skogi-cli/actions/workflows/test.yml)

A small, standalone CLI that takes you from a `CREATE TABLE` script to a database full of realistic
fake data — in one command:

```bash
skogi run --ddl schema.sql --dsn postgresql://user@localhost:5432/dbname
```

Under that are the two halves it orchestrates, usable on their own:

- **`skogi generate`** — asks the Skogi service for a dataset and writes the two files below. It
  authenticates with a personal access token and **never embeds the generation engine**, which stays
  server-side.
- **`skogi seed`** — materializes those files into a real database: create the tables from the DDL
  (or skip the ones that exist), then insert the rows, transactionally, with an undo.

```
                    ┌──────────────────┐
  schema.sql (DDL) ─┤ skogi generate   ├─▶ schema.sql + data.sql + skogi.run.json
  or a Template     └──────────────────┘                 │
                                                          ▼
                                                   skogi seed  ──▶  live database
                    └──────────────  skogi run  ──────────────┘
```

`seed` is **fully offline** — it talks to your database and nothing else, no token required — and it
consumes any DDL + `data.sql` pair, including one produced directly by
[`syn-data-gen`](https://github.com/ysk125103/syn-data-gen). It never imports the generator's Python;
the only coupling is that **emitted-file contract**.

**Targets.** MVP is **PostgreSQL only** (the generated SQL is ANSI/Postgres, so it executes
directly). The roadmap adds **MySQL → SQLite**, with **Oracle** later — see
[docs/ROADMAP.md](docs/ROADMAP.md).

New here? Read **[docs/usage.md](docs/usage.md)** to run it, **[docs/architecture.md](docs/architecture.md)**
for the design, and **[CLAUDE.md](CLAUDE.md)** for contributor/agent guidance. For the product as a
user sees it — website + CLI, no internal terminology — see
**[docs/end-user-guide.md](docs/end-user-guide.md)**.

## Status

**All three verbs exist.** Seed Phase 1 (the PostgreSQL MVP) is complete, and the Generate track has
shipped end to end: **G0** (the `skogi` rename + subcommand split), **G1** (`skogi generate` against
the control plane) and **G2** (`skogi run`, `generate --template-id`, `seed --run-dir`, and the
`--confirm-target` guardrail on destructive work aimed off this machine).

Next up is close-out — distribution, licensing, contract versioning — plus the Seed track's dialect
phases (**MySQL → SQLite → Oracle**). See **[docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)** for the
live tracker and **[docs/ROADMAP.md](docs/ROADMAP.md)** for the plan (issue **#17** has the full
rationale).

## Setup

This project uses [uv](https://docs.astral.sh/uv/).

```bash
uv sync                 # create the env from the lockfile
uv run pytest           # run tests
uv run ruff check .     # lint
```

## Usage

One command, generate + load (needs `$SKOGI_TOKEN`, minted in the web app under
**Settings → CLI tokens**):

```bash
uv run skogi run \
  --ddl examples/retail.sql \
  --dsn postgresql://user@localhost:5432/dbname
```

Or the two halves separately — `seed` can take both inputs straight from a `generate` run directory:

```bash
uv run skogi generate --ddl examples/retail.sql --out ./out
uv run skogi seed --run-dir ./out --dsn postgresql://user@localhost:5432/dbname
```

**Secrets come from the environment, never a flag** — `SKOGI_TOKEN` for `generate`, and
`PGPASSWORD`/`DB_PASSWORD` for `seed`. Copy `.env.example` to `.env` and fill it in.

**Teardown** (restore the DB to the state the loader found it in):

```bash
# load, recording provenance
uv run skogi seed --ddl examples/retail.sql --data out/data.sql \
  --dsn postgresql://user@localhost:5432/dbname --record run.json

# later: undo exactly that run
uv run skogi seed --teardown --record run.json \
  --dsn postgresql://user@localhost:5432/dbname
```

Destructive work (`--on-conflict truncate`, `--teardown`) against a database that is **not on this
machine** is refused until you name it with `--confirm-target <dbname>` — `--yes` is not enough,
because a confirmation that transfers between targets does not guard against picking the wrong one.

See **[docs/usage.md](docs/usage.md)** for the full guide — every flag, the conflict/create-table
modes, dry-run, the teardown round-trip, and a GitHub Actions CI recipe.
