terminusdb-migrations 0.1.0__tar.gz

terminusdb_migrations-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: terminusdb-migrations
+Version: 0.1.0
+Summary: Schema diff and migration automation for TerminusDB
+Project-URL: Source, https://gitlab.com/ed-tech6370840/terminusdb-migrations
+Project-URL: Issues, https://gitlab.com/ed-tech6370840/terminusdb-migrations/-/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: terminusdb-async<1.0.0,>=0.1.0
+Requires-Dist: terminusdb-pydantic<1.0.0,>=0.1.0
+
+# terminusdb-migrations
+
+Schema diff and migration planning for TerminusDB based on Pydantic models.
+
+## Development
+
+After `terminusdb-async` and `terminusdb-pydantic` 0.1.0 are available from
+PyPI:
+
+```bash
+uv sync --group dev
+uv run pytest
+uv build --no-sources
+```
+
+Dependencies are declared in `pyproject.toml` and managed with uv.
+
+The initial CI unit tests intentionally use an isolated uv environment until the
+two runtime packages have completed their first PyPI release.
+
+## Release
+
+A version tag such as `v0.1.0` publishes through PyPI Trusted Publishing with
+`uv publish`.

terminusdb_migrations-0.1.0/README.md

@@ -0,0 +1,24 @@
+# terminusdb-migrations
+
+Schema diff and migration planning for TerminusDB based on Pydantic models.
+
+## Development
+
+After `terminusdb-async` and `terminusdb-pydantic` 0.1.0 are available from
+PyPI:
+
+```bash
+uv sync --group dev
+uv run pytest
+uv build --no-sources
+```
+
+Dependencies are declared in `pyproject.toml` and managed with uv.
+
+The initial CI unit tests intentionally use an isolated uv environment until the
+two runtime packages have completed their first PyPI release.
+
+## Release
+
+A version tag such as `v0.1.0` publishes through PyPI Trusted Publishing with
+`uv publish`.

terminusdb_migrations-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terminusdb-migrations"
+version = "0.1.0"
+description = "Schema diff and migration automation for TerminusDB"
+requires-python = ">=3.11"
+readme = "README.md"
+dependencies = [
+  "terminusdb-async>=0.1.0,<1.0.0",
+  "terminusdb-pydantic>=0.1.0,<1.0.0",
+]
+
+[project.urls]
+Source = "https://gitlab.com/ed-tech6370840/terminusdb-migrations"
+Issues = "https://gitlab.com/ed-tech6370840/terminusdb-migrations/-/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+tdb-migrate = "terminusdb_migrations.cli:main"
+
+[tool.uv]
+package = true
+trusted-publishing = "always"
+
+[tool.setuptools.packages.find]
+where = ["src"]

terminusdb_migrations-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

terminusdb_migrations-0.1.0/src/terminusdb_migrations/__init__.py

@@ -0,0 +1,4 @@
+from .manager import MigrationManager
+from .plan import MigrationPlan
+
+__all__ = ["MigrationManager", "MigrationPlan"]

terminusdb_migrations-0.1.0/src/terminusdb_migrations/cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import os
+
+from terminusdb_async import AsyncTerminusClient
+
+from .manager import MigrationManager
+
+
+def _load_models(spec: str):
+    module_name, attr = spec.split(":", 1)
+    module = importlib.import_module(module_name)
+    return getattr(module, attr)
+
+
+async def _run(args):
+    models = _load_models(args.models)
+    async with AsyncTerminusClient(
+        args.url,
+        organization=args.org,
+        database=args.db,
+        branch=args.branch,
+        username=args.username,
+        password=args.password,
+        token=args.token,
+    ) as client:
+        manager = MigrationManager(client, models)
+        plan = await manager.plan()
+        print(plan.render())
+        if args.command == "apply":
+            await manager.apply(
+                plan,
+                author=args.author,
+                message=args.message,
+                dry_run=args.dry_run,
+                allow_destructive=args.allow_destructive,
+            )
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="tdb-migrate")
+    parser.add_argument("command", choices=["plan", "apply"])
+    parser.add_argument("--models", required=True, help="Python import path, e.g. app.models:MODELS")
+    parser.add_argument("--url", default=os.getenv("TERMINUSDB_URL", "http://localhost:6363"))
+    parser.add_argument("--org", default=os.getenv("TERMINUSDB_ORG", "admin"))
+    parser.add_argument("--db", required=True)
+    parser.add_argument("--branch", default="main")
+    parser.add_argument("--username", default=os.getenv("TERMINUSDB_USER"))
+    parser.add_argument("--password", default=os.getenv("TERMINUSDB_PASSWORD"))
+    parser.add_argument("--token", default=os.getenv("TERMINUSDB_TOKEN"))
+    parser.add_argument("--author", default="schema-bot")
+    parser.add_argument("--message", default="sync schema")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--allow-destructive", action="store_true")
+    args = parser.parse_args()
+    asyncio.run(_run(args))
+
+
+if __name__ == "__main__":
+    main()

