Start a new schema
llms.txtlists every page for an agent
For a team starting a schema from nothing: declare it in TypeScript in a project from a starter template, and yodel writes the first migration from it on a local database.
Works
- A project with a profile, a migrate Op and a drift watch per environment, and pipelines for GitHub, GitLab and Forgejo
- The first migration written from
src/schema.ts, planned, approved and applied on chant's local emulator - Lint, the replay check and a plan comment on every pull request
Differs
By database
- A project owns ClickHouse databases (
yodel create <dir> --clickhouse --database <name>). - A rebuild keeps the old table until
yodel cleanupdrops it, and lint flags mutations and rebuilds (ch-mutation,ch-rebuild).
- A project owns Postgres schemas (
yodel create <dir> --postgres --schema <name>). - Roles stay the environment's: the schema declares the policies and grants that name them.
By forge
- The writer's secrets are secrets of a GitHub environment limited to
main. - The plan comment and the drift issue use the job's own token.
- The writer's variables are protected and scoped to the environment; the readers' are not protected.
- The plan comment and the drift issue need
GITLAB_TOKEN, and each drift watch runs from a pipeline schedule you create.
- Secrets belong to the repository, with no environments, so limit who can push branches.
- Jobs need a runner with the
dockerlabel, and a job gets no OIDC token for cloud roles.
First step
npx @intentius/sql-yodeler@latest create my-schema --clickhouse --database eventsnpx @intentius/sql-yodeler@latest create my-schema --postgres --schema appProof
Each claim runs what this room relies on against a real server, once plain (it passes) and once with the behaviour broken (the claim catches it). Claims status lists every claim.
| Claim | What it says | Plain, broken |
|---|---|---|
new | yodel new writes the next migration offline, with no dev database, and it applies; on Postgres, functions, procedures and triggers too, which lint checks | ClickHouse: pass, caughtPostgres: pass, caught |
lint | yodel lint --replay replays the migrations into a fresh database and each gives the schema it recorded; offline, yodel lint fails a migrations directory with a fork (exit 3), naming both migrations; a checkpoint replays alone to its recorded schema, and a fresh environment starts from it; yodel revert undoes the newest migration behind the gate, with a hand-written step for its data step, back to its parent's recorded schema, and refuses a checkpoint or a migration before one; yodel test runs a project's tests on databases replayed from the migrations, a seed meeting the backfill after it, fails a case whose assertion does not hold, and refuses an environment with a history; on Postgres, a unique index over rows with duplicates is refused before the gate by its generated pre-check (exit 4, naming the statement and the count), and yodel lint flags it as data-dependent | ClickHouse: pass, caughtPostgres: pass, caught |
approval | a pending migration applies only after chant approve of its plan digest, and the history records that digest; a failing pre-migration check refuses it, and so does a policy rule, read at the base commit, unless an override is recorded for that digest, for a yodel revert as for an apply; the audit log derived from the history and the ledger accounts for every approval and apply, and names one removed; a reader and a writer that are one user are refused, and the reader, its password a minted token, cannot write; an approval is refused once the migration changed after it, and nothing is applied | ClickHouse: pass, caughtPostgres: pass, caught |
drift | yodel drift reports a declared object changed out of band, naming the property, and one dropped; on the versioned path it compares with the newest applied migration's recorded schema, so a pending migration is not drift | ClickHouse: pass, caughtPostgres: pass, caught |
