drift Docs
Pages
drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Moving off Azure
Estimate, snapshot and transform a resource group.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

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.

Driftfile
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

labelwhat it declares
  • slice "name"
    label
    the slice's name
    what it declares
    labels, and one limits block
  • atomic
    label
    none
    what it declares
    the backend blocks. At most one
  • backend "name"
    label
    the folder
    what it declares
    inside atomic: dir, and its function and worker blocks
  • function "POST /rpc"
    label
    method and route, or QUEUE name
    what it declares
    inside a backend: handler and memory (both required), response, concurrent, stream, cron, env, secrets, dir, and an auth block
  • worker "name"
    label
    the Worker's name
    what it declares
    inside a backend: handler and memory (both required), env, secrets, dir
  • backbone
    label
    none
    what it declares
    the stores, secrets and cache below. At most one
  • sql "name"
    label
    the database
    what it declares
    inside backbone: size (required), schema, migrations, seed
  • nosql "name"
    label
    the collection
    what it declares
    inside backbone: size (required), seed, ttl, unique
  • blobs "name"
    label
    the bucket
    what it declares
    inside backbone: size (required)
  • queue "name"
    label
    the queue
    what it declares
    inside backbone: depth
  • cache "key"
    label
    the cache key
    what it declares
    inside backbone: file or value, and ttl
  • secret "NAME"
    label
    an environment-variable-style name
    what it declares
    inside backbone: value = env("NAME") (required)
  • realtime
    label
    none
    what it declares
    inside backbone: client_channels
  • canvas
    label
    none
    what it declares
    the site blocks. At most one
  • site "/path"
    label
    the path it is served at
    what it declares
    inside canvas: dir (required)
  • edge
    label
    none
    what it declares
    rate_limit, links, allow, hosts, and the blocks egress, domain "host" and site_auth
  • variable "name"
    label
    the variable
    what it declares
    default
  • environment "name"
    label
    the environment
    what it declares
    slice, vars
  • hook "pre_deploy"
    label
    when it runs, pre_deploy or post_deploy
    what it declares
    run (required)
  • test "name"
    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.

typemeaning
  • name (the block's label)
    type
    string
    meaning
    Required. 1 to 32 lowercase letters, digits and hyphens, with a hyphen only in the interior. With environment blocks, prod and production apply to this bare name and every other environment to slice-environment.
  • labels
    type
    map of string
    meaning
    Your own key-value pairs, see below.
  • limits
    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:

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

typemeaning
  • labels
    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 asmeaning
  • requests_per_minute
    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.
  • timeout
    written as
    duration
    meaning
    Wall-clock time an invocation may run before it is killed.
  • log_retention
    written as
    duration, whole hours
    meaning
    How long invocation logs are kept.
  • deploy_history
    written as
    number
    meaning
    Past deploys kept per slot, for drift atomic rollback.
  • backup_retention
    written as
    duration, whole days
    meaning
    How long Backbone backups are kept.
  • scheduled_jobs
    written as
    number
    meaning
    Scheduled jobs the slice may run. Left out, it is the number of Functions with a cron.
  • atomic_storage
    written as
    size
    meaning
    Disk across every deployed slot: its code and vendored dependencies, plus the source archive stored for it.
  • canvas_storage
    written as
    size
    meaning
    Storage across every site the slice serves.
  • realtime_connections
    written as
    number
    meaning
    Live Realtime connections held at once; 0 turns Realtime off.
  • secrets
    written as
    number
    meaning
    Secrets the slice may hold.
  • secret_size
    written as
    size
    meaning
    Largest value one secret may hold.
  • locks
    written as
    number
    meaning
    Backbone locks held at once.
  • blob_object_size
    written as
    size
    meaning
    Largest single object a bucket accepts.
  • queue_depth
    written as
    number
    meaning
    Messages a queue holds when its own block states no depth.
  • vault_entry_size
    written as
    size
    meaning
    Largest value one Deed Vault entry may hold.
  • vault_entries
    written as
    number
    meaning
    Deed Vault entries one identity may hold.
  • pocket_record_size
    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 hyphen

The few that differ:

name rule
a Function's routeThe 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 nameThe same shape as any queue name.
a Worker's name1 to 63 characters, lowercase letters, digits and hyphens, starting with a letter.
a SQL database1 to 64 characters, and underscores are allowed in the interior. See Backbone.
a secretNamed like an environment variable: STRIPE_KEY.
an environmentThe slice it applies to must be a valid slice name, so slice-environment is at most 32 characters.
a label keySee 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 sql blocks.
  • scheduled_jobs is the number of Functions with a cron. Writing fewer is refused.
  • A queue with no depth takes the slice's queue_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 plan says which limit took it out of the free slice. The file never says how the slice is paid for: a billing line 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

A 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