mainsequence-metatable 0.1.38.dev70__tar.gz → 0.1.39.dev71__tar.gz

{mainsequence_metatable-0.1.38.dev70/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.39.dev71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.38.dev70
+Version: 0.1.39.dev71
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/docs/adr/api/0014-main-sequence-release-jobs-and-production-migrations.md

@@ -73,6 +73,14 @@ resolve declaration and Secret
   -> commit; fresh registration/reference verification; release bootstrap lock
 ```
 
+The bootstrap lock is a session lock held on its own connection (amended
+2026-10-15, [MetaTables #65](https://github.com/mainsequence-projects/MetaTables/issues/65)).
+A heartbeat queries that connection every 30 seconds so a tunnel or NAT does not
+drop it as idle. The registration commit happens only while the lock is held: if
+the connection was lost, the bootstrap fails before committing. A connection
+dropped after the commit means the server already released the lock, so its
+release is a warning and never fails the committed migration.
+
 Hosted configuration defers database inspection to the authoritative preflight
 inside the bootstrap lock. The local path retains its pre-lock check, so an old
 store cannot be replaced or a new file created before compatibility is checked.

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence-metatable"
-version = "0.1.38.dev70"
+version = "0.1.39.dev71"
 description = "Main Sequence MetaTables Python client and standalone API"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.38.dev70
+Version: 0.1.39.dev71
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/src/mainsequence_metatable.egg-info/SOURCES.txt

@@ -570,6 +570,7 @@ tests/integrations/test_serving_policy.py
 tests/integrations/test_source_validation.py
 tests/integrations/test_sqlite_operations.py
 tests/labels/test_labels.py
+tests/operations/test_bootstrap_lock.py
 tests/operations/test_create_table_operation.py
 tests/operations/test_create_table_postgres.py
 tests/operations/test_physical_operation_journal.py

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/src/metatables/api/app/bootstrap.py

@@ -400,8 +400,8 @@ class RuntimeBootstrap:
     @contextmanager
     def migration_lock(self):
         engine = self.open_engine(create=True)
-        with self.backend.catalog.bootstrap_lock(engine):
-            yield
+        with self.backend.catalog.bootstrap_lock(engine) as lock:
+            yield lock
 
     def migrate(self, user_uid):
         if not self.candidate:
@@ -416,7 +416,7 @@ class RuntimeBootstrap:
                     raise BootstrapError(self.error or "The selected database cannot be migrated.")
             with ExitStack() as locks:
                 with bootstrap_phase("lock_wait"):
-                    locks.enter_context(self.migration_lock())
+                    lock = locks.enter_context(self.migration_lock())
                 with bootstrap_phase("locked_preflight"):
                     self.inspect(validate_schema=False)
                 if self.status not in {"migration_required", "registration_required", "ready"}:
@@ -452,6 +452,8 @@ class RuntimeBootstrap:
                         if hasattr(credentials, "initialize"):
                             credentials.initialize()
                     with bootstrap_phase("registration_commit"):
+                        # Commit only while the lock is still held (MetaTables #65).
+                        lock.check()
                         session.commit()
                 # upgrade_catalog already verified the complete system schema.
                 # Recheck registration before releasing the lock, without

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/src/metatables/api/backend/backends/catalog.py

@@ -1,5 +1,7 @@
 """Catalog connection, lock and migration mechanics for bound backends."""
 
+import logging
+import threading
 from contextlib import contextmanager
 from pathlib import Path
 
@@ -9,6 +11,61 @@ from sqlalchemy.engine import URL
 from metatables.api.backend.backends import catalog_ddl  # register reserved-schema renderers
 from metatables.api.backend.backends.contracts import CatalogConfigurationError
 
+logger = logging.getLogger(__name__)
+
+# The lock's connection is otherwise idle for the whole bootstrap; a tunnel or NAT
+# drops idle TCP connections, and with the connection the server drops the lock.
+BOOTSTRAP_LOCK_HEARTBEAT_SECONDS = 30
+
+
+class BootstrapLockLost(RuntimeError):
+    """The bootstrap lock's connection, and so the lock, was lost before a commit."""
+
+
+class HeldLock:
+    """A session lock held on its own connection for a whole bootstrap (MetaTables #65).
+
+    A heartbeat keeps the connection in use so it is not dropped as idle.
+    ``check()`` fails before a commit if the connection was lost anyway. At
+    release a lost connection means the server already released the lock: a
+    warning, never a failure of work that committed.
+    """
+
+    def __init__(self, connection=None, release_sql=None, *, interval=BOOTSTRAP_LOCK_HEARTBEAT_SECONDS):
+        self.connection, self.release_sql, self.lost = connection, release_sql, None
+        self._stop, self._use = threading.Event(), threading.Lock()
+        self._heartbeat = None
+        if connection is not None:
+            self._heartbeat = threading.Thread(target=self._beat, args=(interval,), daemon=True,
+                                               name="metatables-bootstrap-lock")
+            self._heartbeat.start()
+
+    def _beat(self, interval):
+        while not self._stop.wait(interval):
+            with self._use:
+                try:
+                    self.connection.exec_driver_sql("SELECT 1")
+                except Exception as exc:
+                    self.lost = exc
+                    return
+
+    def check(self):
+        if self.lost is not None:
+            raise BootstrapLockLost("The bootstrap lock's connection was lost before commit; "
+                                    "nothing was committed. Retry the migration.") from self.lost
+
+    def release(self):
+        if self.connection is None:
+            return
+        self._stop.set()
+        self._heartbeat.join()
+        try:
+            with self._use:
+                self.connection.exec_driver_sql(self.release_sql)
+        except Exception:
+            logger.warning("The bootstrap lock's connection was lost; the server released the lock with it.",
+                           exc_info=True)
+
 
 class PostgreSQLCatalog:
     default_schema = "public"
@@ -161,12 +218,11 @@ class PostgreSQLCatalog:
         with engine.connect() as connection:
             connection.exec_driver_sql("SET LOCAL statement_timeout = '30s'")
             connection.exec_driver_sql("SELECT pg_advisory_lock(hashtext('metatables:bootstrap'))")
+            lock = HeldLock(connection, "SELECT pg_advisory_unlock(hashtext('metatables:bootstrap'))")
             try:
-                yield
+                yield lock
             finally:
-                connection.exec_driver_sql(
-                    "SELECT pg_advisory_unlock(hashtext('metatables:bootstrap'))"
-                )
+                lock.release()
 
     @contextmanager
     def migration_connection(self, engine):
@@ -250,7 +306,8 @@ class SQLiteCatalog(PostgreSQLCatalog):
                     if time.monotonic() >= deadline:
                         raise CatalogConfigurationError("bootstrap_lock_unavailable") from exc
                     time.sleep(0.05)
-            yield
+            # A local file lock cannot be dropped by the network.
+            yield HeldLock()
 
     def lock_shared(self, session, *, write=False):
         # WAL readers do not block permission publication. Keep SQLite's native

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/src/metatables/api/backend/backends/contracts.py

@@ -176,7 +176,7 @@ class CatalogBackend(Protocol):
     def lock(self, session: Session) -> None: ...
     def lock_shared(self, session: Session, *, write=False) -> None: ...
     def schema(self, name: str | None) -> str | None: ...
-    def bootstrap_lock(self, engine: Engine) -> AbstractContextManager[None]: ...
+    def bootstrap_lock(self, engine: Engine) -> AbstractContextManager[Any]: ...
     def migration_connection(self, engine: Engine) -> AbstractContextManager[Connection]: ...
     def schema_object_state(self, connection: Connection, name: str) -> Any: ...
     def column_type_matches(self, expected: Any, actual: Any, dialect: Any) -> bool: ...

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/src/metatables/api/backend/backends/hosted.py

@@ -233,12 +233,12 @@ class MySQLCatalog(HostedCatalog):
                 != 1
             ):
                 raise CatalogConfigurationError("bootstrap_lock_unavailable")
+            from metatables.api.backend.backends.catalog import HeldLock
+            lock = HeldLock(connection, "SELECT RELEASE_LOCK(CONCAT(DATABASE(), ':metatables:bootstrap'))")
             try:
-                yield
+                yield lock
             finally:
-                connection.execute(
-                    sa.text("SELECT RELEASE_LOCK(CONCAT(DATABASE(), ':metatables:bootstrap'))")
-                )
+                lock.release()
 
     def column_type_matches(self, expected, actual, dialect):
         if isinstance(expected, sa.Boolean):

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/tests/auth/test_data_source_identity.py

@@ -9,6 +9,7 @@ from sqlalchemy.orm import sessionmaker
 
 from metatables.api.app.bootstrap import RuntimeBootstrap
 from metatables.api.app.runtime import RuntimeConfig
+from metatables.api.backend.backends.catalog import HeldLock
 from metatables.api.backend.persistence.database import create_catalog_engine, upgrade_catalog
 from metatables.api.backend.persistence.models import DataSource
 
@@ -31,7 +32,7 @@ def test_deployment_registers_the_declared_runtime_and_follows_its_declaration(t
     bootstrap.backend = SimpleNamespace(source=Source())
     # Keep the actual migration/registration transaction; isolate hosted driver
     # and schema-access setup, which the engine contract tests cover separately.
-    monkeypatch.setattr(bootstrap, "migration_lock", nullcontext)
+    monkeypatch.setattr(bootstrap, "migration_lock", lambda: nullcontext(HeldLock()))
     monkeypatch.setattr("metatables.api.backend.backends.registry.backend_for", lambda source:
         SimpleNamespace(access=SimpleNamespace(initialize=lambda session, revisions: None)))
 
@@ -81,7 +82,7 @@ def test_setup_reports_the_database_privilege_error_without_sql_or_parameters(tm
         uid: UUID | None = None
 
     bootstrap.backend = SimpleNamespace(source=Source())
-    monkeypatch.setattr(bootstrap, "migration_lock", nullcontext)
+    monkeypatch.setattr(bootstrap, "migration_lock", lambda: nullcontext(HeldLock()))
     monkeypatch.setattr(bootstrap, "inspect", lambda **_: setattr(bootstrap, "status", "registration_required"))
     # A TimescaleDB runtime whose extension objects belong to the superuser.
     denied = SimpleNamespace(pgcode="42501", diag=SimpleNamespace(message_primary="permission denied for table job_errors"))
@@ -127,7 +128,7 @@ def test_unsecurable_database_is_blocked_before_any_setup_ddl(tmp_path, monkeypa
     ])
     # Hosted prerequisite inspection now runs after taking the read-only
     # bootstrap lock; isolate that lock along with this fixture's hosted adapter.
-    monkeypatch.setattr(bootstrap, "migration_lock", nullcontext)
+    monkeypatch.setattr(bootstrap, "migration_lock", lambda: nullcontext(HeldLock()))
     monkeypatch.setattr("metatables.api.app.bootstrap.upgrade_catalog",
                         lambda engine: pytest.fail("Setup DDL ran on a database the login cannot secure"))
     try:

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/tests/auth/test_runtime_bootstrap.py

@@ -210,6 +210,60 @@ def test_missing_local_key_leaves_settings_readable_and_blocks_save(bootstrap_cl
         assert not key.exists()
 
 
+def _lock(monkeypatch, *, lost=False):
+    """A bootstrap lock whose connection is lost before commit, or dropped at release."""
+    from contextlib import contextmanager
+
+    from metatables.api.backend.backends import catalog
+
+    class Connection:
+        def exec_driver_sql(self, statement):
+            if lost or statement != "SELECT 1":
+                raise ConnectionError("SSL SYSCALL error: EOF detected")
+
+    released = []
+
+    class Lock(catalog.HeldLock):
+        def __init__(self):
+            super().__init__(Connection(), "SELECT release", interval=3600)
+            self.lost = ConnectionError("SSL SYSCALL error: EOF detected") if lost else None
+
+        def release(self):
+            super().release()  # The dropped connection only warns.
+            released.append(True)
+
+    @contextmanager
+    def bootstrap_lock(self, engine):
+        lock = Lock()
+        try:
+            yield lock
+        finally:
+            lock.release()
+
+    monkeypatch.setattr(catalog.SQLiteCatalog, "bootstrap_lock", bootstrap_lock)
+    return released
+
+
+def test_a_lock_lost_before_commit_fails_without_registering(bootstrap_client, monkeypatch):
+    """MetaTables #65: the bootstrap stops before commit when its lock is gone."""
+    client, path, _ = bootstrap_client
+    _lock(monkeypatch, lost=True)
+    response = client.post("/runtime-bootstrap/migrate/")
+    assert response.status_code == 409 and "BootstrapLockLost" in response.text
+    assert not client.get("/runtime-context/").json()["bootstrap"]["active"]
+    with client.app.state.runtime.bootstrap.factory() as session:
+        assert session.scalar(select(DataSource)) is None
+
+
+def test_a_lock_connection_dropped_after_commit_keeps_the_migration(bootstrap_client, monkeypatch):
+    """MetaTables #65: a dropped lock connection after commit is a warning, not a failure."""
+    client, path, _ = bootstrap_client
+    released = _lock(monkeypatch)
+    response = client.post("/runtime-bootstrap/migrate/")
+    assert response.status_code == 200, response.text
+    assert response.json()["active"] is True and released == [True]
+
+
 def test_failed_migration_never_activates(bootstrap_client, monkeypatch):
     client, path, _ = bootstrap_client
     import metatables.api.app.bootstrap as boot

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/tests/e2e/test_runtime_upgrade.py

@@ -115,10 +115,10 @@ def test_deployment_validates_schema_once_under_lock_and_reapplies_access(sqlite
     @contextmanager
     def lock(catalog, engine):
         nonlocal locked
-        with original_lock(catalog, engine):
+        with original_lock(catalog, engine) as held:
             locked = True
             try:
-                yield
+                yield held
                 # Registration is verified before the validation's lock expires.
                 assert target.status == "ready"
             finally:
@@ -215,10 +215,10 @@ def test_hosted_migration_inspects_once_under_lock_and_rechecks_registration(sql
     @contextmanager
     def lock(catalog, engine):
         nonlocal inside
-        with original_lock(catalog, engine):
+        with original_lock(catalog, engine) as held:
             inside = True
             try:
-                yield
+                yield held
             finally:
                 inside = False
 

mainsequence_metatable-0.1.39.dev71/tests/operations/test_bootstrap_lock.py

@@ -0,0 +1,55 @@
+"""The bootstrap lock survives long runs and a dropped connection (MetaTables #65)."""
+
+import threading
+
+import pytest
+
+from metatables.api.backend.backends.catalog import BootstrapLockLost, HeldLock
+
+RELEASE = "SELECT pg_advisory_unlock(hashtext('metatables:bootstrap'))"
+
+
+class Connection:
+    """Records statements; fails them once dropped, as a closed socket does."""
+
+    def __init__(self):
+        self.statements, self.dropped, self.beat = [], False, threading.Event()
+
+    def exec_driver_sql(self, statement):
+        self.statements.append(statement)
+        if statement == "SELECT 1":
+            self.beat.set()
+        if self.dropped:
+            raise ConnectionError("SSL SYSCALL error: EOF detected")
+
+
+def test_the_heartbeat_keeps_the_lock_connection_busy_until_release():
+    connection = Connection()
+    lock = HeldLock(connection, RELEASE, interval=0.01)
+    assert connection.beat.wait(5)
+    lock.check()
+    lock.release()
+    assert connection.statements[-1] == RELEASE
+    count = len(connection.statements)
+    threading.Event().wait(0.05)
+    assert len(connection.statements) == count  # No heartbeat after release.
+
+
+def test_a_lost_connection_fails_the_check_before_commit():
+    connection = Connection()
+    connection.dropped = True
+    lock = HeldLock(connection, RELEASE, interval=0.01)
+    assert connection.beat.wait(5)
+    lock._heartbeat.join(5)
+    with pytest.raises(BootstrapLockLost, match="nothing was committed"):
+        lock.check()
+    lock.release()
+
+
+def test_a_connection_dropped_after_commit_is_a_warning(caplog):
+    connection = Connection()
+    lock = HeldLock(connection, RELEASE, interval=60)
+    connection.dropped = True
+    with caplog.at_level("WARNING", logger="metatables.api.backend.backends.catalog"):
+        lock.release()  # Committed work stays a success.
+    assert "server released the lock with it" in caplog.text

{mainsequence_metatable-0.1.38.dev70 → mainsequence_metatable-0.1.39.dev71}/uv.lock

@@ -854,7 +854,7 @@ mcp = [
 
 [[package]]
 name = "mainsequence-metatable"
-version = "0.1.38"
+version = "0.1.39"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },