Relink

Relink is a GitHub-native agent that traces breaking schema changes through FalkorDB, repairs only affected SQL and Airflow code, validates every fix, and delivers review-ready pull requests.

Comment

Inspiration

A single column rename shouldn't break an entire data pipeline. Yet in modern data systems, one small upstream schema change can trigger failures across dozens of downstream SQL models, dashboards, and orchestration workflows.

The real challenge isn't just fixing broken code. It's understanding what actually broke, why it broke, and what should remain untouched.

Traditional approaches rely on manual dependency tracing, brittle search-and-replace operations, or AI-generated patches that may introduce nonexistent columns.

That led to a question:

What if a coding agent could understand the entire dependency graph before changing even one line of code?

That's why I built Relink, a GitHub-native schema-drift repair agent powered by FalkorDB.

What it does

Relink transforms schema changes into traceable, validated, reviewable code repairs.

When an upstream column is renamed, retyped, or dropped, Relink:

  1. Detects schema drift: Compares warehouse schemas against a baseline to identify breaking changes.
  2. Traces the blast radius: Uses FalkorDB and Cypher to investigate multi-hop column lineage across dbt models and Airflow workflows.
  3. Decides what actually needs fixing: Classifies assets as requiring repair, protected by an existing alias, or unaffected.
  4. Investigates with AI: Uses Groq-powered reasoning and Model Context Protocol (MCP) tools to explore graph evidence and propose structured PATCH/SKIP decisions.
  5. Generates precise repairs: Applies deterministic AST-based transformations instead of letting an LLM freely rewrite source code.
  6. Validates every change: Checks generated column references against the active FalkorDB schema and blocks invalid repairs.
  7. Delivers through GitHub: Produces reviewable diffs, impact explanations, validation evidence, and GitHub-native repair updates.

The key difference: Relink doesn't blindly fix everything downstream. It understands which dependencies are genuinely broken.

A real example

Imagine renaming raw_orders.user_id to customer_user_id.

A naive agent might attempt to modify every downstream model referencing the original field.

Relink instead traces the column through FalkorDB and discovers that:

  • stg_orders.sql needs a targeted repair.
  • orders.sql and customers.sql remain safe because an existing customer_id alias protects their contracts.
  • Unrelated models should not be modified.

The result is a surgical repair with evidence explaining both the changes made and the changes intentionally skipped.

How I built it

Relink combines graph reasoning, agentic tool use, deterministic code transformation, and GitHub automation.

FalkorDB is the heart of the architecture. It stores datasets, columns, lineage relationships, code assets, incidents, and repair runs. Cypher queries and native breadth-first search power dependency tracing and impact classification.

I built a Python backend using FastAPI, with a dedicated MCP server exposing graph investigation and validation tools.

The AI agent uses Groq with openai/gpt-oss-120b to dynamically select MCP tools, inspect graph evidence, and propose structured repair decisions.

But there's an important safety boundary: the LLM does not directly write code.

Every proposed action must pass deterministic graph-policy checks. Actual code modifications use SQLGlot for SQL AST transformations and structured editors for dbt metadata and supported Airflow SQL.

A separate validation layer resolves generated references against FalkorDB before any repair can proceed.

For the interface, I built a React and TypeScript control room featuring interactive dependency graphs, schema diffs, agent execution timelines, proposed patches, validation results, and reviewer handoff screens.

Finally, I integrated a GitHub App that responds to relevant issues and pull requests, investigates changes, posts graph-backed explanations, and supports validated repair commits on existing PR branches.

Challenges I faced

1. Understanding multi-hop dependencies accurately

A column might travel through several models before reaching its consumers. Simply finding references isn't enough, especially when aliases protect downstream contracts. Modeling column-level lineage and alias boundaries in FalkorDB was essential.

2. Preventing AI hallucinations from becoming code

An LLM can propose convincing fixes that reference nonexistent columns. I separated AI-driven investigation from deterministic execution and introduced strict validation against the live graph.

3. Knowing when NOT to change code

One of the hardest problems was distinguishing genuinely broken dependencies from unaffected assets. Relink needed to justify every PATCH and every SKIP using graph evidence.

4. Making GitHub automation safe

Handling webhook authentication, duplicate events, concurrent branch changes, and self-triggered webhook loops required careful safeguards.

Accomplishments I'm proud of

  • Built an end-to-end schema-drift investigation and repair pipeline with FalkorDB as its authoritative knowledge graph.
  • Integrated real MCP-based tool discovery and dynamic AI investigation.
  • Implemented deterministic repairs for column renames, type changes, and drops.
  • Developed graph-backed PATCH/SKIP classification that recognizes alias-protected dependencies.
  • Added reference-level validation to prevent unsupported SQL changes.
  • Built a GitHub-native workflow that connects schema-change proposals to reviewable repair evidence.
  • Created an interactive control room that makes the agent's reasoning and decisions inspectable.

Most importantly, Relink demonstrates an alternative to unrestricted AI code generation: an agent that can reason flexibly while operating within verifiable engineering constraints.

What I learned

Building Relink changed how I think about AI agents.

An agent doesn't become more reliable simply by using a more powerful language model. Reliability comes from giving it the right context, tools, constraints, and verification mechanisms.

I learned how graph databases enable multi-hop reasoning, how MCP can expose specialized capabilities to an AI agent, and how deterministic execution can complement probabilistic reasoning.

The biggest lesson: A useful AI agent must know not only what to change, but also what to leave alone.

What's next for Relink

The current GitHub-native demonstration focuses on a configured Jaffle Shop repository and supported schema-change scenarios.

Next, I want to:

  • Support arbitrary dbt repositories through automatic repository ingestion.
  • Integrate directly with production warehouse metadata sources.
  • Expand repair capabilities to more complex SQL and orchestration patterns.
  • Add authenticated, repository-scoped access to investigation evidence.
  • Introduce durable background workers for scalable webhook processing.
  • Expand validation and impact analysis across larger production data ecosystems.

The vision is simple: Make schema evolution safer by turning every breaking data change into an explainable, validated repair before it becomes a production incident.

Built With

Share this project:

Updates

Submission history