Database Branching for Replay

​

How it works

1. Connect your database once in the Bitfab dashboard. Your source database can be any Postgres; Bitfab provisions a managed, branchable copy from it.
2. Wire replay by passing dbBranch to the replay call and reading the per-trace branch URL inside the replayed function.

​

1. Connect your database

​

2. Wire replay to the branch

import { Bitfab, getCurrentReplayBranch } from "@bitfab/sdk"

const bitfab = new Bitfab({ apiKey: process.env.BITFAB_API_KEY })
const pipeline = bitfab.getFunction("checkout-agent")

// The replayed function connects to the branch URL when a per-trace branch is
// available, and to the normal env var otherwise.
const runCheckout = pipeline.withSpan(
  { name: "CheckoutAgent", type: "agent" },
  async (orderId: string) => {
    const branch = getCurrentReplayBranch()
    const url = branch?.databaseUrl ?? process.env.DATABASE_URL
    const db = makeDbClient(url) // your normal client factory
    const order = await db.orders.find(orderId)
    return decideRefund(order)
  },
)

const result = await bitfab.replay("checkout-agent", runCheckout, {
  limit: 10,
  dbBranch: true,
})
console.log(result.testRunUrl)

import os
from bitfab import Bitfab, get_current_replay_branch

bitfab = Bitfab(api_key=os.environ["BITFAB_API_KEY"])
pipeline = bitfab.get_function("checkout-agent")

@pipeline.span(name="CheckoutAgent", type="agent")
def run_checkout(order_id: str):
    branch = get_current_replay_branch()
    url = branch.database_url if branch else os.environ["DATABASE_URL"]
    db = make_db_client(url)  # your normal client factory
    order = db.orders.find(order_id)
    return decide_refund(order)

result = bitfab.replay(run_checkout, limit=10, db_branch=True)
print(result["test_run_url"])

require "bitfab"

Bitfab.configure(api_key: ENV["BITFAB_API_KEY"])
client = Bitfab.client

class CheckoutAgent
  include Bitfab::Traceable
  bitfab_function "checkout-agent"

  bitfab_span :run_checkout, name: "CheckoutAgent", type: "agent"
  def run_checkout(order_id)
    branch = Bitfab.current_replay_branch
    url = branch ? branch.database_url : ENV["DATABASE_URL"]
    db = make_db_client(url) # your normal client factory
    decide_refund(db.orders.find(order_id))
  end
end

result = client.replay(
  CheckoutAgent.new, :run_checkout,
  trace_function_key: "checkout-agent",
  limit: 10,
  db_branch: true,
)
puts result[:test_run_url]

​

Sizing and warming the branch

await bitfab.replay("checkout-agent", runCheckout, {
  dbBranch: {
    minCu: 2,
    maxCu: 2,
    warmupSql: "SELECT count(*) FROM orders; SELECT count(*) FROM line_items;",
  },
})

bitfab.replay(
    run_checkout,
    db_branch={
        "min_cu": 2,
        "max_cu": 2,
        "warmup_sql": "SELECT count(*) FROM orders; SELECT count(*) FROM line_items;",
    },
)

client.replay(
  CheckoutAgent.new, :run_checkout,
  trace_function_key: "checkout-agent",
  db_branch: {
    min_cu: 2,
    max_cu: 2,
    warmup_sql: "SELECT count(*) FROM orders; SELECT count(*) FROM line_items;"
  }
)

• minCu / maxCu set the branch compute’s autoscaling floor and ceiling, in Neon Compute Units. Setting them equal pins the size, which is what you want for an experiment: with a range, an item that runs later can hit an endpoint that has already scaled up and post a better number for identical code. Equal values are a fixed-size compute, allowed up to 56 CU. A range is autoscaling, which Neon caps at an 8 CU span and a 16 CU ceiling, so minCu: 2, maxCu: 16 is rejected. Sizes are a discrete set, not a continuum: 0.25, 0.5, every integer to 16, then even numbers to 56. Anything invalid fails the replay immediately rather than silently falling back to your live database. Note that a pinned size above 16 CU stays always-active, since Neon does not scale those to zero, so it keeps billing until the branch is released.
• warmupSql runs as part of the branch’s readiness check, before your function ever sees the lease. Warm-up time is therefore not charged to the replayed call. Passing it raises the readiness check’s budget from 10 seconds to 240 seconds, since warming a real working set is not a SELECT 1. Invalid SQL, or a warm-up that outruns that budget, fails the lease rather than quietly handing back a cold branch.

​

Handling branch failures

​

Reading the branch

• On the live request path it is null: your function keeps using its normal DATABASE_URL. The same code works in production and in replay.
• For traces captured before the SDK version that added always-on snapshot capture, it is null (no snapshot ref), so the item replays against your normal database.

​

Resolve the connection per call, not at import

​

Verifying it works

1. Run the instrumented function once so a new trace lands.
2. Replay that trace and confirm, inside the function, that the accessor returned a branch and that snapshotTimestamp matches the moment the source trace ran. A differing URL host only proves some branch was handed over; the pinned instant proves it is the right point in history.
3. Open the test run URL from the replay result to inspect the experiment.

​

Bitfab tracks whether the branch was actually used

• Used: a branch was provisioned and your function took its URL.
• Provisioned but never read: a branch was ready, but the function never asked for the URL. This usually means the replay silently hit your live database; the most common cause is a connection pool created at module import (see “Resolve the connection per call, not at import” above).
• No branch: the item had no snapshot to branch from, so the function ran against its normal database. A provisioning failure does not produce a replay trace because the function is not invoked; it returns an item with a structured replay error instead.

​

Where the provisioning time went

const result = await bitfab.replay("my-key", myFn, { dbBranch: {} })

for (const item of result.items) {
  console.log(item.dbBranchTimings)
  // {
  //   startedAt: "2026-05-22T14:29:55.000Z",
  //   projectResolveMs: 12,    // resolving your project, its retention and region
  //   branchCreateMs: 1800,    // creating the branch, until it exists
  //   connectionUriMs: 0,      // resolving the connection URI
  //   computeConnectMs: 340,   // the compute accepting a connection
  //   baseProbeMs: 8,          // the branch answering a readiness query
  //   warmupMs: 2500,          // your warm-up SQL
  //   totalMs: 4660,
  // }
}

• They are measured server-side, from Bitfab to your database provider. Your own runner will observe the total plus its round trip to the branch’s region, which the lease reports as region.
• They are per item, not per replay. Each item gets its own branch and its own compute, so a cold one and a warm one are not comparable.
• A failed resolve still reports them, carrying the phases it reached and a totalMs that is time-to-failure. Phases after the failure are absent rather than zero, so “it spent four minutes and then failed” is answerable.

​

Optional: pin the provider (TypeScript)

const bitfab = new Bitfab({
  apiKey: process.env.BITFAB_API_KEY,
  dbSnapshot: { provider: "neon" },
})

​

Limitations

• TypeScript, Python, and Ruby only (Go has no replay).
• Postgres only.
• Branch leases are short-lived (a few minutes) and created fresh per replay item. Replay completes well within that window; the lease is released and the branch deleted afterward.
• The branch reflects the source database’s state at the captured instant, bounded by replication lag (typically sub-second to a few seconds).
• When a branch is provisioned and used, replay writes land only on that ephemeral branch and are discarded; they never propagate to your source database. A trace with no snapshot uses the normal database path, so unsafe writes on that path must still be mocked.
• Only traces captured by an SDK version with always-on snapshot capture can be branched. Older traces replay against your normal database.