muscles-migrations 0.2.1__tar.gz

muscles_migrations-0.2.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: muscles-migrations
+Version: 0.2.1
+Summary: Storage-independent migration orchestration for Muscles
+Project-URL: Homepage, https://github.com/butkoden/muscles-migrations
+Project-URL: Repository, https://github.com/butkoden/muscles-migrations
+Project-URL: Documentation, https://github.com/butkoden/muscles-migrations#readme
+Project-URL: Releases, https://github.com/butkoden/muscles-migrations/releases
+Requires-Python: >=3.10
+Requires-Dist: muscles-data<1.0.0,>=0.2.0
+Provides-Extra: redis
+Requires-Dist: muscles-data-redis<1.0.0,>=0.2.0; extra == "redis"
+Provides-Extra: mongodb
+Requires-Dist: muscles-data-mongodb<1.0.0,>=0.2.0; extra == "mongodb"

muscles_migrations-0.2.1/README.md

@@ -0,0 +1,49 @@
+# muscles-migrations
+
+Compatibility package: new code should import the registry and source contracts
+from `muscles-data`. SQL migration backends live in `muscles-data-sql`; Redis and
+MongoDB backends live in their respective data adapter packages. This package
+keeps legacy imports available for existing projects. See
+`muscles-data/docs/migrations.en.md` for discovery, command integration, locks
+and migration history.
+
+Register migration sources with a backend implementing `upgrade(target)`.
+The registry validates dependencies before applying sources in dependency order.
+Backends own their version tracking, concurrency handling and rollback semantics.
+
+```python
+import os
+
+from muscles.data import MigrationRegistry, MigrationSource, discover_migration_modules
+from muscles.data.sql.native_migrations import NativeSqlMigration, NativeSqlMigrationSourceBackend
+
+registry = MigrationRegistry()
+modules = discover_migration_modules("myapp.migrations")
+migrations = [NativeSqlMigration.from_module(module) for module in modules]
+registry.register(MigrationSource(
+    name="accounts",
+    backend=NativeSqlMigrationSourceBackend(
+        os.environ["DATABASE_URL"], "accounts", migrations
+    ),
+))
+registry.upgrade()
+```
+
+`DATABASE_URL` must point to a SQLite or PostgreSQL database supported by the
+native SQL migration backend. The application should create one registry in
+its composition root and pass it to its CLI/runtime integration; packages
+should not create duplicate registries or connection managers.
+
+## Experimental Redis and MongoDB backends
+
+Redis and MongoDB migration backends are provided by their respective data
+adapter packages. Their backend configuration and migration object types are
+owned by those adapters; the shared registry contract remains in `muscles-data`.
+
+Locks deliberately do not expire: an expired lease could allow a second runner
+to overlap a long-running migration. If a process dies, an operator must first
+confirm it is no longer running and inspect the migration state before manually
+clearing the lock. A migration left in `running` requires manual recovery; it is
+never automatically retried. The backing journal must itself be durable and
+protected against eviction or deletion.
+Repository: https://github.com/butkoden/muscles-migrations

