SQL2Graph Agentic Migration: From Relational Thinking to Graph Reasoning

By Ante Javor

7 min readNovember 11, 2025

If you’ve ever designed a relational database, you already know how to model tables, define primary and foreign keys, and structure your relational model. Relational modeling is familiar to most developers.

Graph modeling is different. It requires a shift in mindset, from organizing data in rows and columns to representing it as a network of connected nodes and relationships.

This change introduces a steep learning curve. To design a helpful graph, you need to:

Translate concepts (people, devices, events) into nodes and relationships
Define properties, labels, and constraints that maintain expressiveness and efficiency
Understand query access patterns and traversal semantics

Even simple questions, like whether something is a node or a relationship, can influence how you query and reason about data later. The difficulty is not in writing the Graph Query language, but in mapping a relational mental model into a graph model.

At the organizational level, this knowledge gap means that only a few “graph champions” typically have the combined skills to design, reason, and implement graph systems effectively. This is a problem since the majority of data systems are based on the relational model.

Which is why SQL2Graph came into being. The idea was to move shift from relational to graph databases in the simplest and quickest way possible by removing the hurdle of this knowledge gap.

The Role of Agentic Systems

Large Language Models (LLMs) have recently demonstrated strong capabilities in pattern recognition, understanding, and reasoning assistance when working towards a particular problem. When applied to graph challenges, they can act as intelligent co-workers, capable of interpreting data, suggesting models, and automating repetitive steps.

This means if you are interested in the graphs, you can have a helping hand. This is where the SQL2Graph Agent steps in.

What is the SQL2Graph Agent?

The SQL2Graph is a migration agent that automates the process of converting relational databases into graph structures suitable for Memgraph.

It combines schema analysis, HyGM modeling, and data validation into a single automated process. This means you can quickly get from the relational mode to the graph model with migrated data.

There are a few essential aspects of this Agent’s operations and capabilities:

Automatic Schema Analysis
HyGM modeling strategy
Migration modes
Validation

The Schema analysis detects tables, columns, constraints, and indexes to understand the data in the relational model. After the schema is collected, HyGM (Hypothetical Graph Modeling) comes into play. HyGM is at the core of this SQL2Graph agent. It is a component responsible for automatically generating graph models and AI modeling.

It supports two modeling strategies:

Fully AI-powered modeling strategy
Deterministic (Rule-based) modeling strategy

There are also two migration modes: ****

Automatic mode: where the user does not provide any input into modeling or migration.
Incremental mode: ****which involves the user's input and feedback loops to improve the graph model.

After modeling is complete, validation occurs at both the model level and the migration level, ensuring that we have accurate models and that the data has been appropriately migrated.

In short, this is your helpful co-worker trying to assist you with migrating your data swiftly without any hiccups.

How It Works

The SQL2Graph Migration Agent is a Python-based system that leverages the LangGraph workflows for orchestration and Memgraph Mage migration modules to migrate the data.

Follow this step-by-step how-to guide on SQL2Graph to get started immediately.

Architecture Overview

This is what the architectural flow of the agent looks like:

After the graph model is generated, the agent performs multiple validation steps to ensure data integrity and schema consistency between the relational source and the resulting graph representation.

These checks include verifying referential constraints, index coverage, and property type alignment to confirm that the generated graph structure accurately reflects the original SQL schema.

This process is not strictly linear and there are feedback loops during model creation. For example, if the LLM-powered HyGM strategy produces a graph model that fails pre-migration validation, the agent automatically regenerates and refines the model.

This iterative approach ensures that even AI-generated graph designs attempt to approximate the most accurate version of the SQL model. Of course, LLMs are non-deterministic systems, and anything is possible at that point.

The Two Modeling Strategies

1. Deterministic Strategy

The deterministic mode provides a predictable, rule-based transformation from relational to graph structures.

It applies a fixed set of mapping rules, making it ideal for transparent migrations where reproducibility and consistency are most important.

Transformation Rules:

Tables → Nodes: Each table becomes a node label with the same name.
Columns → Properties: Each table column is translated into a node property.
Foreign Keys → Relationships: Foreign key constraints define directed relationships between nodes.
Junction Tables → Relationships with Properties: Many-to-many junction tables are converted into relationships that can retain additional attributes.
Indexes & Constraints: Automatically recreated on the graph side to maintain performance and data integrity.

This approach serves as the baseline strategy. You’ll get a reliable, fully deterministic process that ensures an accurate 1:1 structural translation from SQL to graph model. Keep in mind that there is also an interactive modeling approach available, and you can leverage HyGM to actually change something in the model using the AI.

2. LLM-Powered Strategy

The LLM-powered strategy mode utilizes large language models to interpret relational structures and propose an optimized graph model. This mode aims to automatically capture domain semantics and determine the best graph model for a given SQL model. All in just a few minutes.

As all LLMs are non-deterministic systems, so is this modeling strategy. You still have a chance to influence the model if you decide to run this in incremental modeling, and suggest to LLM what changes it should make.

Quick Start Guide

Prerequisites

Trying out the migration agent should be a simple process. We are assuming that you have:

Python
Git
Docker
MySQL or PostgresSQL running
Memgraph running

1. Installation

Next, clone the repository and synchronize the Python dependencies.

# Clone the repository
git clone https://github.com/memgraph/ai-toolkit.git
cd ai-toolkit/agents/sql2graph
 
# Install dependencies using uv
uv sync

The uv is being used to manage dependencies and to run the actuall project, so before this step, we assume you have uv installed. If you haven’t been exposed to the uv, it is much faster then pip.

2. Configuration

For the migration agent to understand from where it is moving the data and what system is being used, you need to pass the environment variables. Create a .env file with your database credentials. Here is a full list of .env variables you can change during the migration process. In particular:

SQL2MG_MODE will enable you to change the modeling approach. If you want to provide feedback, use incremental.
SQL2MG_STRATEGY will help you define the strategy.

3. Run the Migration

To run the migration based on the .env file, just run:

uv run main.py

Depending on the environment specification, the agent will interactively guide you through:

Environment validation
Mode selection
Strategy selection
Schema analysis
Graph model generation
Data migration
Validation

Wrapping Up

Migrating from relational to graph databases is now fully automated with the SQL2Graph Agent. It handles:

Schema analysis
Graph model generation
Index and constraint creation
Data migration

All of this is validated post migration.

Developers can rely on AI-driven modeling, combined with deterministic, rule-based strategies, to quickly convert relational data into fully queryable graph structures. At the same time, you still have a chance to drink your coffee!