runic-migrate

name: runic-migrate description: | Expert guide for runic — an Alembic-style graph schema migration tool that supports FalkorDB, Memgraph, Neo4j, ArcadeDB, and Apache AGE. Use whenever the user works with runic: CLI commands, migration file anatomy, op.* API, env.py config, autogenerate, branching/merge, or testing. Invoke for any versions/*.py file, runic CLI question, or graph schema change task.

Runic — Graph Schema Migration Tool

Runic is an Alembic-style migration framework for graph databases (FalkorDB, Memgraph, Neo4j, ArcadeDB, Apache AGE). It tracks schema versions in a version node inside each graph and drives upgrades/downgrades via Python scripts stored in versions/.

• FalkorDB version node label: (:_FalkorMigrateVersion)
• All other backends: (:_RunicMigrateVersion)

For real migration file examples see examples/. For the full op.* API and SchemaManifest see references/op-api.md. For autogenerate, programmatic SDK, testing, and branching see references/advanced.md. For the initial migration workflow (dev bootstrap → baseline → production) see references/initial-migration.md. For annotated migration patterns (rename, relabel, seed, constraint guard) see references/migration-patterns.md.

Quick-start

pip install runic          # or: uv add runic

runic init                 # scaffold runic/ directory
# edit runic/env.py to point at your graph database instance
runic revision -m "create user index"
# edit the generated versions/*.py (see examples/ for patterns)
runic upgrade head

Directory layout (after runic init)

runic/
├── env.py            # executed on every CLI call; configures adapter + context
├── script.py.mako    # Mako template for new revision files
└── versions/
    ├── .gitkeep
    └── <rev_id>_<slug>.py

Default config: runic/env.py — override with --config path/to/env.py.

When you init to a non-default location, runic writes a .runic file in the working directory containing the path to env.py. Subsequent commands use this as a fallback when the default runic/env.py does not exist. Commit .runic.

env.py

import os
from runic.migrate import context
from runic.migrate.adapters import create_adapter

adapter = create_adapter(
    "falkordb",
    url=os.getenv("FALKORDB_URL", "falkor://localhost:6379"),
    graph_name=os.getenv("FALKORDB_GRAPH", "my_graph"),
)
context.configure(adapter)

For autogenerate/check, add target_manifest — see references/advanced.md.

CLI reference

Relative targets: +1 / +2 (upgrade N steps), -1 / -2 (downgrade N steps).

Migration file anatomy

"""create user email index

Revision ID: 1975ea83b712
Revises: None
Create Date: 2026-05-30T14:00:00+00:00
"""
from datetime import UTC, datetime

message = "create user email index"
create_date = datetime.fromisoformat("2026-05-30T14:00:00+00:00")

revision = "1975ea83b712"
down_revision = None       # None = base; str = parent id; tuple = merge revision
branch_labels = []
depends_on = []
irreversible = False       # True → refuse downgrade unless --force
snapshot = False           # True → GRAPH.COPY before upgrade; restore on failure


def upgrade(op) -> None:
    op.create_range_index("User", "email")
    op.create_constraint("UNIQUE", "NODE", "User", ["email"])


def downgrade(op) -> None:
    op.drop_constraint("UNIQUE", "NODE", "User", ["email"])  # constraint BEFORE index
    op.drop_range_index("User", "email")

Key rules:

• Drop constraints before dropping their backing range index in downgrade.
• Create the range index before a unique constraint on the same property in upgrade.
• Use irreversible = True for one-way data migrations (e.g. rename + drop old property).
• Use snapshot = True for risky data migrations; runic GRAPH.COPYs before upgrade and restores on failure/downgrade.
• Keep every data step idempotent — use MERGE / guarded WHERE … IS NULL writes; graph databases have no multi-statement transactions.

For the full op.* API signatures, see references/op-api.md.