terminusdb_migrations-0.1.0/src/terminusdb_migrations/manager.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from .plan import MigrationPlan
+
+if TYPE_CHECKING:
+    from terminusdb_async import AsyncTerminusClient
+
+
+class MigrationManager:
+    def __init__(self, client: "AsyncTerminusClient", models: Iterable[type[BaseModel]]):
+        self.client = client
+        self.models = list(models)
+
+    async def plan(self) -> MigrationPlan:
+        from terminusdb_pydantic import models_to_schema
+
+        current = await self.client.get_schema_documents()
+        desired = models_to_schema(self.models)
+        return diff_schema(current, desired)
+
+    async def apply(
+        self,
+        plan: MigrationPlan,
+        *,
+        author: str,
+        message: str,
+        dry_run: bool = False,
+        allow_destructive: bool = False,
+    ) -> Any:
+        if plan.destructive and not allow_destructive:
+            raise RuntimeError("Migration contains destructive changes; pass allow_destructive=True")
+
+        results: list[Any] = []
+        if plan.schema_documents:
+            if dry_run:
+                results.append({"schema_documents": plan.schema_documents, "dry_run": True})
+            else:
+                results.append(
+                    await self.client.insert_schema_documents(
+                        plan.schema_documents,
+                        author=author,
+                        message=message,
+                    )
+                )
+        if plan.operations:
+            results.append(
+                await self.client.migrate(
+                    plan.operations,
+                    author=author,
+                    message=message,
+                    dry_run=dry_run,
+                )
+            )
+        return results
+
+
+def diff_schema(current: list[dict[str, Any]], desired: list[dict[str, Any]]) -> MigrationPlan:
+    plan = MigrationPlan()
+    current_map = {d.get("@id"): d for d in current if d.get("@id")}
+    desired_map = {d.get("@id"): d for d in desired if d.get("@id")}
+
+    for ident, target in desired_map.items():
+        source = current_map.get(ident)
+        if source is None:
+            if target.get("@type") == "Enum":
+                plan.schema_documents.append(target)
+            else:
+                plan.operations.append({"@type": "CreateClass", "class": target})
+            continue
+
+        if target.get("@type") == "Enum" and source.get("@type") == "Enum":
+            old_values = list(source.get("@value", []))
+            new_values = list(target.get("@value", []))
+            added = [v for v in new_values if v not in old_values]
+            removed = [v for v in old_values if v not in new_values]
+            if added:
+                plan.operations.append({"@type": "ExpandEnum", "enum": ident, "values": added})
+            if removed:
+                plan.warnings.append(f"Enum {ident} removes values {removed}; manual migration required")
+                plan.destructive = True
+            continue
+
+        if target.get("@type") != "Class" or source.get("@type") != "Class":
+            continue
+
+        _diff_class(ident, source, target, plan)
+
+    for ident, source in current_map.items():
+        if ident not in desired_map and source.get("@type") in {"Class", "Enum"}:
+            plan.warnings.append(f"{source.get('@type')} {ident} exists in DB but not in models")
+            plan.destructive = True
+
+    return plan
+
+
+def _diff_class(name: str, source: dict[str, Any], target: dict[str, Any], plan: MigrationPlan) -> None:
+    metadata = {"@type", "@id", "@key", "@inherits", "@documentation", "@abstract", "@subdocument"}
+    old_props = {k: v for k, v in source.items() if k not in metadata}
+    new_props = {k: v for k, v in target.items() if k not in metadata}
+
+    for prop, prop_type in new_props.items():
+        if prop not in old_props:
+            if _is_optional(prop_type):
+                plan.operations.append(
+                    {"@type": "CreateClassProperty", "class": name, "property": prop, "type": prop_type}
+                )
+            else:
+                plan.warnings.append(
+                    f"{name}.{prop} is a new required property without a migration default"
+                )
+            continue
+
+        if old_props[prop] != prop_type:
+            plan.operations.append(
+                {
+                    "@type": "CastClassProperty",
+                    "class": name,
+                    "property": prop,
+                    "type": prop_type,
+                }
+            )
+
+    for prop in old_props:
+        if prop not in new_props:
+            plan.warnings.append(f"{name}.{prop} would be removed")
+            plan.destructive = True
+
+    if source.get("@key") != target.get("@key"):
+        plan.operations.append(
+            {"@type": "ChangeKey", "class": name, "key": target.get("@key", {"@type": "Random"})}
+        )
+        plan.destructive = True
+
+
+def _is_optional(value: Any) -> bool:
+    return isinstance(value, dict) and value.get("@type") == "Optional"

