ContractGuard

Inspiration

Code reviewers can see a migration diff, but they rarely know every dashboard, model, or analyst query downstream. DataHub already contains that organizational context. ContractGuard turns it into an executable safety gate before a breaking data change reaches production.

What it does

ContractGuard reviews SQL and dbt changes, resolves referenced assets through DataHub, measures downstream blast radius, detects unstable projections and deprecated assets, and returns a PASS, REVIEW, or BLOCK decision.

In the current committed example, dropping analytics.customers.email is blocked with a risk score of 100. DataHub evidence identifies two downstream consumers and two active production query patterns that use the dropped column; the query evidence was added after the narrated demo was recorded. ContractGuard also flags the unstable SELECT *, proposes a compatibility-first migration, and can write the evidence-backed decision back to DataHub as a durable document.

How we built it

The dependency-free Python policy engine is separated from catalog transport by an adapter interface. The production adapter targets DataHub's official MCP server over stdio JSON-RPC and uses:

• search to resolve SQL identifiers
• get_entities for schema, owners, and deprecation context
• get_lineage for downstream blast radius
• get_dataset_queries for real usage evidence
• save_document to preserve the review decision in DataHub

A deterministic fixture adapter makes judging and tests reproducible without claiming that sample results came from a private live catalog.

The public CLI now exposes the production adapter through --live-datahub. Discovery remains read-only by default; a live writeback requires both --write-back and --enable-mutations, so an ordinary review cannot silently enable DataHub MCP mutation tools.

Challenges

The central challenge was avoiding generic lint rules. Each important finding needed catalog evidence so the result would be explainable, organization-specific, and actionable. We also designed the writeback loop so DataHub is part of the decision workflow rather than a decorative lookup.

Accomplishments

• DataHub is in the critical path of every meaningful decision.
• Findings bind each verdict to lineage and active usage-query evidence.
• The agent proposes a safer migration instead of only reporting failure.
• Live writeback is protected by an explicit least-privilege mutation gate.
• SQL comments and string literals are masked before risk analysis, preventing non-executable examples from causing false BLOCK or REVIEW decisions.
• Breaking remediation is fail-closed: position-sensitive rewrites happen before every source line is disabled, so multiline destructive SQL cannot remain executable.
• Whole-table drops, including DROP TABLE IF EXISTS, now use asset-wide query evidence instead of being misread as column drops.
• Nineteen reproducible tests cover breaking lineage, scoring, remediation, SQL lexical isolation, CLI routing, and writeback.

What we learned

Metadata becomes most valuable when it is brought into the developer's moment of action. A small SQL diff can carry large organizational risk, and lineage plus usage context can make that risk visible before merge.

What's next

GitHub Check annotations, dbt manifest mapping, owner notifications, richer column-level lineage, and a DataHub Cloud-backed hosted demo.

Verification

• Public source and Apache-2.0 license: https://github.com/ILoveBuns/contractguard-datahub
• Current source commit: ddb7832
• Public GitHub Actions CI passes all 19 deterministic tests on Python 3.11, 3.12, and 3.13: https://github.com/ILoveBuns/contractguard-datahub/actions/runs/31324364261
• Machine-readable example artifact: artifacts/review.json
• Narrated demo (recorded before the latest query-evidence and live-CLI additions, so it honestly shows the earlier BLOCK/70 result): https://youtu.be/tHVYGCJKByo

Built With

• datahub