Deploying and validating
The loop around a Driftfile: check it offline, fold your build into the deploy, then apply it and read whatever it says back.
Working on a Driftfile
drift file answers questions about a manifest without touching the network. It's the fast loop: fix, lint, repeat, and only then deploy.
| Command | What it answers |
|---|---|
drift file lint | Is this file valid? Validates exactly as a deploy would, and exits non-zero, so it can gate CI. |
drift file explain --env staging | What does staging resolve to once the overlay and the inherited defaults are applied? |
drift file fmt --write | Canonical key order and indentation. Comments and short forms survive. |
drift file new | A starter Driftfile in this directory. |
explain prints names of secrets, never values, because some are resolved $ENVREFs by that point, and a command whose job is to print the resolved shape must not put a live credential on a terminal or into a CI log. It prints no price either: cost comes from the server, via drift project deploy --plan.
Hooks: pre/post-deploy commands
Fold the build-and-verify ceremony into the deploy so it stays one command. Commands run locally, in order, through the shell from the project root, with the deploy environment exported; a non-zero exit aborts.
hooks:
pre_deploy: # before anything ships, typically a build
- npm --prefix web run build
post_deploy: # after the slice is live, typically a smoke test
- ./scripts/smoke.shHooks are lifecycle commands, not a pipeline engine: no test stages, matrices, parallelism, or remote execution. A failed post_deploy leaves the slice live but exits non-zero so you and CI see it.
Deploy & validation
The CLI validates the whole Driftfile before any network call. Bad sizes, missing seed files, malformed JSONL, and unset secret references are reported together, so you fix everything in one pass. On a valid file, drift project deploy shows the diff, tells you whether the slice is free or its monthly cost, and asks to apply.
drift project deploy --plan is the same diff and the same cost with nothing applied and no hooks run. It is the way to see what a deploy would do before letting it.
Reading an error
Errors are keyed by location within the document, not by line number. The file is converted to JSON before validation, which is the honest conversion but discards the YAML source positions, so what you get is a path:
at '/environments/staging': additional properties 'name' not allowed
at '/backbone/nosql/1': missing property 'size'Read /backbone/nosql/1 as “the second entry of nosql”. Seed files are the one exception and do carry a file and line, because a JSONL seed is validated line by line: nosql "permit-types" seed: ./backbone/permit-types.jsonl:4: missing _id.
The platform owns the format, so validation needs a copy of it.
~/.drift/driftfile.schema.json. On a machine that has never run an online command there is nothing to validate against, and the CLI says so rather than passing a file it hasn't checked. Run drift account login or drift slice list once. It also means a field the platform adds is accepted as soon as the cached schema refreshes, with no CLI release.Deploys only create or grow a slice.
drift project deploy never shrinks one. To lower a limit or drop a resource, edit the Driftfile downward and run drift slice resize --from Driftfile --allow-destructive. The flag is required for any non-zero shrink, and it lives on the command line so that destructive intent is visible on the terminal that ran it rather than buried in a manifest.Ready to ship one?