LineageGuard(Metadata-Aware Code Generation)

A metadata-aware migration & impact-analysis agent that generates production-safe schema changes and closes the loop by writing verified impact data back into DataHub.

Comment

Inspiration

Most AI coding tools can answer:

“What SQL should I write?”

But a production schema change requires a harder answer:

“Should this change happen, what could it break, and who needs to review it?”

A simple request such as renaming or dropping a column can affect downstream datasets, dashboards, queries, pipelines, data quality checks, and business reports. The problem is that this context usually exists outside the code change itself.

LineageGuard was inspired by this gap. It uses DataHub as the source of truth for schema, lineage, ownership, tags, documentation, and downstream dependencies, allowing an agent to make a more informed governance decision before generating a migration.

What it does

LineageGuard transforms a natural-language database change request into a governed and auditable workflow:

Natural-language request
        ↓
DataHub context through MCP
        ↓
LLM planning
        ↓
Risk and impact analysis
        ↓
Platform-aware SQL generation
        ↓
Approval gate
        ↓
GitHub pull request
        ↓
DataHub write-back

The agent:

  • Retrieves real dataset metadata from DataHub through MCP.
  • Understands the requested change using an LLM.
  • Produces a structured execution plan.
  • Calculates deterministic risk and downstream impact.
  • Generates platform-aware migration SQL.
  • Generates rollback SQL and change documentation.
  • Requires approval for risky changes.
  • Creates an auditable GitHub pull request after approval.
  • Writes governance metadata back to DataHub.
  • Uses idempotency and audit logs to make the workflow safer and traceable.

The important part is that SQL generation happens after planning, risk analysis, and impact analysis. For higher-risk changes, the workflow stops at an approval gate instead of automatically creating the GitHub change.

How we built it

LineageGuard uses a hybrid architecture that separates language understanding from safety-critical execution.

The LLM is responsible for:

  • Understanding natural-language intent.
  • Identifying the requested operation.
  • Finding affected columns and assets.
  • Creating a structured execution plan.
  • Recording assumptions, missing information, and confidence.

Deterministic engines are responsible for:

  • Risk scoring.
  • Downstream impact analysis.
  • Approval decisions.
  • Platform-aware SQL generation.
  • Rollback generation.
  • SQL validation.
  • Idempotency.
  • GitHub operations.
  • DataHub mutation validation.

The project was built with:

  • Node.js and TypeScript.
  • DataHub MCP Server for metadata context.
  • PostgreSQL and Prisma for persistence.
  • GitHub API and Octokit for pull request automation.
  • A web interface for reviewing requests, risk, impact, and generated artifacts.
  • Docker and Docker Compose for reproducible setup.

The main pipeline is implemented as separate stages:

Context → Planning → Risk → Generation → Impact → Approval → GitHub

Each stage adds structured information to the workflow state, making the final decision auditable and easier to debug.

Challenges we ran into

The biggest challenge was working with real metadata and agent infrastructure rather than a static demonstration.

We had to understand how to:

  • Retrieve and normalize schema, ownership, lineage, and governance metadata.
  • Work with DataHub through the MCP protocol.
  • Handle incomplete or missing metadata.
  • Understand the response shape of lineage operations.
  • Safely perform DataHub mutations.
  • Separate LLM output from deterministic execution.
  • Generate platform-specific SQL and rollback scripts.
  • Prevent duplicate branches and pull requests.
  • The GitHub integration exposed another useful failure. A feature branch could be created successfully, while the following file commit still failed when resolving the branch reference. This showed us that successfully creating a branch is not enough to consider the GitHub stage successful. Each external operation needs its own validation and error handling.

Running the complete local DataHub environment also required careful configuration, environment management, and sufficient Docker resources.

These challenges led us to add validation, structured errors, retries, idempotency, audit logging, dependency injection, and explicit safety boundaries.

Accomplishments that we're proud of

We are proud that LineageGuard became a complete workflow rather than a prompt that returns SQL. The system connects real DataHub metadata to a planning and governance pipeline and ultimately produces reviewable engineering artifacts in GitHub.

The agent can move from:

Natural-language request
        ↓
Real DataHub context
        ↓
Risk-aware decision
        ↓
Validated migration
        ↓
Human approval
        ↓
GitHub pull request
        ↓
DataHub governance record

The accomplishments we are most proud of are:

  • Using real DataHub metadata to influence the change decision.
  • Combining LLM planning with deterministic safety controls.
  • Producing migration, rollback, and documentation artifacts together.
  • Performing downstream impact analysis before delivery.
  • Keeping risky changes behind an explicit approval gate before GitHub execution.
  • Producing a reviewable pull request containing the generated migration and change documentation.
  • Writing the governance result back into DataHub.
  • Adding idempotency to prevent duplicate workflow and GitHub operations.
  • Keeping production actions behind explicit validation and approval boundaries.
  • Building the project as a complete, inspectable reference implementation for metadata-aware code generation.

The central idea is simple:

DataHub context should not just explain a change. It should control what the agent is allowed to do.

What we learned

The biggest lesson was that the model is only one part of the system. The difficult engineering work was deciding what the model is allowed to decide, what must be deterministic, and where the workflow must stop and ask a human.

The most important lessons were:

  • Context is valuable only when it changes the agent’s decision.
  • LLMs are useful for semantic understanding, but deterministic code should control execution.
  • High-risk actions need explicit approval boundaries.
  • Rollback and auditability should be designed from the beginning.
  • Idempotency is essential when agents interact with external systems.
  • Metadata quality directly affects the quality of agent decisions.
  • A failed write-back or external operation must be visible and explainable.
  • A clear workflow is more valuable than an overly complicated agent architecture.
  • DataHub becomes more powerful when agents both read from and contribute back to the metadata graph.

One lesson became especially clear during testing: a generated migration is only useful if the evidence behind it is trustworthy.

For every change, LineageGuard needs to preserve the chain from the original request to the DataHub context, execution plan, risk assessment, generated SQL, approval decision, and GitHub artifact.

That chain is what makes the system useful for real engineering workflows rather than just another code-generation demo.

What's next for LineageGuard (Metadata-Aware Code Generation)

The next phase of LineageGuard would focus on making the governance workflow more collaborative and production-ready.

Potential next steps include:

  • Multi-user and multi-stage approval workflows.
  • Owner-specific review routing.
  • Slack and Microsoft Teams notifications.
  • Jira and incident-management integration.
  • Stronger column-level lineage analysis.
  • Policy-as-code for organization-specific governance rules.
  • Better handling of schema evolution strategies such as expand-and-contract migrations.
  • Automated validation against staging environments.
  • More database platforms and migration frameworks.
  • Historical learning from previous approvals and rejected changes.
  • Richer DataHub write-back records with links to pull requests and mitigation history.
  • Continuous monitoring of approved changes after deployment.

The broader vision is to make LineageGuard a governance layer between natural-language engineering requests and production data changes.

For the Build with DataHub hackathon, LineageGuard fits the Metadata-Aware Code Generation category because DataHub metadata directly influences the generated engineering plan, risk assessment, migration, approval workflow, and final GitHub artifact.

Built With

Share this project:

Updates