muscles_migrations-0.2.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "muscles-migrations"
+version = "0.2.1"
+description = "Storage-independent migration orchestration for Muscles"
+requires-python = ">=3.10"
+dependencies = ["muscles-data>=0.2.0,<1.0.0"]
+
+[project.optional-dependencies]
+redis = ["muscles-data-redis>=0.2.0,<1.0.0"]
+mongodb = ["muscles-data-mongodb>=0.2.0,<1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/butkoden/muscles-migrations"
+Repository = "https://github.com/butkoden/muscles-migrations"
+Documentation = "https://github.com/butkoden/muscles-migrations#readme"
+Releases = "https://github.com/butkoden/muscles-migrations/releases"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["muscles.migrations*"]

muscles_migrations-0.2.1/setup.cfg

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

muscles_migrations-0.2.1/src/muscles/migrations/__init__.py

@@ -0,0 +1,5 @@
+"""Compatibility exports; migration orchestration lives in muscles-data."""
+
+from muscles.data.migrations import MigrationBackend, MigrationRegistry, MigrationSource
+
+__all__ = ["MigrationBackend", "MigrationRegistry", "MigrationSource"]

muscles_migrations-0.2.1/src/muscles/migrations/native.py

@@ -0,0 +1,13 @@
+"""Compatibility imports for optional backend-specific migration packages."""
+
+__all__ = ["RedisJournal", "RedisMigrationBackend", "MongoJournal", "MongoMigrationBackend"]
+
+
+def __getattr__(name):
+    if name in {"RedisJournal", "RedisMigrationBackend"}:
+        from muscles.data.redis import migrations
+        return getattr(migrations, name)
+    if name in {"MongoJournal", "MongoMigrationBackend"}:
+        from muscles.data.mongodb import migrations
+        return getattr(migrations, name)
+    raise AttributeError(name)

muscles_migrations-0.2.1/src/muscles/migrations/versioned.py

@@ -0,0 +1,6 @@
+"""Compatibility imports for the shared versioned migration contract."""
+from muscles.data.versioned_migrations import (
+    Migration, MigrationJournal, MigrationStateError, VersionedMigrationBackend,
+)
+
+__all__ = ["Migration", "MigrationJournal", "MigrationStateError", "VersionedMigrationBackend"]

muscles_migrations-0.2.1/src/muscles_migrations.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: muscles-migrations
+Version: 0.2.1
+Summary: Storage-independent migration orchestration for Muscles
+Project-URL: Homepage, https://github.com/butkoden/muscles-migrations
+Project-URL: Repository, https://github.com/butkoden/muscles-migrations
+Project-URL: Documentation, https://github.com/butkoden/muscles-migrations#readme
+Project-URL: Releases, https://github.com/butkoden/muscles-migrations/releases
+Requires-Python: >=3.10
+Requires-Dist: muscles-data<1.0.0,>=0.2.0
+Provides-Extra: redis
+Requires-Dist: muscles-data-redis<1.0.0,>=0.2.0; extra == "redis"
+Provides-Extra: mongodb
+Requires-Dist: muscles-data-mongodb<1.0.0,>=0.2.0; extra == "mongodb"

muscles_migrations-0.2.1/src/muscles_migrations.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/muscles/migrations/__init__.py
+src/muscles/migrations/native.py
+src/muscles/migrations/versioned.py
+src/muscles_migrations.egg-info/PKG-INFO
+src/muscles_migrations.egg-info/SOURCES.txt
+src/muscles_migrations.egg-info/dependency_links.txt
+src/muscles_migrations.egg-info/requires.txt
+src/muscles_migrations.egg-info/top_level.txt
+tests/test_native_journals.py
+tests/test_registry.py
+tests/test_versioned.py

muscles_migrations-0.2.1/src/muscles_migrations.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

muscles_migrations-0.2.1/src/muscles_migrations.egg-info/requires.txt

@@ -0,0 +1,7 @@
+muscles-data<1.0.0,>=0.2.0
+
+[mongodb]
+muscles-data-mongodb<1.0.0,>=0.2.0
+
+[redis]
+muscles-data-redis<1.0.0,>=0.2.0

muscles_migrations-0.2.1/src/muscles_migrations.egg-info/top_level.txt

@@ -0,0 +1 @@
+muscles

muscles_migrations-0.2.1/tests/test_native_journals.py

@@ -0,0 +1,245 @@
+import os
+import hashlib
+import json
+from uuid import uuid4
+
+import pytest
+
+from muscles.migrations.native import RedisJournal, MongoJournal, RedisMigrationBackend, MongoMigrationBackend
+from muscles.migrations.versioned import Migration, MigrationStateError, VersionedMigrationBackend
+
+
+def test_legacy_backends_reexport_adapter_implementations():
+    from muscles.data.mongodb.migrations import MongoMigrationBackend as MongoBackend
+    from muscles.data.redis.migrations import RedisMigrationBackend as RedisBackend
+
+    assert MongoMigrationBackend is MongoBackend
+    assert RedisMigrationBackend is RedisBackend
+
+
+class RedisFake:
+    def __init__(self):
+        self.values = {}
+
+    def get(self, key):
+        return self.values.get(key)
+
+    def set(self, key, value, nx=False):
+        if nx and key in self.values:
+            return False
+        self.values[key] = value
+        return True
+
+    def eval(self, script, count, key, token):
+        if self.values.get(key) == token:
+            del self.values[key]
+            return 1
+        return 0
+
+    def scan_iter(self, match):
+        from fnmatch import fnmatch
+        return iter([key for key in self.values if fnmatch(key, match)])
+
+
+class CollectionFake:
+    def __init__(self):
+        self.values = {}
+
+    def find_one(self, query):
+        return self.values.get(query["_id"])
+
+    def find(self, query, projection=None):
+        return [dict(value) for value in self.values.values()
+                if all(value.get(key) == expected for key, expected in query.items())]
+
+    def insert_one(self, doc):
+        if doc["_id"] in self.values:
+            raise ValueError("duplicate")
+        self.values[doc["_id"]] = dict(doc)
+
+    def update_one(self, query, update):
+        from types import SimpleNamespace
+        doc = self.values.get(query["_id"])
+        matched = doc is not None and all(doc.get(k) == v for k, v in query.items())
+        if matched:
+            doc.update(update["$set"])
+        return SimpleNamespace(matched_count=int(matched))
+
+    def delete_one(self, query):
+        from types import SimpleNamespace
+        doc = self.values.get(query["_id"])
+        matched = doc is not None and all(doc.get(k) == v for k, v in query.items())
+        if matched:
+            del self.values[query["_id"]]
+        return SimpleNamespace(deleted_count=int(matched))
+
+
+@pytest.mark.parametrize("journal", [RedisJournal(RedisFake(), "test"), MongoJournal(CollectionFake(), "test")])
+def test_native_journal_records_versions(journal):
+    calls = []
+    backend = VersionedMigrationBackend(journal, [Migration("001", "checksum", lambda: calls.append(1))])
+    backend.upgrade()
+    backend.upgrade()
+    assert calls == [1]
+    assert journal.get("001") == ("checksum", "complete")
+
+
+def test_sources_are_isolated():
+    client = RedisFake()
+    one, two = RedisJournal(client, "a"), RedisJournal(client, "b")
+    one.begin("001", "checksum")
+    assert two.get("001") is None
+
+
+def test_redis_legacy_journal_identity_is_preserved():
+    client = RedisFake()
+    old_id = hashlib.sha256(json.dumps(["test", "001"], ensure_ascii=False).encode()).hexdigest()
+    client.values[f"muscles:migrations:{old_id}"] = json.dumps({"checksum": "checksum", "state": "complete"})
+    calls = []
+    backend = RedisMigrationBackend(client, "test", [Migration("001", "checksum", lambda: calls.append("up"))])
+    backend.upgrade()
+    assert backend.status()["current"] == ["001"]
+    assert not calls
+
+
+def test_redis_unattributable_legacy_history_requires_reconciliation():
+    client = RedisFake()
+    old_id = hashlib.sha256(json.dumps(["other", "001"], ensure_ascii=False).encode()).hexdigest()
+    client.values[f"muscles:migrations:{old_id}"] = json.dumps({"checksum": "hash", "state": "complete"})
+    backend = RedisMigrationBackend(client, "test", [])
+    with pytest.raises(MigrationStateError, match="reconcile"):
+        backend.status()
+
+
+def test_redis_journal_rejects_glob_metacharacters_in_prefix():
+    with pytest.raises(ValueError, match="prefix"):
+        RedisMigrationBackend(RedisFake(), "test", [], prefix="shared:*")
+
+
+@pytest.mark.parametrize("backend", [
+    RedisMigrationBackend(RedisFake(), "test", []),
+    MongoMigrationBackend(CollectionFake(), "test", []),
+])
+def test_backend_prevents_concurrent_run_and_releases_lock(backend):
+    calls = []
+    def run():
+        with pytest.raises(Exception):
+            backend.upgrade()
+        calls.append(1)
+    backend.migrations = (Migration("001", "checksum", run),)
+    backend.upgrade()
+    backend.upgrade()
+    assert calls == [1]
+
+
+@pytest.mark.parametrize("backend", [
+    RedisMigrationBackend(RedisFake(), "test", []),
+    MongoMigrationBackend(CollectionFake(), "test", []),
+])
+def test_backend_status_and_downgrade_track_nontransactional_reversion(backend):
+    calls = []
+    backend.migrations = (Migration("001", "checksum", lambda: calls.append("up"), lambda: calls.append("down")),)
+    assert backend.plan() == ["001"]
+    backend.upgrade()
+    assert backend.status()["current"] == ["001"]
+    backend.downgrade("base")
+    assert backend.status()["current"] == []
+    assert calls == ["up", "down"]
+
+
+@pytest.mark.parametrize("backend", [
+    RedisMigrationBackend(RedisFake(), "test", []),
+    MongoMigrationBackend(CollectionFake(), "test", []),
+])
+def test_completed_journal_records_application_time(backend):
+    backend.migrations = (Migration("001", "checksum", lambda: None),)
+    backend.upgrade()
+    if isinstance(backend, RedisMigrationBackend):
+        entry = json.loads(backend.client.get(backend.journal._key("001")))
+    else:
+        entry = backend.collection.find_one({"_id": next(key for key in backend.collection.values if not key.startswith("lock:"))})
+    assert entry.get("applied_at") is not None
+
+
+@pytest.mark.parametrize("backend", [
+    RedisMigrationBackend(RedisFake(), "test", []),
+    MongoMigrationBackend(CollectionFake(), "test", []),
+])
+def test_interrupted_rollback_is_not_retried_automatically(backend):
+    def fail():
+        raise RuntimeError("interrupted")
+
+    backend.migrations = (Migration("001", "checksum", lambda: None, fail),)
+    backend.upgrade()
+    with pytest.raises(RuntimeError, match="interrupted"):
+        backend.downgrade("base")
+    assert backend.journal.get("001") == ("checksum", "reverting")
+    with pytest.raises(MigrationStateError, match="interrupted"):
+        backend.status()
+
+
+@pytest.mark.parametrize("backend", [
+    RedisMigrationBackend(RedisFake(), "test", []),
+    MongoMigrationBackend(CollectionFake(), "test", []),
+])
+def test_missing_previously_applied_migration_is_rejected(backend):
+    backend.migrations = (Migration("001", "first", lambda: None), Migration("002", "second", lambda: None))
+    backend.upgrade()
+    backend.migrations = backend.migrations[:1]
+    with pytest.raises(MigrationStateError, match="missing"):
+        backend.status()
+
+
+@pytest.mark.parametrize("backend", [
+    RedisMigrationBackend(RedisFake(), "test", []),
+    MongoMigrationBackend(CollectionFake(), "test", []),
+])
+def test_lost_lock_ownership_is_reported(backend):
+    with pytest.raises(MigrationStateError, match="lock"):
+        with backend._lock():
+            if isinstance(backend, RedisMigrationBackend):
+                backend.client.set(backend.lock_key, "other-owner")
+            else:
+                backend.collection.values[backend.lock_id]["token"] = "other-owner"
+
+
+@pytest.mark.skipif(not os.getenv("MUSCLES_MIGRATION_TEST_REDIS"), reason="isolated Redis not configured")
+def test_redis_migration_lifecycle_against_real_server():
+    from redis import Redis
+
+    client = Redis.from_url(os.environ["MUSCLES_MIGRATION_TEST_REDIS"])
+    prefix = f"muscles:example:{uuid4().hex}"
+    key = f"{prefix}:data"
+    backend = RedisMigrationBackend(client, "example", [
+        Migration("001", "checksum", lambda: client.set(key, "value"), lambda: client.delete(key))
+    ], prefix=prefix)
+    try:
+        backend.upgrade()
+        assert client.get(key) == b"value"
+        assert backend.status()["current"] == ["001"]
+        backend.downgrade("base")
+        assert client.get(key) is None
+        assert backend.status()["current"] == []
+    finally:
+        client.close()
+
+
+@pytest.mark.skipif(not os.getenv("MUSCLES_MIGRATION_TEST_MONGODB"), reason="isolated MongoDB not configured")
+def test_mongodb_migration_lifecycle_against_real_server():
+    from pymongo import MongoClient
+
+    client = MongoClient(os.environ["MUSCLES_MIGRATION_TEST_MONGODB"], serverSelectionTimeoutMS=5000)
+    database = client[f"muscles_test_{uuid4().hex}"]
+    backend = MongoMigrationBackend(database.journal, "example", [
+        Migration("001", "checksum", lambda: database.data.insert_one({"_id": "one"}),
+                  lambda: database.data.delete_one({"_id": "one"}))
+    ])
+    try:
+        backend.upgrade()
+        assert database.data.find_one({"_id": "one"}) is not None
+        assert backend.status()["current"] == ["001"]
+        backend.downgrade("base")
+        assert database.data.find_one({"_id": "one"}) is None
+        assert backend.status()["current"] == []
+    finally:
+        client.close()

muscles_migrations-0.2.1/tests/test_registry.py

@@ -0,0 +1,39 @@
+import pytest
+
+from muscles.migrations import MigrationRegistry, MigrationSource
+
+
+def test_legacy_imports_share_the_data_contract():
+    from muscles.data.migrations import MigrationRegistry as DataRegistry, MigrationSource as DataSource
+
+    assert MigrationRegistry is DataRegistry
+    assert MigrationSource is DataSource
+
+
+class Backend:
+    def __init__(self, name, calls):
+        self.name, self.calls = name, calls
+
+    def upgrade(self, target="head"):
+        self.calls.append((self.name, target))
+
+
+def test_sources_run_after_dependencies():
+    calls = []
+    registry = MigrationRegistry()
+    registry.register(MigrationSource("sites", Backend("sites", calls), ("accounts",)))
+    registry.register(MigrationSource("accounts", Backend("accounts", calls)))
+    registry.upgrade()
+    assert calls == [("accounts", "head"), ("sites", "head")]
+
+
+def test_missing_or_cyclic_dependencies_fail_before_upgrade():
+    calls = []
+    registry = MigrationRegistry()
+    registry.register(MigrationSource("a", Backend("a", calls), ("b",)))
+    with pytest.raises(ValueError):
+        registry.upgrade()
+    registry.register(MigrationSource("b", Backend("b", calls), ("a",)))
+    with pytest.raises(ValueError):
+        registry.upgrade()
+    assert not calls

muscles_migrations-0.2.1/tests/test_versioned.py

@@ -0,0 +1,66 @@
+import pytest
+import importlib.util
+
+from muscles.migrations.versioned import Migration, MigrationStateError, VersionedMigrationBackend
+
+
+class Journal:
+    def __init__(self):
+        self.entries = {}
+
+    def get(self, version):
+        return self.entries.get(version)
+
+    def begin(self, version, checksum):
+        self.entries[version] = (checksum, "running")
+
+    def complete(self, version, checksum):
+        self.entries[version] = (checksum, "complete")
+
+
+def test_applies_once_and_detects_changed_migration():
+    calls = []
+    journal = Journal()
+    backend = VersionedMigrationBackend(journal, [Migration("001", "checksum", lambda: calls.append(1))])
+    backend.upgrade()
+    backend.upgrade()
+    assert calls == [1]
+    with pytest.raises(MigrationStateError):
+        VersionedMigrationBackend(journal, [Migration("001", "changed", lambda: None)]).upgrade()
+
+
+def test_failure_leaves_running_state_and_does_not_rerun():
+    journal = Journal()
+
+    def fail():
+        raise RuntimeError("failure")
+
+    backend = VersionedMigrationBackend(journal, [Migration("001", "checksum", fail)])
+    with pytest.raises(RuntimeError):
+        backend.upgrade()
+    with pytest.raises(MigrationStateError):
+        backend.upgrade()
+
+
+def test_changed_file_after_discovery_is_not_executed(tmp_path):
+    path = tmp_path / "m001.py"
+    path.write_text("revision = '001'\ndef upgrade():\n    pass\n", encoding="utf-8")
+    spec = importlib.util.spec_from_file_location("test_non_sql_migration", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    migration = Migration.from_module(module)
+    path.write_text(path.read_text() + "# changed\n", encoding="utf-8")
+    with pytest.raises(MigrationStateError, match="changed"):
+        VersionedMigrationBackend(Journal(), [migration]).upgrade()
+
+
+def test_migration_module_receives_explicit_resource(tmp_path):
+    path = tmp_path / "m002.py"
+    path.write_text("revision = '002'\ndef upgrade(resource):\n    resource.append('up')\n", encoding="utf-8")
+    spec = importlib.util.spec_from_file_location("test_non_sql_migration_resource", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    resource = []
+    migration = Migration.from_module(module, resource=resource)
+    VersionedMigrationBackend(Journal(), [migration]).upgrade()
+    assert resource == ["up"]