LineageGuard AI

An AI agent that uses DataHub metadata and lineage to assess schema changes, identify downstream risks, and generate safe migration plans, validation queries, and rollback code.

Comment

LineageGuard AI

Inspiration

A database column rename looks like a small change. In a real data platform, however, that column may feed transformation models, dashboards, reports, replicated tables, and business-critical metrics. The SQL change itself can take seconds; discovering everything it might break can take days.

We built LineageGuard AI around a simple question:

What if an AI agent could inspect the actual metadata graph before proposing a migration—and refuse to recommend a dangerous shortcut when the evidence shows a large blast radius?

The goal was not to create another chatbot that generates plausible SQL. We wanted an auditable engineering agent grounded in real schemas, column-level lineage, ownership, and downstream dependencies from DataHub.

What it does

LineageGuard AI analyzes a proposed schema change and produces a safe, review-ready migration package.

In our showcase scenario, a user asks to rename customer_id to customer_key in the Snowflake order_details dataset. The agent:

  1. Resolves the exact dataset and column in DataHub.
  2. Inspects downstream lineage across two hops.
  3. Separates column-confirmed dependencies from table-level evidence.
  4. Retrieves additional context for the affected assets.
  5. Calculates a deterministic risk score.
  6. Decides whether a direct rename is safe.
  7. Generates four validated migration artifacts.

For this scenario, LineageGuard finds:

  • 24 downstream assets
  • 11 column-confirmed dependencies
  • Risk score: 90/100
  • Decision: BLOCK_DIRECT_RENAME

The score is explainable rather than model-invented:

[ R = 25_{\text{rename}} + 30_{\text{downstream}} + 10_{\text{depth}} + 20_{\text{confirmed columns}} + 5_{\text{metadata gap}} = 90 ]

Instead of executing a destructive rename, the agent proposes a staged migration: add the new column, backfill it, migrate downstream consumers, validate the result, and only then retire the old column.

It produces:

  • migration-up.sql
  • migration-down.sql
  • validation.sql
  • rollout-plan.md

These are explicitly marked as non-executable templates for human review.

How we built it

LineageGuard AI is implemented as a single TypeScript package with two entry points: a CLI for the initial vertical slice and a polished Next.js interface for the agent demo.

The application is divided into focused modules:

  • A typed DataHub catalog boundary
  • An MCP subprocess adapter
  • Pure impact-analysis and risk-scoring logic
  • A constrained OpenAI agent workflow
  • Strict artifact validation
  • Immutable run persistence
  • CLI and browser presentation layers

The local live workflow connects to DataHub through the official, pinned DataHub MCP Server. LineageGuard exposes only four read operations through its own allowlist:

  • search
  • list_schema_fields
  • get_lineage
  • get_entities

The OpenAI agent does not receive unrestricted access to the MCP server. It receives normalized, bounded context and can call only the application-owned analysis and artifact-generation tools.

Critical decisions remain deterministic. The model can help construct a migration strategy, but it cannot lower the calculated risk, fabricate evidence, execute SQL, mutate DataHub, or approve the change.

The public deployment uses a deterministic fixture replay of the certified scenario. It requires no DataHub instance, OpenAI key, login, or paid account. Live DataHub and OpenAI execution remains available locally.

Why DataHub is essential

DataHub is not a decorative catalog screen in this project. It supplies the factual context that makes the result defensible.

Schemas identify the requested field. Lineage reveals downstream impact. Entity context helps the agent understand affected assets. Metadata completeness determines how confidently the system can reason about the change.

Without DataHub, the model could only guess from the user’s prompt. With DataHub, every important conclusion can be connected to explicit evidence IDs and inspected by a reviewer.

Challenges we ran into

The hardest challenge was establishing the correct boundary between probabilistic reasoning and deterministic safety.

Early agent outputs could sound convincing while still violating required constraints. We addressed this with strict structured schemas, application-owned risk calculation, artifact validators, non-executable markers, and regression tests for unsafe recommendations such as direct renames.

Local DataHub setup also required careful work. Metadata Service Authentication is disabled by default in the OSS Quickstart configuration, and the downloaded compose file can be overwritten. We created a repeatable pinned setup with explicit authentication, version checks, health gates, and a safe token workflow.

Another challenge was incomplete metadata. Some downstream relationships were visible only at table level. Instead of hiding this limitation, LineageGuard reports medium confidence, adds a metadata-gap penalty, and states exactly what remains unknown.

Finally, we needed a public demo that judges could open without credentials while remaining honest about its execution mode. The result is a clearly labeled replay backed by the same deterministic domain logic and sanitized evidence contract as the local workflow.

What we learned

We learned that better context is more valuable than a more elaborate prompt. A capable model still needs trustworthy data, narrow tools, explicit permissions, and deterministic validation.

We also learned that uncertainty should be part of the product. Missing ownership, descriptions, glossary terms, or column-level lineage should not disappear behind a confident answer. They should affect the risk score and be visible to the reviewer.

Most importantly, an agent that sometimes refuses an unsafe action can be more useful than one that always produces an answer.

Accomplishments that we’re proud of

  • Built a working DataHub-grounded agent as a solo developer
  • Made every major impact conclusion traceable to evidence
  • Separated model creativity from deterministic safety decisions
  • Generated four mutually consistent migration artifacts
  • Enforced a read-only DataHub and non-executable SQL boundary
  • Created a free public replay requiring no credentials
  • Built deterministic, credential-free CI and regression coverage

What’s next for LineageGuard AI

Next, we want to support additional schema changes such as type changes, column deletion, nullability changes, and dataset deprecation.

We also plan to add policy-aware approval workflows, ownership notifications, richer metadata-readiness guidance, and an optional governed DataHub write-back flow—but only behind explicit authorization and human review.

Public demo: https://lineageguard-ai-replay.onrender.com

Source code: https://github.com/nextsukhorutchenko/lineageguard-ai

Built With

Share this project:

Updates