terminusdb_migrations-0.1.0/src/terminusdb_migrations/plan.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class MigrationPlan:
+    operations: list[dict[str, Any]] = field(default_factory=list)
+    schema_documents: list[dict[str, Any]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    destructive: bool = False
+
+    @property
+    def empty(self) -> bool:
+        return not self.operations and not self.schema_documents
+
+    def render(self) -> str:
+        lines: list[str] = []
+        for doc in self.schema_documents:
+            lines.append(f"+ schema {doc.get('@type')} {doc.get('@id')}")
+        for op in self.operations:
+            lines.append(f"+ {op.get('@type')}: {op}")
+        if self.warnings:
+            lines.append("")
+            lines.extend(f"! {warning}" for warning in self.warnings)
+        if not lines:
+            return "No schema changes."
+        return "\n".join(lines)

terminusdb_migrations-0.1.0/src/terminusdb_migrations.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: terminusdb-migrations
+Version: 0.1.0
+Summary: Schema diff and migration automation for TerminusDB
+Project-URL: Source, https://gitlab.com/ed-tech6370840/terminusdb-migrations
+Project-URL: Issues, https://gitlab.com/ed-tech6370840/terminusdb-migrations/-/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: terminusdb-async<1.0.0,>=0.1.0
+Requires-Dist: terminusdb-pydantic<1.0.0,>=0.1.0
+
+# terminusdb-migrations
+
+Schema diff and migration planning for TerminusDB based on Pydantic models.
+
+## Development
+
+After `terminusdb-async` and `terminusdb-pydantic` 0.1.0 are available from
+PyPI:
+
+```bash
+uv sync --group dev
+uv run pytest
+uv build --no-sources
+```
+
+Dependencies are declared in `pyproject.toml` and managed with uv.
+
+The initial CI unit tests intentionally use an isolated uv environment until the
+two runtime packages have completed their first PyPI release.
+
+## Release
+
+A version tag such as `v0.1.0` publishes through PyPI Trusted Publishing with
+`uv publish`.

terminusdb_migrations-0.1.0/src/terminusdb_migrations.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/terminusdb_migrations/__init__.py
+src/terminusdb_migrations/cli.py
+src/terminusdb_migrations/manager.py
+src/terminusdb_migrations/plan.py
+src/terminusdb_migrations.egg-info/PKG-INFO
+src/terminusdb_migrations.egg-info/SOURCES.txt
+src/terminusdb_migrations.egg-info/dependency_links.txt
+src/terminusdb_migrations.egg-info/entry_points.txt
+src/terminusdb_migrations.egg-info/requires.txt
+src/terminusdb_migrations.egg-info/top_level.txt
+tests/test_diff.py

terminusdb_migrations-0.1.0/src/terminusdb_migrations.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

terminusdb_migrations-0.1.0/src/terminusdb_migrations.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tdb-migrate = terminusdb_migrations.cli:main

terminusdb_migrations-0.1.0/src/terminusdb_migrations.egg-info/requires.txt

@@ -0,0 +1,2 @@
+terminusdb-async<1.0.0,>=0.1.0
+terminusdb-pydantic<1.0.0,>=0.1.0

terminusdb_migrations-0.1.0/src/terminusdb_migrations.egg-info/top_level.txt

@@ -0,0 +1 @@
+terminusdb_migrations

terminusdb_migrations-0.1.0/tests/test_diff.py

@@ -0,0 +1,45 @@
+from terminusdb_migrations.manager import diff_schema
+
+
+def test_add_optional_property():
+    current = [
+        {
+            "@type": "Class",
+            "@id": "Discipline",
+            "@key": {"@type": "Random"},
+            "name": "xsd:string",
+        }
+    ]
+    desired = [
+        {
+            "@type": "Class",
+            "@id": "Discipline",
+            "@key": {"@type": "Random"},
+            "name": "xsd:string",
+            "description": {"@type": "Optional", "@class": "xsd:string"},
+        }
+    ]
+    plan = diff_schema(current, desired)
+    assert plan.operations == [
+        {
+            "@type": "CreateClassProperty",
+            "class": "Discipline",
+            "property": "description",
+            "type": {"@type": "Optional", "@class": "xsd:string"},
+        }
+    ]
+
+
+def test_expand_enum():
+    current = [{"@type": "Enum", "@id": "Level", "@value": ["bachelor"]}]
+    desired = [{"@type": "Enum", "@id": "Level", "@value": ["bachelor", "master"]}]
+    plan = diff_schema(current, desired)
+    assert plan.operations[0]["@type"] == "ExpandEnum"
+    assert plan.operations[0]["values"] == ["master"]
+
+
+def test_remove_property_is_destructive():
+    current = [{"@type": "Class", "@id": "X", "@key": {"@type": "Random"}, "a": "xsd:string"}]
+    desired = [{"@type": "Class", "@id": "X", "@key": {"@type": "Random"}}]
+    plan = diff_schema(current, desired)
+    assert plan.destructive