dbt-costgate

The BigQuery cost gate for dbt pull requests.

Dry-run what changed, price the diff, and catch the $500-a-day model
before it merges — not on next month's bill.

Quick start · How it works · What you get · Where it fits · Pricing accuracy · Security · Roadmap · Contributing

New here? Start with dbt-costgate, explained — plain English, ten minutes, no prior context assumed.

[!NOTE] MVP — feature-complete, not yet battle-tested. Everything on the roadmap ships: the CLI, the GitHub Action, a pre-commit hook, a published container image, and config scaffolding. What it has not had is mileage across many real projects, which is the only thing that finds the last class of bug. If it does something wrong or confusing, that is worth a bug report — including "the number looks wrong", which is the most useful report this tool can get.

Every report shown here is generated from the real renderers by scripts/gen_samples.py, and CI fails if any of them drifts from what the code actually produces — the figures are illustrative, the output is not. See the usage guide and changelog.

The problem

On dbt + BigQuery teams, SQL changes merge with zero visibility into their cost impact. A changed join, a dropped partition filter, or a widened incremental window can multiply a model's bytes scanned — and the team finds out days later on the bill, or when finance escalates.

BigQuery's dry-run API returns the exact bytes a query would scan — for free, before running anything. dbt-costgate packages that into a first-class PR gate:

What you get on every PR

A sticky comment on the pull request, updated in place on every push. This is the comment itself — GitHub renders it from the same markdown dbt-costgate produces:

💸 dbt-costgate — cost impact of this change (2 models)

❌ Gate: FAIL

• fct_orders_daily: USD +13.19/run exceeds USD 5.00
• fct_orders_daily: +264% exceeds 25%

Net increase: USD 13.19/run · USD 395.70/month

⚠ full-refresh — rows tagged full-refresh show what it costs to build the whole table from scratch. A normal incremental run scans much less, so read this as the ceiling rather than the nightly bill.

_{Pricing: US USD 6.25/TiB · built-in table (table 2026.07, verified 2026-07-25)
Priced from the first byte scanned: BigQuery's 1 TiB/month on-demand free tier is per billing account, so it is disclosed here and never deducted.
Estimates from BigQuery dry-run — nothing executed, no bytes billed, no SQL shown.}

dbt-costgate check --baseline path/to/main/manifest.json

dbt-costgate — region: US · on-demand USD 6.25/TiB · built-in table

  MODEL                             BASELINE     CURRENT    Δ %     Δ / RUN    Δ / MONTH  RUNS
  ────────────────  ────────────  ──────────  ──────────  ─────  ──────────  ───────────  ────
  fct_orders_daily  full-refresh  819.20 GiB    2.91 TiB  +264%  USD +13.19  USD +395.63    30
  dim_customers     new                    —  412.50 MiB      —   USD +0.00    USD +0.07    30

  Net increase: USD 13.19/run · USD 395.70/month

  GATE: FAIL
    - fct_orders_daily: USD +13.19/run exceeds USD 5.00
    - fct_orders_daily: +264% exceeds 25%

  NOTES
    ⚠ full-refresh — rows tagged full-refresh show what it costs to build the whole table from
      scratch. A normal incremental run scans much less, so read this as the ceiling rather than the
      nightly bill.

  Pricing: US USD 6.25/TiB · built-in table (table 2026.07, verified 2026-07-25)
  Priced from the first byte scanned: BigQuery's 1 TiB/month on-demand free tier is per billing
    account, so it is disclosed here and never deducted.
  Estimates from BigQuery dry-run — nothing executed, no bytes billed, no SQL shown.

Quick start

pip install dbt-costgate
gcloud auth application-default login

dbt compile
dbt-costgate check

That's the entire local setup — no baseline, no CI, no config file. Add a baseline and thresholds when you want it to block a PR; see the usage guide.

When you do want a config file, dbt-costgate init writes one documenting every setting, all commented out — so it changes nothing until you uncomment something.

Every release also ships a wheel, an sdist, and SHA256SUMS if you'd rather pin to an artifact.

Documentation

So you know where to look before you open anything:

Every example report in these docs is generated from the real renderers, and CI fails if one drifts — so what you read is what the tool actually prints.

How it works

Where it fits

dbt-costgate is the preventive half of BigQuery cost control — it deliberately does not compete with the excellent retrospective tools:

Accurate, transparent pricing

BigQuery on-demand rates differ by region — a gate that prices every byte at the US rate is silently wrong for half the world. dbt-costgate treats pricing accuracy as a feature:

• 🌍 Versioned per-region pricing table with a last_verified date, auto-selected from your job's detected region.

• 🧾 Every report discloses its math — region, rate, and rate source. Never a silent assumption:

  region: US (multi-region) · on-demand USD 6.25/TiB · source: built-in table 2026.07
  

• ⚙️ Overridable — pricing.region to force a region, pricing.usd_per_tib for negotiated or editions rates, pricing.currency to label amounts in your own currency (an ISO 4217 code — dbt-costgate labels, it never converts).

• ⚠️ Honest limits, stated up front — under capacity/editions pricing, bytes scanned is a proxy signal, not your invoice; set a rate of 0 and reports drop money entirely and measure bytes instead. Every priced report's footer discloses the 1 TiB/month on-demand free tier it does not deduct — the allowance is per billing account, which a dry-run cannot see, so figures are priced from the first byte.

Security model

This tool runs in CI next to warehouse credentials, so the design is deliberately boring:

Details in SECURITY.md · deeper design notes in docs/architecture.md.

Roadmap

The MVP roadmap is complete — every item below ships as of v1.0.5.

• dbt-costgate check — local (zero-setup) + CI diff, region-aware pricing, threshold gating
• One-command local diff — dbt-costgate check --against main (isolated git worktree)
• GitHub Action wrapper with a sticky PR comment
• Absolute cost ceilings — gate on total $/run or TiB/run, not just the increase (works without a baseline, so it gates local mode too)
• Config- and macro-only change detection — catch a change that reaches a model without touching its .sql file
• pre-commit hook — catch it on your own machine, at pre-push
• Docker image — for CI that isn't GitHub Actions; build it yourself, or
• pull the published image — ghcr.io/drichards124/dbt-costgate:v1.0.5, pushed on every release

What's next is not another feature. The list above was written before anyone had run this against a real warehouse for a month. The useful next step is use — finding where the numbers, the defaults or the docs are wrong — and the next features should be the ones that use actually asks for, rather than the ones that looked obvious from here. Two places that already know what they don't do: when the number can be wrong and the non-goals below.

Non-goals

• Not a monitoring tool — retrospective observability belongs to dbt-bigquery-monitoring.
• BigQuery first — one warehouse done accurately beats three done approximately. Other warehouses come only once BigQuery is genuinely finished, and only where the cost model actually transfers.
• Never runs billable queries — features that require executing real queries are out of scope by design.
• No IDE/editor integration (for now).