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] Working MVP. dbt-costgate check and the GitHub Action are implemented and tested. 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)

⚠ fct_orders_daily — incremental — figure is the full-refresh scan

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%

_{Pricing: US USD 6.25/TiB · built-in table (table 2026.07, verified 2026-07-25)
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

  fct_orders_daily  (full-refresh): 819.20 GiB → 2.91 TiB   +264%   USD +13.19/run   USD +395.63/month (30 runs)
      ⚠ incremental — figure is the full-refresh scan
  dim_customers  (new): — → 412.50 MiB   —   USD +0.00/run   USD +0.07/month (30 runs)

  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%

  Pricing: US USD 6.25/TiB · built-in table (table 2026.07, verified 2026-07-25)
  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.

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. The 1 TiB/month free tier is not modeled by default.

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

• 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 entry
• Docker image on ghcr.io (GitLab CI–friendly)

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