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

[!NOTE] Working MVP. dbt-costgate check and the GitHub Action are implemented and tested. The PR-comment image below is an illustrative mock of the comment's design; the terminal output further down is real dbt-costgate output. 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

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

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

  fct_orders_daily  (full-refresh): 68.20 MiB → 2.91 TiB   +$18.19/run   +$545.61/month (30 runs)
      ⚠ incremental — figure is the full-refresh scan
  dim_customers  (new): — → 412.50 MiB   +$0.00/run   +$0.07/month (30 runs)

  GATE: FAIL
    - fct_orders_daily: +$18.19/run exceeds $5.00

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

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

• ⚠️ Honest limits, stated up front — under capacity/editions pricing, bytes scanned is a proxy signal, not your invoice; 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)
• Live pricing (opt-in) via the Cloud Billing Catalog API

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