runic-migrate 0.1.0__py3-none-any.whl

runic/__init__.py

@@ -0,0 +1,33 @@
+from runic import context
+from runic.context import IrreversibleMigrationError
+from runic.exceptions import MultipleBasesError, MultipleHeadsError
+from runic.manifest import (
+    FulltextIndex,
+    MandatoryConstraint,
+    RangeIndex,
+    SchemaManifest,
+    UniqueConstraint,
+    VectorIndex,
+)
+from runic.operations import ConstraintFailedError, ConstraintTimeoutError, op
+from runic.script import AmbiguousRevision, RevisionNotFound
+from runic.service import RunicService
+
+__all__ = [
+    "AmbiguousRevision",
+    "ConstraintFailedError",
+    "ConstraintTimeoutError",
+    "FulltextIndex",
+    "IrreversibleMigrationError",
+    "MandatoryConstraint",
+    "MultipleBasesError",
+    "MultipleHeadsError",
+    "RangeIndex",
+    "RevisionNotFound",
+    "RunicService",
+    "SchemaManifest",
+    "UniqueConstraint",
+    "VectorIndex",
+    "context",
+    "op",
+]

runic/adapters/__init__.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from runic.introspect import LiveSchema
+
+
+@runtime_checkable
+class GraphAdapter(Protocol):
+    """Protocol all graph-database adapters must satisfy.
+
+    The runic core depends only on this interface — no FalkorDB or any other
+    concrete database client leaks into shared code.
+    """
+
+    @property
+    def name(self) -> str: ...
+
+    # Low-level query execution
+    def run_query(self, query: str, params: dict | None = None) -> Any: ...
+    def run_ro_query(self, query: str) -> Any: ...
+
+    # Version tracking
+    def get_version(self) -> list[str]: ...
+    def set_version(self, revisions: list[str]) -> None: ...
+
+    # Schema introspection
+    def read_live_schema(self) -> LiveSchema: ...
+
+    # Schema DDL
+    def create_range_index(
+        self, label: str, prop: str, *, rel: bool = False
+    ) -> None: ...
+    def drop_range_index(self, label: str, prop: str, *, rel: bool = False) -> None: ...
+    def create_fulltext_index(
+        self,
+        label: str,
+        *props: str,
+        language: str | None = None,
+        stopwords: list[str] | None = None,
+    ) -> None: ...
+    def drop_fulltext_index(self, label: str, *props: str) -> None: ...
+    def create_vector_index(
+        self,
+        label: str,
+        prop: str,
+        dimension: int,
+        similarity: str,
+        *,
+        m: int = 16,
+        ef_construction: int = 200,
+        ef_runtime: int = 10,
+    ) -> None: ...
+    def drop_vector_index(self, label: str, prop: str) -> None: ...
+    def create_constraint(
+        self, kind: str, entity: str, label: str, props: list[str]
+    ) -> None: ...
+    def drop_constraint(
+        self, kind: str, entity: str, label: str, props: list[str]
+    ) -> None: ...
+
+    # Snapshots
+    def snapshot(self, snap_name: str) -> None: ...
+    def restore_snapshot(self, snap_name: str) -> None: ...
+    def snapshot_exists(self, snap_name: str) -> bool: ...
+
+
+__all__ = ["GraphAdapter"]

