CI/CD
Checks on every pull request, gated deploys, no stored secrets.
On every pull request
trek plan check -C db
Needs no database. Fails on plan problems, missing folders or reverts, lint errors, and variables missing in any environment.
On merge and release
trek deploy -C db -e test --json
trek deploy -C db -e prod --yes --json # --yes: protected environment, no prompt in CI
trek verify -C db -e prod
Two pipelines cannot interleave: the second waits for the deploy lock. Use --script review.sql to attach the exact SQL to an approval step, then deploy after approval.
Build once, deploy the same bundle everywhere
trek bundle create -C db -o db-bundle.zip # build stage: publish as an artifact
trek --bundle db-bundle.zip deploy -e test --json # each release stage
trek --bundle db-bundle.zip deploy -e prod --yes --json
A bundle freezes the plan and scripts at build time, and every stage checks its hashes before running anything, so production gets exactly what test got.
Identity without secrets
| Runner | Use |
|---|---|
| GitHub Actions | azure/login with OIDC, then entraAzureCli; or entraWorkloadIdentity |
| Azure Pipelines | entraAzurePipelines with a workload-identity service connection, or entraAzureCli inside an AzureCLI task |
| Azure-hosted agents, VMs, Container Apps | entraManagedIdentity |
| Anything else | entraServicePrincipalCertificate or entraEnvironment with secrets from your secret store |
Complete GitHub Actions and Azure Pipelines files are on the Examples page.
Pin the tool version
dotnet tool install --global Badger.Trek --version 0.6.0
Containers
DockerfileFROM mcr.microsoft.com/dotnet/runtime-deps:10.0
ADD https://lonebadgerdownloads.blob.core.windows.net/badger-trek/v0.6.0/badger-trek-0.6.0-linux-x64.tar.gz /tmp/trek.tgz
RUN tar -xzf /tmp/trek.tgz -C /usr/local/bin trek && rm /tmp/trek.tgz
COPY db /db
ENTRYPOINT ["trek", "-C", "/db"]
Is this database up to date?
trek status -C db -e prod --exit-code # exit code 3 when changes are pending or history differs
trek status -C db -e prod --json # upToDate, certified, databaseHead, planHead, changes
An application can make the same check at start-up without trek. Record the plan head when you build (planHead in the output of trek plan check --json, which needs no database), and compare it with the chain id of the last change the database has:
-- SQL Server
SELECT TOP (1) chain_id FROM trek.changes ORDER BY sequence DESC;
-- PostgreSQL
SELECT chain_id FROM trek.changes ORDER BY sequence DESC LIMIT 1;
-- SQLite
SELECT chain_id FROM trek_changes ORDER BY sequence DESC LIMIT 1;
Equal chain ids mean the database has exactly the build's changes, in order. sequence and chain_id are part of the documented journal: a change to its layout raises state_version in the meta table.
Fast test databases
Deploying for every test is slower than it needs to be (most of it is starting the process). Deploy once into a template database per test run, then copy the template for each test:
| Database | Copy the template |
|---|---|
| SQL Server | BACKUP DATABASE app_template TO DISK = '...' once, then RESTORE DATABASE app_test_1 FROM DISK = '...' WITH MOVE ... per test (about half a second for a small schema) |
| PostgreSQL | CREATE DATABASE app_test_1 TEMPLATE app_template |
| SQLite | Copy the file |
A copy keeps the journal, so trek status and trek verify work on it like on the template. Run trek deploy against the template whenever the plan head changes.
Applications that migrate themselves
The engine is also a .NET library; see Library and providers.