Coming from another tool

For a team whose database another migration tool manages today: the concepts mapped, then the database adopted with init --from.

Works

• Each concept of a numbered-files migration tool mapped to its SQL Yodeler counterpart
• The database adopted as it is, with the old tool's history table left out
• Rollback with yodel revert, planned from the recorded schema, behind the same approval
• A migration that fails part way resumes where it stopped; one out of order is refused

Differs

By database

ClickHouse

• A project owns ClickHouse databases (yodel create <dir> --clickhouse --database <name>).
• A rebuild keeps the old table until yodel cleanup drops it, and lint flags mutations and rebuilds (ch-mutation, ch-rebuild).

Postgres

• 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

GitHub

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

GitLab

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

Forgejo

• Secrets belong to the repository, with no environments, so limit who can push branches.
• Jobs need a runner with the docker label, and a job gets no OIDC token for cloud roles.

First step

YODEL_CREDENTIALS=writer npx yodel init --from <env> --force

Coming from another migration tool

Proof

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
adopt	yodel init --from adopts a live database without touching it, and yodel plan then shows no change; on Postgres its policies, row-level security and grants too, on ClickHouse its dictionaries, functions, roles, users, row policies and grants; yodel init --baseline records the baseline, behind the gate, in a second environment that holds the same schema, and refuses one that differs	ClickHouse: pass, caughtPostgres: pass, caught
resume	an interrupted apply resumes where it stopped: a backfill step written as yodel's form (table, key, batch size, SQL) from its receipts, running each batch once, and a failed statement at that statement, never resending one that ran	ClickHouse: pass, caughtPostgres: pass, caught
out-of-order	a migration merged late, before one already applied, is refused unless --allow-out-of-order, and never skipped	ClickHouse: pass, caughtPostgres: pass, caught

Then read

Tasks

Coming from another migration toolCutting CI overSetting up each forge

Background

MigrationsData migrations

Reference

The commandsGlossary