runic/adapters/falkordb.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from runic import introspect
+from runic.adapters import GraphAdapter
+from runic.introspect import LiveSchema
+
+log = logging.getLogger(__name__)
+
+_POLL_RETRIES = 30
+_POLL_INTERVAL = 0.5
+
+_VERSION_LABEL = "_FalkorMigrateVersion"
+_GET_VERSION_QUERY = f"MATCH (v:{_VERSION_LABEL}) RETURN v.revisions, v.revision"
+_SET_VERSION_QUERY = (
+    f"MERGE (v:{_VERSION_LABEL} {{singleton: true}})"
+    " SET v.revisions = $revisions, v.applied_at = timestamp()"
+)
+
+
+class ConstraintFailedError(Exception):
+    pass
+
+
+class ConstraintTimeoutError(Exception):
+    pass
+
+
+class FalkorDBAdapter(GraphAdapter):
+    """GraphAdapter implementation for FalkorDB (standalone or embedded via falkordblite)."""
+
+    def __init__(self, db: Any, graph: Any) -> None:
+        self._db = db
+        self._graph = graph
+
+    @classmethod
+    def from_url(cls, url: str, graph_name: str) -> FalkorDBAdapter:
+        from falkordb import FalkorDB
+
+        db = FalkorDB.from_url(url)
+        return cls(db, db.select_graph(graph_name))
+
+    def fork(self, graph_name: str) -> FalkorDBAdapter:
+        """Return a sibling adapter on the same connection for a different graph name."""
+        return FalkorDBAdapter(self._db, self._db.select_graph(graph_name))
+
+    # ------------------------------------------------------------------
+    # GraphAdapter Protocol
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return self._graph.name  # type: ignore[no-any-return]
+
+    def run_query(self, query: str, params: dict | None = None) -> Any:
+        return self._graph.query(query, params) if params else self._graph.query(query)
+
+    def run_ro_query(self, query: str) -> Any:
+        return self._graph.ro_query(query)
+
+    # ------------------------------------------------------------------
+    # Version tracking
+    # ------------------------------------------------------------------
+
+    def get_version(self) -> list[str]:
+        try:
+            result = self._graph.ro_query(_GET_VERSION_QUERY)
+        except Exception as exc:
+            if "empty key" in str(exc).lower():
+                return []
+            raise
+        rows = result.result_set
+        if not rows:
+            return []
+        row = rows[0]
+        col0 = row[0]
+        col1 = row[1] if len(row) > 1 else None
+
+        if isinstance(col0, list):
+            return [r for r in col0 if r is not None]
+        if isinstance(col0, str):
+            return [col0]
+        if isinstance(col1, str):
+            return [col1]
+        return []
+
+    def set_version(self, revisions: list[str]) -> None:
+        log.info("stamping versions: %s", revisions)
+        self._graph.query(_SET_VERSION_QUERY, {"revisions": revisions})
+
+    # ------------------------------------------------------------------
+    # Schema introspection
+    # ------------------------------------------------------------------
+
+    def read_live_schema(self) -> LiveSchema:
+        return introspect.read_live_schema(self._graph)
+
+    # ------------------------------------------------------------------
+    # Schema DDL — range indexes
+    # ------------------------------------------------------------------
+
+    def create_range_index(self, label: str, prop: str, *, rel: bool = False) -> None:
+        if rel:
+            query = f"CREATE INDEX FOR ()-[r:{label}]->() ON (r.{prop})"
+        else:
+            query = f"CREATE INDEX FOR (n:{label}) ON (n.{prop})"
+        log.info("creating range index on %s.%s", label, prop)
+        self._graph.query(query)
+
+    def drop_range_index(self, label: str, prop: str, *, rel: bool = False) -> None:  # noqa: ARG002
+        query = f"DROP INDEX ON :{label}({prop})"
+        log.info("dropping range index on %s.%s", label, prop)
+        self._graph.query(query)
+
+    # ------------------------------------------------------------------
+    # Schema DDL — fulltext indexes
+    # ------------------------------------------------------------------
+
+    def create_fulltext_index(
+        self,
+        label: str,
+        *props: str,
+        language: str | None = None,
+        stopwords: list[str] | None = None,
+    ) -> None:
+        if language or stopwords:
+            map_parts = [f"label: '{label}'"]
+            if language:
+                map_parts.append(f"language: '{language}'")
+            if stopwords:
+                sw = "[" + ", ".join(f"'{w}'" for w in stopwords) + "]"
+                map_parts.append(f"stopwords: {sw}")
+            map_literal = "{" + ", ".join(map_parts) + "}"
+            props_str = ", ".join(f"'{p}'" for p in props)
+            query = f"CALL db.idx.fulltext.createNodeIndex({map_literal}, {props_str})"
+        else:
+            props_str = ", ".join(f"'{p}'" for p in props)
+            query = f"CALL db.idx.fulltext.createNodeIndex('{label}', {props_str})"
+        log.info("creating fulltext index on %s %s", label, list(props))
+        self._graph.query(query)
+
+    def drop_fulltext_index(self, label: str, *props: str) -> None:
+        log.info("dropping fulltext index on %s %s", label, list(props))
+        for prop in props:
+            query = f"DROP FULLTEXT INDEX FOR (n:{label}) ON (n.{prop})"
+            self._graph.query(query)
+
+    # ------------------------------------------------------------------
+    # Schema DDL — vector indexes
+    # ------------------------------------------------------------------
+
+    def create_vector_index(
+        self,
+        label: str,
+        prop: str,
+        dimension: int,
+        similarity: str,
+        *,
+        m: int = 16,
+        ef_construction: int = 200,
+        ef_runtime: int = 10,
+    ) -> None:
+        options = (
+            f"{{dimension: {dimension}, similarityFunction: '{similarity}', "
+            f"M: {m}, efConstruction: {ef_construction}, efRuntime: {ef_runtime}}}"
+        )
+        query = f"CREATE VECTOR INDEX FOR (n:{label}) ON (n.{prop}) OPTIONS {options}"
+        log.info("creating vector index on %s.%s", label, prop)
+        self._graph.query(query)
+
+    def drop_vector_index(self, label: str, prop: str) -> None:
+        query = f"DROP VECTOR INDEX FOR (n:{label}) (n.{prop})"
+        log.info("dropping vector index on %s.%s", label, prop)
+        self._graph.query(query)
+
+    # ------------------------------------------------------------------
+    # Schema DDL — constraints
+    # ------------------------------------------------------------------
+
+    def create_constraint(
+        self, kind: str, entity: str, label: str, props: list[str]
+    ) -> None:
+        if kind == "UNIQUE":
+            for prop in props:
+                self.create_range_index(label, prop)
+        prop_count = str(len(props))
+        log.info("creating %s constraint on %s %s %s", kind, entity, label, props)
+        self._db.execute_command(
+            "GRAPH.CONSTRAINT",
+            "CREATE",
+            label,
+            kind,
+            entity,
+            label,
+            "PROPERTIES",
+            prop_count,
+            *props,
+        )
+        self._poll_constraint(label, props)
+
+    def _poll_constraint(self, label: str, props: list[str]) -> None:
+        for _ in range(_POLL_RETRIES):
+            result = self._graph.ro_query("CALL db.constraints()")
+            for row in result.result_set:
+                entry = row[0]
+                status = entry[4] if isinstance(entry, (list, tuple)) else str(entry)
+                if status == "FAILED":
+                    raise ConstraintFailedError(f"constraint on {label}.{props} failed")
+                if status == "OPERATIONAL":
+                    return
+            time.sleep(_POLL_INTERVAL)
+        raise ConstraintTimeoutError(
+            f"constraint on {label}.{props} did not become OPERATIONAL"
+        )
+
+    def drop_constraint(
+        self, kind: str, entity: str, label: str, props: list[str]
+    ) -> None:
+        prop_count = str(len(props))
+        log.info("dropping %s constraint on %s %s %s", kind, entity, label, props)
+        self._db.execute_command(
+            "GRAPH.CONSTRAINT",
+            "DROP",
+            label,
+            kind,
+            entity,
+            label,
+            "PROPERTIES",
+            prop_count,
+            *props,
+        )
+
+    # ------------------------------------------------------------------
+    # Snapshots
+    # ------------------------------------------------------------------
+
+    def snapshot(self, snap_name: str) -> None:
+        # GRAPH.COPY fails on an empty key; initialize graph if it doesn't exist yet
+        if self._graph.name not in self._db.list_graphs():
+            self._graph.query("RETURN 1")
+        self._graph.copy(snap_name)
+        log.debug("snapshot taken: %s → %s", self._graph.name, snap_name)
+
+    def restore_snapshot(self, snap_name: str) -> None:
+        snap_graph = self._db.select_graph(snap_name)
+        self._graph.delete()
+        snap_graph.copy(self._graph.name)
+        snap_graph.delete()
+        log.debug("snapshot restored: %s → %s", snap_name, self._graph.name)
+
+    def snapshot_exists(self, snap_name: str) -> bool:
+        return snap_name in self._db.list_graphs()
+
+    def delete_graph(self) -> None:
+        """Delete the underlying graph (used for ephemeral test cleanup)."""
+        self._graph.delete()

