​
Load Your Relational Database

Difficulty: Easy

​
Overview

Migrating your relational data to a graph can open up new ways to explore and search your data—with minimal code changes using cognee’s built-in ingestion tasks. Below is a simple tutorial on how to migrate a relational database into cognee’s graph engine. We’ll walk through the setup—using SQLite as the source relational database, and Kuzu as the graph database. At the end, we’ll cover how to switch to Postgres. cognee provides functionality to:
  1. Connect to a relational database (e.g. SQLite, Postgres).
  2. Extract the schema and data.
  3. Migrate tables and relationships into a graph structure.
  4. Store the new graph in a robust graph DB like Neo4j or Kuzu.
Once migrated, you can run queries or semantic searches (using the cognee.search API) against your newly formed knowledge graph.

​
Troubleshooting and Tips

  1. Foreign Keys: Only actual foreign key constraints in your relational DB become edges in the graph.
  2. Case Sensitivity: Note that entity naming is derived from your DB tables/rows.
  3. Environment Variables: Make sure .env is loaded or environment variables are otherwise set so that get_migration_relational_engine() and get_graph_engine() can pick them up.

​
Using Postgres Instead

If you want to migrate from Postgres as your relational DB:
  1. Change your .env to: 
    MIGRATION_DB_PROVIDER=postgres
MIGRATION_DB_NAME=my_postgres_db 
MIGRATION_DB_HOST=127.0.0.1
MIGRATION_DB_PORT=5432
MIGRATION_DB_USERNAME=cognee
MIGRATION_DB_PASSWORD=cognee
  2. Make sure your Postgres instance is running and that your user can connect to my_postgres_db.
  3. Run the same migration code. The main difference is MIGRATION_DB_PROVIDER=postgres, so get_migration_relational_engine() connects to your Postgres DB.
Everything else is the same. If you have the Chinook schema in Postgres, it will be migrated to the graph.

​
Using Neo4j or Kuzu as the Graph DB

If you want a more robust or persistent graph database, check out our Configuration guide.

​
Conclusion

  • SQLite + Kuzu is the simplest configuration (no external DB servers needed).
  • To switch to more production-level databases (Postgres → Neo4j, etc.), adjust .env accordingly.
  • The main migration code stays the same: extract_schema(), then migrate_relational_database().
With that, you should be able to ingest your own relational data and explore it in a graph format with cognee. Happy coding!