DataHub Contract Bridge

Inspiration

dbt knows what a model declares. DataHub knows what already exists, who owns it, and what depends on it. Teams still have to reconcile those two views before a schema or contract change is safe. DataHub issue #11927 describes a real user's custom mapping between dbt contracts and DataHub contracts, while DataHub's native contract feature is still evolving. Contract Bridge makes that review explicit, reproducible, and guarded.

What it does

Contract Bridge is a deterministic data-contract agent. It:

reads one enforced model contract plus explicitly contract-tagged tests from a dbt manifest.json; launches DataHub's official MCP server and resolves exactly one matching dataset; reads the current schema, owners, and bounded one-hop downstream lineage; classifies additions, removals, type drift, missing ownership, and downstream impact; emits a human-readable Markdown review and machine-readable JSON plan with a stable SHA-256; and writes the review back to one deterministic DataHub document only when the operator supplies that exact hash, then verifies the write from a fresh read-only MCP session. The default MCP command cannot mutate. Ambiguous assets, incomplete pagination, stale hashes, oversized documents, unexpected response shapes, and failed re-reads all stop the workflow rather than producing a success claim.

How we built it

The project is a Python 3.11+ CLI with no runtime dependency for fixture planning. Its live extra uses DataHub's official mcp-server-datahub over stdio. The same pure planner operates on deterministic fixtures and live MCP context, which keeps comparison logic testable without pretending fixtures are integration tests.

The live proof runs DataHub OSS 1.5.0.6 on a disposable GitHub-hosted runner, ingests only DataHub's official SampleHiveDataset, executes the read/plan/confirm/write/re-read flow, checks verified: true, byte-compares the plans from the read and write sessions, and preserves non-secret artifacts. Successful run: https://github.com/Hero988/datahub-contract-bridge/actions/runs/29842906648.

DataHub already provides contracts, lineage, impact analysis, and MCP tools. Contract Bridge does not rebuild them. It composes four operations that are otherwise separate: dbt contract/test compilation, exact catalog resolution, lineage-and-owner-aware risk review, and hash-confirmed durable write-back. The confirmation hash binds the reviewed artifact to the later mutation session, and the deterministic document URN makes retries idempotent.

Challenges we ran into

The official MCP server chooses its document-tool surface at process startup, so a fresh read-only process is required after mutation. Its get_entities response also uses a union-shaped transport that exposes only a URN in structured content. Rather than infer success, Contract Bridge switched verification to the official grep_documents raw-content path and checks the full content through two overlapping reads. DataHub's search index can converge after ingestion, so live lookup retries are bounded and preserve exact matching.

Accomplishments that we're proud of

Twelve deterministic tests cover manifest selection, exact MCP reads, pagination, fail-closed conditions, confirmation, deterministic URNs, and verified write-back. The public live workflow completed the exact read, guarded write, and fresh-session re-read against DataHub OSS. Sample JSON and Markdown outputs are committed for evaluation without setup. No production endpoint, customer metadata, or secret enters the artifacts.

What we learned

For catalog agents, write access is the easy part; proving that the reviewed context and the written result are exactly the same is the real safety boundary. Stable hashes, bounded reads, deterministic identifiers, and independent verification turn a useful automation into an auditable one.

What's next for DataHub Contract Bridge

The next safe extension is a pull-request check that publishes the plan for review and passes its exact hash to a separately authorized write job. Broader contract mutation will remain preview-only until DataHub exposes a stable supported contract-write API with equivalent re-read guarantees

Built With

• and
• datahub's
• datahub's-official-mcp-server
• datahub-oss-1.5.0.6
• dbt-manifest-artifacts
• github-actions
• official
• pytest
• python
• ruff
• synthetic