Staging and test environments

​

A layout

• The key. Give your staging deployment only the acme/staging/* key. It can’t read or change anything in production, and it can’t mark or unmark prefixes. Create keys on the dashboard’s Keys page. A scope can name a prefix before anything under it exists.
• The template. Define staging’s judgments on acme/staging/*, so every staging tenant has them, as production’s are on acme/prod/*. Templates need the Team plan, in staging as in production.
• The budget. A budget is a namespace setting; there is none on a prefix. A namespace exists from its first write, so set the budget with PATCH /namespaces/{ns} (ns.update(budget=...)) when you provision each staging tenant. With pause, a staging tenant that reaches its budget stops judging and its answers read stale; writes continue.

​

Mark the prefix non-production

await db.nonproductionPrefixes.mark("acme/staging/");
const { prefixes } = await db.nonproductionPrefixes.list();
await db.nonproductionPrefixes.unmark("acme/staging/");

db.nonproduction_prefixes.mark("acme/staging/")
prefixes = db.nonproduction_prefixes.list()["prefixes"]
db.nonproduction_prefixes.unmark("acme/staging/")

{"prefixes": [{"prefix": "acme/staging/", "marked_at": "2026-09-27T14:05:12Z"}]}

• A prefix is namespace characters ending in /. acme/staging/* is accepted and stored as acme/staging/. It can’t be the whole organization.
• It needs no namespaces yet. Mark it before staging’s first judgment.
• Up to 20 prefixes are marked at once. Marking a marked prefix, or unmarking one that isn’t marked, changes nothing.
• Each change is in your audit log as org.nonproduction.

​

What it changes

• The tenant fee. A namespace counts only if it had a billed judgment in an hour it wasn’t under a marked prefix. Marking takes effect from the next whole UTC hour, and unmarking from the start of the hour it happens in. So marking late in the month exempts nothing already judged. The invoice line says what was left out: “Active tenant namespaces: 1,600 (25 included; 1,600 non-production not counted)”. See staging tenants don’t count for a whole bill.
• Calibration. A template’s calibration pool leaves out tenants under a marked prefix: their outcomes shape neither its pooled calibration nor the prior that tenants’ own fits shrink toward. They read the pool, and get no fit of their own; their calibration report says tenant.reason: "non_production". This matters when one template covers both environments, such as acme/*. A template under the marked prefix, such as acme/staging/*, pools its staging tenants among themselves, so staging is calibrated like production without touching it.
• Nothing else. Judging, storage, writes and queries under a marked prefix are billed as usual, and shadow reports sample its tenants as usual.

​

Promote a change from staging to production

1. In staging, create the new version on acme/staging/* with the staging key, by posting the definition again under the same name. It stays inactive.
2. Activate it there. You get one shadow job, sampled across the staging tenants. Read its report, then confirm it to switch every staging tenant, and test your staging deployment against it.
3. In production, create the same definition on acme/prod/* with the production key. Versions are numbered per template, so its number there can differ.
4. Activate it on acme/prod/* and read that shadow report, sampled across production tenants. Confirm it to switch every production tenant, or cancel it to leave production as it was.

// db is a client with the acme/prod/* key.
const prod = db.namespace("acme/prod/*");
const { version } = await prod.judgments.create(needsEscalation); // the definition staging tested
const activation = await prod.judgments.activate("needs_escalation", { version });
if ("id" in activation) {
  // Read (await db.jobs.get(activation.id)).report once it is filled in, then:
  await db.jobs.confirm(activation.id);
}

# db is a client with the acme/prod/* key.
prod = db.namespace("acme/prod/*")
created = prod.judgments.create(**needs_escalation)  # the definition staging tested
activation = prod.judgments.activate("needs_escalation", version=created["version"])
# Read db.jobs.get(activation["id"])["report"] once it is filled in, then:
db.jobs.confirm(activation["id"])

​

Keep staging data synthetic