runic/autogen.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from runic.introspect import LiveSchema
+from runic.manifest import (
+    FulltextIndex,
+    MandatoryConstraint,
+    RangeIndex,
+    SchemaManifest,
+    UniqueConstraint,
+    VectorIndex,
+)
+
+log = logging.getLogger(__name__)
+
+_AUTOGEN_COMMENT = "    # AUTOGENERATED — review before applying; cannot detect renames"
+
+
+@dataclass
+class DiffOp:
+    action: Literal["create", "drop"]
+    op_call: str
+    inverse_call: str
+
+
+# ---------------------------------------------------------------------------
+# Canonical key helpers
+# ---------------------------------------------------------------------------
+
+
+def _range_key(idx: RangeIndex) -> tuple:
+    entity = "RELATIONSHIP" if idx.rel else "NODE"
+    return ("range", entity, idx.label, idx.prop)
+
+
+def _fulltext_key(idx: FulltextIndex) -> tuple:
+    return ("fulltext", "NODE", idx.label, idx.props)
+
+
+def _vector_key(idx: VectorIndex) -> tuple:
+    return ("vector", "NODE", idx.label, idx.prop)
+
+
+def _constraint_key(c: UniqueConstraint | MandatoryConstraint) -> tuple:
+    kind = "UNIQUE" if isinstance(c, UniqueConstraint) else "MANDATORY"
+    return (kind, c.entity, c.label, c.props)
+
+
+# ---------------------------------------------------------------------------
+# op call renderers
+# ---------------------------------------------------------------------------
+
+
+def _range_create(idx: RangeIndex) -> str:
+    rel_arg = ", rel=True" if idx.rel else ""
+    return f'op.create_range_index("{idx.label}", "{idx.prop}"{rel_arg})'
+
+
+def _range_drop(idx: RangeIndex) -> str:
+    rel_arg = ", rel=True" if idx.rel else ""
+    return f'op.drop_range_index("{idx.label}", "{idx.prop}"{rel_arg})'
+
+
+def _fulltext_create(idx: FulltextIndex) -> str:
+    props_args = ", ".join(f'"{p}"' for p in idx.props)
+    extra: list[str] = []
+    if idx.language:
+        extra.append(f'language="{idx.language}"')
+    if idx.stopwords:
+        sw = "[" + ", ".join(f'"{w}"' for w in idx.stopwords) + "]"
+        extra.append(f"stopwords={sw}")
+    extra_str = (", " + ", ".join(extra)) if extra else ""
+    return f'op.create_fulltext_index("{idx.label}", {props_args}{extra_str})'
+
+
+def _fulltext_drop(idx: FulltextIndex) -> str:
+    props_args = ", ".join(f'"{p}"' for p in idx.props)
+    return f'op.drop_fulltext_index("{idx.label}", {props_args})'
+
+
+def _vector_create(idx: VectorIndex) -> str:
+    return (
+        f'op.create_vector_index("{idx.label}", "{idx.prop}", '
+        f'{idx.dimension}, "{idx.similarity}", '
+        f"m={idx.m}, ef_construction={idx.ef_construction}, ef_runtime={idx.ef_runtime})"
+    )
+
+
+def _vector_drop(idx: VectorIndex) -> str:
+    return f'op.drop_vector_index("{idx.label}", "{idx.prop}")'
+
+
+def _constraint_create(c: UniqueConstraint | MandatoryConstraint) -> str:
+    kind = "UNIQUE" if isinstance(c, UniqueConstraint) else "MANDATORY"
+    props_repr = "[" + ", ".join(f'"{p}"' for p in c.props) + "]"
+    return f'op.create_constraint("{kind}", "{c.entity}", "{c.label}", {props_repr})'
+
+
+def _constraint_drop(c: UniqueConstraint | MandatoryConstraint) -> str:
+    kind = "UNIQUE" if isinstance(c, UniqueConstraint) else "MANDATORY"
+    props_repr = "[" + ", ".join(f'"{p}"' for p in c.props) + "]"
+    return f'op.drop_constraint("{kind}", "{c.entity}", "{c.label}", {props_repr})'
+
+
+# ---------------------------------------------------------------------------
+# Diff engine
+# ---------------------------------------------------------------------------
+
+
+def diff_schema(manifest: SchemaManifest, live: LiveSchema) -> list[DiffOp]:
+    ops: list[DiffOp] = []
+
+    # Build manifest lookup by canonical key
+    manifest_range: dict[tuple, RangeIndex] = {
+        _range_key(i): i for i in manifest.range_indexes
+    }
+    manifest_fulltext: dict[tuple, FulltextIndex] = {
+        _fulltext_key(i): i for i in manifest.fulltext_indexes
+    }
+    manifest_vector: dict[tuple, VectorIndex] = {
+        _vector_key(i): i for i in manifest.vector_indexes
+    }
+    manifest_constraints: dict[tuple, Any] = {
+        _constraint_key(c): c for c in manifest.constraints
+    }
+
+    live_range: dict[tuple, RangeIndex] = {_range_key(i): i for i in live.range_indexes}
+    live_fulltext: dict[tuple, FulltextIndex] = {
+        _fulltext_key(i): i for i in live.fulltext_indexes
+    }
+    live_vector: dict[tuple, VectorIndex] = {
+        _vector_key(i): i for i in live.vector_indexes
+    }
+    live_constraints: dict[tuple, Any] = {
+        _constraint_key(c): c for c in live.constraints
+    }
+
+    # --- DROP ops (live - manifest) ---
+    # Drop order: constraints first (before their backing indexes), then indexes
+
+    # Drop constraints not in manifest
+    for key, c in live_constraints.items():
+        if key not in manifest_constraints:
+            ops.append(
+                DiffOp(
+                    action="drop",
+                    op_call=_constraint_drop(c),
+                    inverse_call=_constraint_create(c),
+                )
+            )
+
+    # Drop indexes not in manifest
+    for key, idx in live_range.items():
+        if key not in manifest_range:
+            ops.append(
+                DiffOp(
+                    action="drop",
+                    op_call=_range_drop(idx),
+                    inverse_call=_range_create(idx),
+                )
+            )
+    for key, idx in live_fulltext.items():
+        if key not in manifest_fulltext:
+            ops.append(
+                DiffOp(
+                    action="drop",
+                    op_call=_fulltext_drop(idx),
+                    inverse_call=_fulltext_create(idx),
+                )
+            )
+    for key, idx in live_vector.items():
+        if key not in manifest_vector:
+            ops.append(
+                DiffOp(
+                    action="drop",
+                    op_call=_vector_drop(idx),
+                    inverse_call=_vector_create(idx),
+                )
+            )
+
+    # --- CREATE ops (manifest - live) ---
+    # Create order: indexes first (UNIQUE constraint requires prior range index), then constraints
+
+    for key, idx in manifest_range.items():
+        if key not in live_range:
+            ops.append(
+                DiffOp(
+                    action="create",
+                    op_call=_range_create(idx),
+                    inverse_call=_range_drop(idx),
+                )
+            )
+    for key, idx in manifest_fulltext.items():
+        if key not in live_fulltext:
+            ops.append(
+                DiffOp(
+                    action="create",
+                    op_call=_fulltext_create(idx),
+                    inverse_call=_fulltext_drop(idx),
+                )
+            )
+    for key, idx in manifest_vector.items():
+        if key not in live_vector:
+            ops.append(
+                DiffOp(
+                    action="create",
+                    op_call=_vector_create(idx),
+                    inverse_call=_vector_drop(idx),
+                )
+            )
+    for key, c in manifest_constraints.items():
+        if key not in live_constraints:
+            ops.append(
+                DiffOp(
+                    action="create",
+                    op_call=_constraint_create(c),
+                    inverse_call=_constraint_drop(c),
+                )
+            )
+
+    log.debug("autogen diff: %d ops", len(ops))
+    return ops
+
+
+# ---------------------------------------------------------------------------
+# Body renderers
+# ---------------------------------------------------------------------------
+
+
+def render_upgrade_body(ops: list[DiffOp]) -> str:
+    lines = [_AUTOGEN_COMMENT]
+    lines.extend(f"    {op.op_call}" for op in ops)
+    return "\n".join(lines)
+
+
+def render_downgrade_body(ops: list[DiffOp]) -> str:
+    lines = [_AUTOGEN_COMMENT]
+    lines.extend(f"    {op.inverse_call}" for op in reversed(ops))
+    return "\n".join(lines)