Driftfile
A Driftfile declares one slice: what runs on it, and its shape. It names the Atomic Functions and Workers to deploy and the memory each one books, the Backbone databases, collections, buckets and queues and the size of each, the Canvas sites to publish, and through edge, what can reach the slice and what it can reach. Every booking sits beside what it books, and the slice-wide limits sit in one limits block inside slice, so the file is the whole of what the slice is and what it costs.
The file is written in HCL, the configuration language Terraform uses. A YAML Driftfile is refused: every command that reads one answers with
Driftfile is written in YAML, and the Driftfile is HCL now: this CLI reads no YAML Driftfile.
Rewrite it in HCL. `drift file new` writes a starter, and `drift file explain` lists every block it can holdYou run drift plan to see what applying the file would change and what it would cost, and drift apply from the project root to make the slice exactly what the file says. Applying creates the slice when it does not exist, resizes it to the file's shape when it does, and then deploys what runs on it. What a file leaves out is the smallest shape that runs what it names; see Anatomy.
The file
The file is named Driftfile: capital D, no extension, just like a Makefile or Dockerfile. It lives at the project root, next to your atomic/, backbone/, and canvas/ folders. The CLI looks for ./Driftfile where you run it. There is no second config file and no lockfile; several environments live in this one file as environment blocks, not a forest of per-environment variants.
-
my-project/the project root
-
atomic/your functions
- submit.go
- validator.go
-
backbone/seeds and schemas
- permit-types.jsonlupserted by
_id
- permit-types.jsonlupserted by
-
canvas/your sites
- public/mounted at /
- reviewer/mounted at /reviewer
- Driftfilethe manifest, at the root
-
atomic/your functions
The shape of the file
- AnatomyEvery block, the name rules, sizes and values.
- A worked exampleOne app with every section written out, sizes included.
Section by section
- AtomicBackends, Functions and Workers: handlers, memory bookings and schedules.
- BackboneCollections, databases, buckets, queues and secrets, each with its size.
- CanvasStatic sites, and the path each is served at.
- EdgeHostnames, the site gate, the rate limit, an address allowlist, egress and links.
-
DomainsCustom hostnames the slice answers on, as
domainblocks insideedge. - EnvironmentsOne file, several slices, varied through variables.
- Deploying and validatingLint it, format it, hook a build onto it, read its errors.
The smallest Driftfile
The minimum is the slice, how it is paid for, and one Function to run on it. drift file new writes exactly this, with comments that explain each part:
# new: a Drift project.
# `drift file explain` lists every block this file can hold, `drift file lint`
# checks it without deploying, and `drift plan` shows what applying it does and
# what that costs.
# The file does not say how the slice is paid for: a shape inside the free grant
# can be one of your free slices, and `drift plan` says which it is.
slice "new" {}
# The Atomic pillar: every backend the slice runs. A backend is one folder
# of one language's source: "default" is ./atomic itself, and any other name
# is ./atomic/<name>. Each function and worker is declared inside the backend its
# handler lives in; nothing in your source declares one.
atomic {
backend "default" {
# A function answers one call with one result. It is labelled with its method
# and route, or with QUEUE and the queue it drains: "QUEUE orders".
# Long-running processes are `worker` blocks beside it.
function "GET /hello" {
handler = "GetHello"
# The memory it books: its own pool, and what it is billed at.
# `drift size` rewrites it from what the slice measured.
memory = "32MiB"
}
}
}
# An environment is a slice of its own, <slice>-<name> unless it names one:
#
# environment "staging" {}
#
# `drift plan staging` and `drift apply staging` work on it.The slice is named after DRIFT_SLICE when it is set, or after the folder; --name chooses another, --canvas <dir> adds a site, and --force overwrites an existing Driftfile.
drift plan
drift plan compares the file with the live slice and prints every difference, what it costs, and what it removes. It changes nothing: the only request it makes that is not a read is the platform's price quote, which writes nothing. It takes the name of an environment, drift plan staging, to plan that environment's slice.
$ drift plan
slice ada/testnode ~ change
~ function POST /rpc memory 64MiB → 128MiB
- function GET /bench deployed code, triggers and history are deleted
sql chain unchanged
worker sequencer unchanged (digest 9f2c…)
Price €5.76 a month → €7.68 a month (quoted by the platform)
Restart yes: the slice restarts once, because its total booked memory changes (192MiB → 256MiB),
which means a few seconds of errors
Removes function GET /bench
Apply with: drift apply (asks for each of the above)
or: drift apply --approve-price 768 --approve-remove "function GET /bench"Each line starts with a mark:
| mark | means |
|---|---|
+ | added |
~ | changed |
- | removed |
| blank | unchanged |
! | cannot be applied as it is, for example secret STRIPE_KEY $STRIPE_KEY is not set here: apply would refuse |
A slice that does not exist yet is planned as + create, and its price line reads €x.xx a month (quoted by the platform), or free. With nothing to do, the plan prints Nothing to change. A plan says that only for a slice it read in full: if some fact it compares could not be read, the slice's header reads unchanged (not fully read) instead, and the plan ends on Nothing differs in what could be read. followed by one line for each fact it could not read, naming what it was read for and why, for example site /: sites could not be read (Couldn't list canvas sites: the platform is having trouble. ...). A line carrying a mark still wins: a plan that finds a difference reports it, and lists beside it whatever else it could not read.
A line's address is how a resource is named everywhere, in the plan and in the flags that answer it: function POST /rpc, function QUEUE orders, field sequencer, sql chain, nosql items, blobs uploads, queue txs, secret STRIPE_KEY, site /, site_auth alice, link billing, allow 203.0.113.0/24, host app.example.com, domain app.example.com, egress, limits.timeout, slots, databases, tier and label team. When a store is removed or shrunk, or limits.backup_retention shortens, the plan adds a Data line saying could be lost and naming what.
Some things are compared in their own way:
- A secret is write-only. One already on the slice is set again from its variable on apply, never compared.
- An API key is compared by the slice's fingerprint of it, its last four characters. An unchanged key is not rotated; a different one is planned as
rotates to the key in $NAME. - A booking that shrinks is a removal that apply asks about, and a store that shrinks is a possible data loss.
- A site the file does not name stays served: the plan prints
still served: no drift command removes a site yet. - A domain the file does not name stays attached. Apply adds what the file declares and reports the rest.
Plan files, for CI
drift plan --out plan.json also writes the plan down, for drift apply plan.json to apply exactly. See For CI below.
drift plan --exit-code reports the same verdict as an exit status, for a script that cannot read the plan's text: 0 for a match, 2 for create or a difference, 3 when a fact could not be read, 1 when the plan fails. Without the flag, a difference exits 0. Combined with --out, the file is written either way.
drift apply
drift apply prints the same plan, then asks before three things, each on its own:
- asked when
- the monthly figure moves, or a monthly slice is created
- answered without a terminal by
--approve-price <cents>, which must be the figure the plan quoted
- asked when
- code, a slot, a booking or a limit goes away
- answered without a terminal by
--approve-remove "<address>", once per resource
- asked when
- a database, collection, bucket or queue holding data is removed or shrunk, or backups are kept for less time
- answered without a terminal by
--allow-data-loss "<address>", once per resource
Agreeing to a removal is not agreeing to lose what it holds; each is asked. At a terminal a price and a removal are y/N questions, and a data loss is agreed to by typing the resource's address. Without a terminal, an unanswered question stops the apply before anything is sent, and the message lists the flags that answer it.
Then, in order:
- A
pre_deployhook runs first, so it can build what the file names. - Checks run before any route is called: the files and folders the Driftfile names exist, and every secret, API key and site password has its variable set.
- No slice yet: it is created with the file's shape. If the shape fits the free slice, apply asks
You have 1 of 3 free slices — make this the 2nd?(--use-free-sliceanswers it in a script) and creates it from the free preset; if you hold all your free slices it refuses and names them. A shape that does not fit is a priced slice, and--approve-priceagrees to the figuredrift planquotes. - The shape changed: the slice is resized. The figure you agreed to goes with the request, so if the price moved between the plan and the apply, the platform refuses and nothing changes; run
drift planagain. - What runs on it is deployed: Backbone, then Atomic and Canvas, then edge. A Function or Worker whose source and declaration are unchanged is skipped;
--forceredeploys every one. - API keys are set, but only where the slice holds none or a different one.
- A
post_deployhook runs once the slice is live. A failed one leaves the slice live and exits non-zero.
A file that would move an existing free slice to a priced shape is refused for now; drift slice resize makes that move.
Besides the three answers, drift apply takes --var KEY=value (repeatable) to set a variable env() reads, --secret as the same thing, and --no-env-file to skip the .env files. drift plan takes the same three.
For CI
Plan and apply in two steps. drift apply plan.json applies exactly the plan that was written, with the answers it recorded, and refuses if the Driftfile, the slice, or what the plan asks changed in between:
drift plan --out plan.json
drift apply plan.jsondrift size
drift file benchmark reports what each Function and Worker measured: the peak memory of an invocation, the high-water mark of a slot, and the size it should book. drift size writes those recommendations into the Driftfile's memory lines, keeping comments and layout, and shows the change as a diff. drift size --dry-run shows the diff without writing it. A Function nobody has called yet is left alone, because there is nothing to size it from.
The file is changed and nothing else. Run drift plan to see what the new bookings cost, and apply them like any other edit.