skogi 0.3.0

Thin API-contract CLI for syn-data-gen — generate synthetic data and seed it into a live database

skogi

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

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. 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.

New here? Read docs/usage.md to run it, docs/architecture.md for the design, and 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.

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 for the live tracker and docs/ROADMAP.md for the plan (issue #17 has the full rationale).

Setup

This project uses uv.

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

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:

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

# 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 for the full guide — every flag, the conflict/create-table modes, dry-run, the teardown round-trip, and a GitHub Actions CI recipe.