Backbone data & state
Backbone is declared inside one backbone block, with one block per thing the slice holds: a sql database, a nosql collection, a blobs bucket, a queue, a cache entry and a secret. Each block names the thing, states how large it is where it has a size, and says what to put in it: a schema, a seed, a lifetime, a value. The snippets below show the block inside backbone, which is where it is written; written at the top of the file it is refused.
- Label
- none
- Attributes
- The container for everything below. At most one per file.
- Label
- the database's name
- Attributes
size(REQUIRED),schema,migrations,seed
- Label
- the collection's name
- Attributes
size(REQUIRED),seed,ttl,unique
- Label
- the bucket's name
- Attributes
size(REQUIRED)
- Label
- the queue's name
- Attributes
depth
- Label
- the cache key
- Attributes
fileorvalue, andttl
- Label
- an environment-variable-style name
- Attributes
value(REQUIRED,env("NAME")only)
- Label
- none
- Attributes
client_channels
A collection, bucket or database has to exist before anything can be written to it. The slice refuses a write naming one it does not have with 400 rather than creating it, so the set is declared here, and drift apply creates what the file names.
What a size means
Every database, collection and bucket states its size, and the size has no default. It is the enforced limit and what the store is billed at, so it is the figure you are held to on both sides. A write that would pass a collection's size is refused. A size is a whole number of KiB, MiB or GiB, written "64MiB". A missing size, a size of zero and "64MB" are each refused, and every error in a file is reported at once, with its line and column:
Driftfile:9:1: Missing size: nosql "items" states its size, size = "20MiB": it is the enforced limit and what it is billed at, and the platform refuses a size of zero
Driftfile:12:10: Not a size: blobs "uploads": size "64MB" is not a size: write a whole number of KiB, MiB or GiB, e.g. "64MiB"The slice-wide dials that no single block owns sit in the limits block of slice: blob_object_size (the largest single object a bucket accepts), queue_depth (the depth of a queue that states none), secrets and secret_size, locks and realtime_connections. A size you shrink, or a store you remove, shows in drift plan as data that could be lost, and drift apply asks before it goes ahead.
NoSQL collections
nosql "name" is one document collection. Besides its size, it takes a seed, a JSONL file (one JSON document per line) that the deploy upserts by each document's _id, a ttl, and unique fields.
- Type
- size
- Default
- REQUIRED
- Meaning
- The collection's storage: the enforced limit and what it is billed at. A write past it is refused.
- Type
- string
- Default
- none
- Meaning
- A JSONL file, one document per line, each with a non-empty
_id, upserted on deploy.
- Type
- duration
- Default
- none
- Meaning
- How long a document lives after its last write:
"30s","5m","24h","7d". Left out, documents are kept forever.
- Type
- list of string
- Default
- none
- Meaning
- Fields whose values must be unique in the collection. A write that repeats one is refused with
409.
backbone {
nosql "submissions" {
size = "64MiB"
}
nosql "permit-types" {
size = "16MiB"
seed = "backbone/permit-types.jsonl"
}
nosql "sessions" {
size = "32MiB"
ttl = "30d"
}
nosql "accounts" {
size = "64MiB"
unique = ["email"]
}
}backbone/permit-types.jsonl holds one JSON document per line, each with an _id:
{"_id": "residential-extension", "name": "Residential extension"}
{"_id": "new-build-residential", "name": "New-build residential"}Seeding is idempotent (re-deploying re-upserts changed rows) and non-destructive (documents your app added at runtime are left alone, because their _ids are not in the seed file). Every line must be valid JSON with a non-empty _id.
ttl deletes a document once its last write is older than the TTL. The clock resets on every update, so only genuinely stale, untouched documents are reaped. There is no undo: documents are not soft-deleted or archived anywhere. It applies per collection, not per document.
unique names fields whose values must not repeat in the collection. A write carrying a value another document already holds in one of them is rejected with 409, inside the same transaction as the write rather than a check your own code could still lose a race on. Use it for an email, a username, an external reference. A document that omits one of these fields is written anyway; absence is not a value the constraint has an opinion on. It is authoritative in both directions: removing a field from the list and applying again stops enforcing it.
SQL databases
sql "name" is a per-slice SQLite database, addressed by name. Each materialises as one .db file and is reached from the SDK as drift.Backbone.SQL("name") for relational queries and transactions. The name is 1 to 64 characters ([a-z0-9], then [a-z0-9_-], then [a-z0-9]) and becomes both the .db filename and the SDK lookup key. The number of databases the slice holds is the number of sql blocks in the file.
- Type
- size
- Default
- REQUIRED
- Meaning
- The database's storage: the enforced limit and what it is billed at.
- Type
- string
- Default
- none
- Meaning
- A SQL file of idempotent DDL, applied on every deploy, before
migrations.
- Type
- string
- Default
- none
- Meaning
- A folder of numbered
<number>_<name>.sqlfiles, such as0001_create_users.sql, each applied once, in order, afterschemaand beforeseed.
- Type
- string
- Default
- none
- Meaning
- A SQL file run after
schemaandmigrations, while the database holds no data yet.
backbone {
sql "app" {
size = "128MiB"
schema = "backbone/app.sql"
migrations = "backbone/migrations"
seed = "backbone/app-seed.sql"
}
}A deploy takes them in that order: the schema every time, each migration once, the seed while the database holds no data. schema is applied on every deploy, so keep it idempotent (CREATE TABLE IF NOT EXISTS ...).
Migrations are applied once, on the first deploy that sees them, in numeric order, each in its own transaction, and recorded in the database's _drift_migrations table. A new file numbered below one already applied is refused, and so is an applied file whose contents changed: put the change in a new migration instead. A migration that fails is rolled back and fails the deploy, naming the file. The SQL guide has every rule.
seed runs while the database holds no data yet: when it has no tables, or the first of its tables by name (the migration history aside) is empty. In practice that is the first deploy, so later deploys do not re-run it, even if you change the file. To re-run a seed, start from an empty database again: drop it with drift backbone sql drop <name> and apply again, and the deploy recreates the database and re-applies the schema, the migrations and the seed.
Read the Backbone SQL guide for querying and transactions from your Functions.
Blob buckets
blobs "name" is a bucket in the slice's blob store. A bucket has no seed or schema, so the block is its name and its size. Code does not reach a bucket through a handle the way SQL("name") does; drift.Backbone.Blob.Put and .Get take one path-shaped name (for example "uploads/receipt-42.pdf"), where everything before the first / is the bucket, and a name with no / goes to the default bucket.
- Type
- size
- Default
- REQUIRED
- Meaning
- The bucket's storage: the enforced limit and what it is billed at.
backbone {
blobs "uploads" {
size = "256MiB"
}
}The largest single object a bucket accepts is blob_object_size in limits. A put naming a bucket the slice does not hold is refused with 400, the default bucket included, and the same holds for an undeclared collection. See Blobs and NoSQL.
Queues
queue "name" is a FIFO queue. A Function labelled QUEUE <name> drains it. Queues cannot be seeded, because seeding messages on every deploy would re-fire work, so a block is a name and, optionally, a depth.
- Type
- number
- Default
- the slice's
queue_depth - Meaning
- Messages the queue holds before producers are throttled. 0 or more.
backbone {
queue "validate" {}
queue "notify" {
depth = 200
}
}validate takes the slice-wide depth, limits.queue_depth; notify states its own. drift plan shows a queue with no depth as the slice's queue depth, and one with a depth as 200 messages. A queue that is removed, or whose depth shrinks, is listed as data that could be lost. A Function that drains a queue the file does not declare still fires, but the queue then has no declared depth, and drift file lint says so.
Secrets
A secret "NAME" block holds one credential the slice keeps and your Functions and Workers read. Its name is written like an environment variable, STRIPE_KEY. Its value is always a reference: value = env("NAME"), the name of an environment variable read when drift apply runs, so the credential itself never touches the Driftfile and only the resolved string travels.
backbone {
secret "RESEND_API_KEY" {
value = env("RESEND_API_KEY")
}
secret "STRIPE_KEY" {
value = env("STRIPE_KEY")
}
}- Type
env("NAME")- Default
- REQUIRED
- Meaning
- The environment variable the value is read from at apply. Written
env("NAME")and nothing else.
A literal is refused. The Driftfile is in your repository, so a literal here would be a credential committed to git, readable by everyone with repository access and still in the history after you remove it. var.x and file() are refused for the same reason, since both put the value in the repository. The refusal never prints the value:
Driftfile:6: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 fileA Function reads only the secrets its secrets list names. Declaring a secret holds it on the slice; a Function or Worker that does not list it cannot reach it. Name each one where it is used:
atomic {
backend "default" {
function "POST /submit" {
handler = "PostSubmit"
memory = "32MiB"
secrets = ["RESEND_API_KEY"]
}
}
}If the value is not secret at all, put it in the Function's env rather than here. A secret block is what tells a reviewer which Functions gained privilege, and that reading only holds while the list carries credentials.
env("NAME") is looked up through four sources, highest precedence first:
- The terminal: a variable exported in your shell session.
--var NAME=value(repeatable) ondrift plananddrift apply.--secret NAME=valueis the same flag. A flag yields to a variable the terminal set; it beats the env files..env.<environment>: when an environment is selected, the per-environment file (for example.env.staging) next to the Driftfile. It out-ranks the base.env..env: the baseNAME=valuefile next to the Driftfile, sourced automatically. Lowest precedence; it fills only what nothing above provided.
So an exported DB_PASSWORD beats --var DB_PASSWORD=..., which beats a DB_PASSWORD line in .env.staging, which beats one in .env. Pass --no-env-file to skip the env files. Values that differ per environment and are not secret belong in environment blocks and variables; only secrets belong in .env.<environment>.
A secret is write-only: the platform never returns it. drift plan therefore never compares one. A secret whose variable is set shows as present and is set again from the variable on apply, a secret whose variable is not set shows as $STRIPE_KEY is not set here: apply would refuse, and a secret the slice holds that the file does not name is listed as a removal. The number of secrets a slice holds is limits.secrets, and the largest value one may hold is limits.secret_size.
Realtime
realtime says which Realtime channels a visitor's browser may publish to. A slice has one block, and it has one attribute.
- Type
- list of string
- Default
- none
- Meaning
- The channels a client may publish to. A channel name, a prefix ending in
*, or"*"for every channel.[]closes every channel. At most 64 entries.
backbone {
realtime {
client_channels = ["board:*", "chat"]
}
}No channel accepts client frames until it is named here. A frame a client sends on any other channel is dropped and never reaches the room, and the sender is told once why. Subscribing is not affected. A Function may always publish; the list governs clients only, and a Function cannot change it.
The list is the whole truth, as edge.allow is: drift apply replaces the slice's set with the file's, and a file with no realtime block closes whatever an earlier apply opened. drift plan shows each channel opening or closing, and closing one asks for no answer, since no data goes with it. An entry the slice would refuse, such as a name with a space, is refused when the file is read, at its line.
Cache
cache "key" is a cache entry written on every deploy, so it is the initial warm set: at runtime the cache is read and written from your Functions. Give it a file whose contents become the value, or an inline value, and a ttl.
- Type
- string
- Default
- none
- Meaning
- A file whose contents are the value.
- Type
- string
- Default
- none
- Meaning
- The value itself.
- Type
- number
- Default
- never expires
- Meaning
- Seconds the entry lives. After it, a
Cache.Getreturns empty until your code re-populates the entry. Left out, or 0, the entry never expires.
backbone {
cache "menu" {
file = "backbone/menu.json"
}
cache "banner" {
value = "Closed for maintenance"
ttl = 3600
}
cache "pricelist" {
file = "backbone/prices.json"
ttl = 86400
}
}A key declared twice is refused. Read the Backbone Cache guide.