Anatomy
A Driftfile declares one slice: what runs on it and its shape. It is a list of blocks, each with a type, labels in quotes and a body in braces, and attributes written name = value. A block's label is its name, and the plan prints every resource by it: function POST /rpc, sql chain. Comments start with #.
Only slice is required. Every other block is optional and independent. Each pillar's blocks are written inside one container block of that pillar: atomic holds the backends, backbone the stores, secrets and cache, and canvas the sites; a pillar block written at the top of the file is refused, naming the container it belongs in. A static site needs only slice and a canvas with a site; a data pipeline needs only slice, its atomic Functions and its backbone stores. Every Function, Worker, database, collection and bucket states the size it books, and the slice-wide limits sit in one limits block inside slice, so the file is the whole of what the slice costs.
slice "shop" { # required: the slice this file declares
labels = { team = "backend" } # optional: your own key-value pairs
limits { # optional: the slice-wide part of the shape
timeout = "30s"
log_retention = "24h"
}
}
variable "rpc_memory" { # optional: a value an environment can change
default = "64MiB"
}
environment "staging" { # optional: another slice from the same file
vars = { rpc_memory = "32MiB" }
}
atomic { # everything that runs: its backends
backend "default" { # the Functions and Workers in ./atomic
function "POST /items" {
handler = "PostItems"
memory = var.rpc_memory # required: what it books
response = "json"
secrets = ["STRIPE_KEY"]
env = { LOG_LEVEL = "debug" }
auth {
api_key = env("ITEMS_KEY")
}
}
function "QUEUE validate" { # drains the queue "validate"
handler = "QueueValidate"
memory = "32MiB"
}
function "GET /report" {
handler = "GetReport"
memory = "32MiB"
cron = "0 3 * * *"
}
}
backend "billing" { # the Workers and Functions in ./atomic/billing
worker "ledger" {
handler = "Ledger"
memory = "32MiB"
}
}
}
backbone { # everything the slice stores
sql "app" { # a database
size = "128MiB" # required
schema = "backbone/schema.sql"
}
nosql "items" { # a collection
size = "64MiB" # required
seed = "backbone/items.jsonl"
ttl = "30d"
unique = ["sku"]
}
blobs "uploads" { # a bucket
size = "256MiB" # required
}
queue "validate" {}
cache "banner" {
value = "hello"
ttl = 3600
}
secret "STRIPE_KEY" {
value = env("STRIPE_KEY") # always a reference
}
}
canvas { # every static site the slice serves
site "/" { # served at this path
dir = "site"
}
}
edge { # what reaches the slice, and what it reaches
rate_limit = "600/min"
links = ["billing"]
allow = ["203.0.113.0/24"]
hosts = { "app.example.com" = "frontend" }
egress {
mode = "allowlist"
hosts = ["api.stripe.com"]
}
domain "app.example.com" {
wildcard = true
}
site_auth {
realm = "Staging"
paths = ["*"]
user "alice" {
password = env("ALICE_PASS")
}
}
}
hook "pre_deploy" { # a local command, before anything ships
run = "npm run build"
}
test "e2e" { # a command for drift file test
run = "npx playwright test"
}drift file explain prints this same map from the CLI itself: drift file explain lists the blocks, drift file explain atomic.backend.function describes one, drift file explain atomic.backend.function.memory one attribute, and --recursive everything under the path. drift file resolve prints what one file compiles to.
The blocks
- label
- the slice's name
- what it declares
labels, and onelimitsblock
- label
- none
- what it declares
- the
backendblocks. At most one
- label
- the folder
- what it declares
- inside
atomic:dir, and itsfunctionandworkerblocks
- label
- method and route, or
QUEUE name - what it declares
- inside a
backend:handlerandmemory(both required),response,concurrent,stream,cron,env,secrets,dir, and anauthblock
- label
- the Worker's name
- what it declares
- inside a
backend:handlerandmemory(both required),env,secrets,dir
- label
- none
- what it declares
- the stores, secrets and cache below. At most one
- label
- the database
- what it declares
- inside
backbone:size(required),schema,migrations,seed
- label
- the collection
- what it declares
- inside
backbone:size(required),seed,ttl,unique
- label
- the bucket
- what it declares
- inside
backbone:size(required)
- label
- the queue
- what it declares
- inside
backbone:depth
- label
- the cache key
- what it declares
- inside
backbone:fileorvalue, andttl
- label
- an environment-variable-style name
- what it declares
- inside
backbone:value = env("NAME")(required)
- label
- none
- what it declares
- inside
backbone:client_channels
- label
- none
- what it declares
- the
siteblocks. At most one
- label
- the path it is served at
- what it declares
- inside
canvas:dir(required)
- label
- none
- what it declares
rate_limit,links,allow,hosts, and the blocksegress,domain "host"andsite_auth
- label
- the variable
- what it declares
default
- label
- the environment
- what it declares
slice,vars
- label
- when it runs,
pre_deployorpost_deploy - what it declares
run(required)
- label
- the test
- what it declares
run(required)
Each section has a page of its own: Atomic for backends, Functions and Workers, Backbone for the stores, secrets and cache, Canvas for sites, Edge and Domains for what reaches the slice, and Environments for variable and environment.
The slice
The slice block names the slice the file declares, and says how it is paid for. drift apply creates the slice when it does not exist and resizes it to the file's shape when it does.
- type
- string
- meaning
- Required. 1 to 32 lowercase letters, digits and hyphens, with a hyphen only in the interior. With
environmentblocks,prodandproductionapply to this bare name and every other environment toslice-environment.
- type
- map of string
- meaning
- Your own key-value pairs, see below.
- type
- block
- meaning
- At most one. The slice-wide part of the shape.
A file with no slice block is refused, and so is one with two: a file declares one slice.
Labels
Your own key-value pairs, for telling your slices apart: team = "backend", env = "staging", client = "bakkerij & zn.". drift slice list shows them, a snapshot carries them, and a restore puts them back, so they survive a download-and-restore round trip like the rest of your data. They are written as labels inside slice:
slice "demo" {
labels = {
client = "bakkerij & zn."
"cost.center" = "42"
}
}The Driftfile owns them. Add one to the file and it appears on the slice; change one and it changes; remove one and it is removed. A file with no labels declares none, so applying it clears any the slice is carrying. The plan lists each change as a label line, such as label team. A label has no price and destroys nothing, so the plan reports a label change but never asks about it.
- type
- map of string
- meaning
- Up to 32 entries. Keys are 1 to 63 characters, start with a letter or digit, and may carry
. _ / -after that; a key with a dot or slash is written in quotes. Values are free text up to 256 bytes.
Label keys do not follow the name rules below, and values follow nothing at all. They are free text and never reach the platform's internals, so client = "bakkerij & zn." is a perfectly good value: spaces, punctuation and accents included. Nothing is lower-cased, truncated or rewritten on the way in.
The limits block
limits is the slice-wide part of the shape: everything the slice has that no single block in the file owns. A limit left out is the platform's figure for it (see what a file leaves out).
- written as
- number
- meaning
- Requests a minute across the whole slice; more is answered 429. The same limit as
edge.rate_limit: write it in one of the two places.
- written as
- duration
- meaning
- Wall-clock time an invocation may run before it is killed.
- written as
- duration, whole hours
- meaning
- How long invocation logs are kept.
- written as
- number
- meaning
- Past deploys kept per slot, for
drift atomic rollback.
- written as
- duration, whole days
- meaning
- How long Backbone backups are kept.
- written as
- number
- meaning
- Scheduled jobs the slice may run. Left out, it is the number of Functions with a
cron.
- written as
- size
- meaning
- Disk across every deployed slot: its code and vendored dependencies, plus the source archive stored for it.
- written as
- size
- meaning
- Storage across every site the slice serves.
- written as
- number
- meaning
- Live Realtime connections held at once; 0 turns Realtime off.
- written as
- number
- meaning
- Secrets the slice may hold.
- written as
- size
- meaning
- Largest value one secret may hold.
- written as
- number
- meaning
- Backbone locks held at once.
- written as
- size
- meaning
- Largest single object a bucket accepts.
- written as
- number
- meaning
- Messages a queue holds when its own block states no depth.
- written as
- size
- meaning
- Largest value one Deed Vault entry may hold.
- written as
- number
- meaning
- Deed Vault entries one identity may hold.
- written as
- size
- meaning
- Largest record a Deed Pocket accepts.
The platform refuses a limit above its maximum for one slice. Function slots (Functions and Workers together) top out at 64 and timeout at 300 seconds, which are the figures the platform already enforces elsewhere. The rest are guard rails against a runaway value, not measured capacity: 20 for deploy_history, 720 hours for log_retention, 30 days for backup_retention, 60,000 for requests_per_minute, 1,000 for secrets and for vault_entries, 64 KiB for secret_size, 10 MiB for blob_object_size, 100,000 for queue_depth and for locks, and 1 MiB for vault_entry_size and pocket_record_size. drift file lint does not check them; the platform refuses the slice at apply.
Names
One identifier shape covers almost everything you name: the slice, every backend, collection, bucket and queue. 1 to 32 characters, lowercase letters and digits, hyphens allowed in the interior only. No underscores, no uppercase, no leading or trailing hyphen.
# pattern: ^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$
permit-types # fine
audit-log-2 # fine
Permit_Types # rejected: uppercase and underscore
-uploads # rejected: leading hyphenThe few that differ:
| name | rule |
|---|---|
| a Function's route | The part after the method and the slash: 1 to 63 characters of lowercase letters, digits and / : _ -, starting with a letter or digit. GET /status/:token is fine, GET /Items is not. |
the queue in QUEUE name | The same shape as any queue name. |
| a Worker's name | 1 to 63 characters, lowercase letters, digits and hyphens, starting with a letter. |
| a SQL database | 1 to 64 characters, and underscores are allowed in the interior. See Backbone. |
| a secret | Named like an environment variable: STRIPE_KEY. |
| an environment | The slice it applies to must be a valid slice name, so slice-environment is at most 32 characters. |
| a label key | See Labels. |
A name that breaks its rule is reported at its line, together with every other error in the file:
Driftfile
4 validation errors:
- Driftfile:1:7: Invalid slice: slice "Bad_Name": slice: 'Bad_Name' does not match pattern '^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$'
- Driftfile:6:9: Invalid function: function "GET /Items": route: 'Items' does not match pattern '^[a-z0-9][a-z0-9/:_-]{0,62}$'
- Driftfile:10:9: Invalid worker: worker "Seq_1": name: 'Seq_1' does not match pattern '^[a-z][a-z0-9-]{0,62}$'
- Driftfile:16:7: Invalid nosql: nosql "my_items": slot: 'my_items' does not match pattern '^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$'Sizes and durations
Sizes are whole KiB, MiB or GiB, written as a string: "64MiB". "64MB" is refused rather than guessed at, so a size means one number whoever reads it. A Function books from 8MiB to 256MiB, in whole MiB, and 16MiB or more in a compiled language. A Worker books 16MiB or more, because it runs Go. A storage size is more than zero: the platform reads zero as unbounded and refuses it.
Durations are whole seconds, minutes, hours or days: "30s", "5m", "24h", "7d". log_retention is kept in whole hours and backup_retention in whole days, so "90m" is refused for the first and "36h" for the second. A nosql block's ttl is a duration too; a cache block's ttl is a number of seconds.
What a file leaves out
Every booking and every storage size is written. A Function, a Worker, a database, a collection and a bucket each state theirs: it is what they are billed at, so it has no default, and a file that leaves one out is refused with a message naming the block.
What a file leaves out is the smallest shape that runs what it names.
- The slot count is the number of Functions and Workers, and the database count is the number of
sqlblocks. scheduled_jobsis the number of Functions with acron. Writing fewer is refused.- A queue with no
depthtakes the slice'squeue_depth. - Every other limit left out is the platform's figure for it.
- A shape that fits the free slice can be one of your free slices, and what it leaves out is the free slice's own figure. A shape that does not fit is priced, and
drift plansays which limit took it out of the free slice. The file never says how the slice is paid for: abillingline is refused, and deleting it is the whole change.
drift file resolve prints every booking, size and limit a file compiles to, and drift plan adds what it costs.
Values
A value is a literal, var.name, or one of three functions:
| function | gives |
|---|---|
env("NAME") | an environment variable: from the terminal, then --var NAME=value, then the .env.environment file beside the Driftfile, then .env, in that order. --no-env-file skips the files. |
file("path") | a file's text, relative to the Driftfile |
sha256("text") | the hex SHA-256 of a string |
There are no others, and no count, for_each or modules.
A secret is always a reference
secret's value, an API key and a site password must each be written env("NAME"). A literal there would be a credential committed with the file, so it is refused, and so are var.x and file(). The refusal never prints the value.For example, this is refused at the line of the literal:
- Driftfile:20:11: A secret is a reference: secret "STRIPE_KEY": value is write-only and must be written env("NAME"): a literal here would be a credential committed with this file