mainsequence-metatable 0.1.12.dev25__tar.gz → 0.1.14__tar.gz

{mainsequence_metatable-0.1.12.dev25/src/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.12.dev25
+Version: 0.1.14
 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.12.dev25 → mainsequence_metatable-0.1.14}/docs/operations/hosted-runtime.md

@@ -123,6 +123,12 @@ Any failure blocks the rollout. The Job prints `status` (`initialized`, `upgrade
 or `up_to_date`), `previous_revisions`, `revisions` and `data_source_uid`. A new
 runtime DataSource is recorded as created by the Job's SDK user.
 
+A failed run names its cause. The error line gives the exception type, plus the
+database server's SQLSTATE and message when the server answered. The
+`metatables.bootstrap` logger writes the full error with its traceback to the Job
+log, with passwords, tokens and connection-string credentials redacted. Settings
+and API errors never carry driver text, which can include hosts and connection strings.
+
 ## API pods and Settings
 
 API pods read the same declaration and Secret at startup and never run DDL. They

{mainsequence_metatable-0.1.12.dev25 → mainsequence_metatable-0.1.14}/docs/operations/recovery-and-observability.md

@@ -54,6 +54,13 @@ assertions, migration passwords, or TLS keys. SDK logging/tracing integration is
 optional behavior; catalog membership and storage authorization are not derived
 from logging context.
 
+The `metatables.bootstrap` logger records unexpected runtime database failures
+(inspection, migration, registration and the Local selection file) with their
+traceback, redacting passwords, tokens and connection-string credentials as run
+logs do. The matching API error names only the exception type and, when the database
+server answered, its SQLSTATE and message. See the
+[deployment gate](hosted-runtime.md#deployment-gate).
+
 Distinguish HTTP availability, catalog readiness, caller admission, source grants,
 physical capabilities, and actual database connectivity when diagnosing failures.
 The [testing guide](../contributing/testing.md) distinguishes isolated tests from

{mainsequence_metatable-0.1.12.dev25 → mainsequence_metatable-0.1.14}/pyproject.toml

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

{mainsequence_metatable-0.1.12.dev25 → mainsequence_metatable-0.1.14/src/mainsequence_metatable.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.12.dev25
+Version: 0.1.14
 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.12.dev25 → mainsequence_metatable-0.1.14}/src/mainsequence_metatable.egg-info/SOURCES.txt

@@ -406,6 +406,7 @@ src/metatables/updaters/runner.py
 src/metatables/updaters/updaters.py
 src/metatables/updaters/utils.py
 tests/conftest.py
+tests/auth/test_bootstrap_failure_cause.py
 tests/auth/test_caller_assertions.py
 tests/auth/test_data_source_identity.py
 tests/auth/test_development_client.py

{mainsequence_metatable-0.1.12.dev25 → mainsequence_metatable-0.1.14}/src/metatables/api/app/bootstrap.py

@@ -1,6 +1,8 @@
 """Explicit, mode-independent initialization of the selected runtime database."""
 import json
+import logging
 import os
+import traceback
 from contextlib import ExitStack, contextmanager
 from dataclasses import replace
 from pathlib import Path
@@ -42,9 +44,11 @@ from metatables.api.backend.persistence.models import (
     MetaTable,
     PhysicalOperation,
 )
+from metatables.log_contract import redact
 from metatables.runtime_contract import RuntimeBootstrapDescriptor
 
 VERSION_TABLE = "metatables_catalog_version"
+logger = logging.getLogger("metatables.bootstrap")
 
 
 class RuntimeSourceInput(BaseModel):
@@ -58,14 +62,42 @@ class BootstrapError(RuntimeError):
     pass
 
 
-def insufficient_privilege(exc):
-    """The database's own message for a missing privilege, never SQL text or parameters."""
+def server_diagnostic(exc):
+    """The database server's SQLSTATE and primary message, never SQL text, parameters or driver text."""
     orig = getattr(exc, "orig", None)
     code = getattr(orig, "pgcode", None) or getattr(orig, "sqlstate", None)
-    message = getattr(getattr(orig, "diag", None), "message_primary", None)
+    return code, getattr(getattr(orig, "diag", None), "message_primary", None)
+
+
+def insufficient_privilege(exc):
+    """The database's own message for a missing privilege, never SQL text or parameters."""
+    code, message = server_diagnostic(exc)
     return message if code == "42501" and message else None
 
 
+def failure_cause(exc):
+    """The part of an unexpected failure that callers may see.
+
+    Its type and, when the database server answered, the SQLSTATE and primary
+    message. Driver text can carry hosts, connection strings or secrets, so it
+    reaches only the redacted log written by `log_failure`.
+    """
+    code, message = server_diagnostic(exc)
+    cause = type(exc).__name__ + (f" {code}" if code else "")
+    return f"{cause}: {redact(' '.join(str(message).split()))}" if message else cause
+
+
+def log_failure(event, exc):
+    """Log an unexpected failure with its traceback, redacted like run log records.
+
+    Returns the failure's caller-visible cause for the error message.
+    """
+    cause = failure_cause(exc)
+    lines = "".join(traceback.format_exception(exc)).rstrip().splitlines()
+    logger.error("%s (%s).\n%s", event, cause, "\n".join(redact(line) for line in lines))
+    return cause
+
+
 class DestroyLocalInput(BaseModel):
     model_config = ConfigDict(extra="forbid")
     path: str
@@ -114,8 +146,9 @@ class RuntimeBootstrap:
             result["required_revisions"] = sorted(script.get_heads())
             if not result["required_revisions"]:
                 raise ValueError("Migration files have no head revision")
-        except Exception:
-            result["migration_error"] = "Cannot read the API's migration files. Check the migration directory and refresh."
+        except Exception as exc:
+            cause = log_failure("Cannot read the API's migration files", exc)
+            result["migration_error"] = f"Cannot read the API's migration files ({cause}). Check the migration directory and refresh."
             return result
         if not self.candidate:
             result["migration_status"] = "unconfigured"
@@ -129,8 +162,9 @@ class RuntimeBootstrap:
                 with engine.connect() as connection:
                     result["current_revisions"] = sorted(MigrationContext.configure(
                         connection, opts={"version_table": VERSION_TABLE}).get_current_heads())
-        except Exception:
-            result["migration_error"] = "Cannot read the database's applied migrations. Check its connection and refresh."
+        except Exception as exc:
+            cause = log_failure("Cannot read the database's applied migrations", exc)
+            result["migration_error"] = f"Cannot read the database's applied migrations ({cause}). Check its connection and refresh."
             return result
         try:
             current = result["current_revisions"]
@@ -314,9 +348,11 @@ class RuntimeBootstrap:
             self.status, self.error = "incompatible", str(exc)
         except CredentialStoreError as exc:
             self.status, self.error = "unavailable", exc.message
-        except Exception:
+        except Exception as exc:
+            cause = log_failure("Cannot verify the selected database or its Alembic history", exc)
             self.status = "unavailable"
-            self.error = "Cannot verify the selected database or its Alembic history. Check configuration, Secret access and the API's migration version."
+            self.error = (f"Cannot verify the selected database or its Alembic history ({cause}). Check configuration, "
+                          "Secret access and the API's migration version. The log has the full error.")
 
     def require_prerequisites(self, connection):
         # Before any setup DDL: a database the login cannot secure must never be
@@ -395,7 +431,9 @@ class RuntimeBootstrap:
                 self.error = (f"Database setup failed: {privilege_error}. The DataSource login must own the runtime "
                               "database and every object in it; see the DataSource database privileges.")
                 raise BootstrapError(self.error) from None
-            self.error = "MetaTables migration or registration failed. The runtime was not activated; inspect the database before retrying."
+            cause = log_failure("MetaTables migration or registration failed", exc)
+            self.error = (f"MetaTables migration or registration failed ({cause}). The runtime was not activated; "
+                          "inspect the database before retrying. The log has the full error.")
             raise BootstrapError(self.error) from None
 
     def persist_selection(self):
@@ -447,11 +485,13 @@ class RuntimeBootstrap:
             raise
         except RuntimeError as exc:
             raise BootstrapError(str(exc)) from None
-        except Exception:
+        except Exception as exc:
+            cause = log_failure("Unable to finish local database destruction", exc)
+            message = f"Unable to finish local database destruction ({cause}). Check file access and retry."
             if not self.active:
                 self.status = "unavailable"
-                self.error = "Unable to finish local database destruction. Check file access and retry."
-            raise BootstrapError("Unable to finish local database destruction. Check file access and retry.") from None
+                self.error = message
+            raise BootstrapError(message) from None
 
     def activate(self, request, user_uid=None, *, persist=True):
         self.inspect()
@@ -466,8 +506,10 @@ class RuntimeBootstrap:
             try:
                 self.persist_selection()
                 self.save_local_selection = False
-            except Exception:
-                raise BootstrapError("Unable to save runtime selection. The database is initialized but was not activated.") from None
+            except Exception as exc:
+                cause = log_failure("Unable to save runtime selection", exc)
+                raise BootstrapError(f"Unable to save runtime selection ({cause}). The database is initialized "
+                                     "but was not activated.") from None
         binding = RuntimeStorageBinding(catalog_url=str(self.engine.url), workspace=self.workspace,
                                         source_uid=self.uid, source_configuration=self.candidate["configuration"])
         from sqlalchemy import create_engine

mainsequence_metatable-0.1.14/tests/auth/test_bootstrap_failure_cause.py

@@ -0,0 +1,80 @@
+"""An unexpected runtime database failure names its cause; driver text stays in the redacted log."""
+import logging
+from types import SimpleNamespace
+from uuid import uuid4
+
+import pytest
+from sqlalchemy.exc import OperationalError
+
+from metatables.api.app.bootstrap import BootstrapError, RuntimeBootstrap
+
+PASSWORD = "hunter2-runtime-login"
+DSN = f"postgresql://metatables:{PASSWORD}@db.internal.test:5432/runtime"
+
+
+class ServerError(Exception):
+    """A DBAPI error carrying the server's SQLSTATE and primary message, as psycopg does."""
+
+    pgcode = "28P01"
+    diag = SimpleNamespace(message_primary='password authentication failed for user "metatables"')
+
+
+def failing_target(tmp_path, failure):
+    """A runtime target whose database connection raises `failure`."""
+    config = SimpleNamespace(local_mode=True, configuration_path=tmp_path / "configuration.yaml")
+    target = RuntimeBootstrap(config, None)
+    target.candidate = {"display_name": "runtime", "class_type": "postgresql",
+                        "configuration": {"host": "db.internal.test"}}
+
+    def connect():
+        raise failure
+
+    target.open_engine = lambda create=False: SimpleNamespace(connect=connect)
+    return target
+
+
+def logged(caplog):
+    return [record for record in caplog.records if record.name == "metatables.bootstrap"]
+
+
+def test_inspection_failure_names_its_type_and_logs_the_redacted_traceback(tmp_path, caplog):
+    failure = OperationalError(None, None, RuntimeError(f'connection failed: invalid connection string "{DSN}"'))
+    target = failing_target(tmp_path, failure)
+    with caplog.at_level(logging.ERROR, logger="metatables.bootstrap"):
+        target.inspect()
+    assert target.status == "unavailable"
+    assert target.error.startswith("Cannot verify the selected database or its Alembic history (OperationalError). ")
+    # Callers (Settings, runtime-context, the Job's error line) never see driver text.
+    assert "db.internal.test" not in target.error and PASSWORD not in target.error
+    [record] = logged(caplog)
+    assert record.levelno == logging.ERROR
+    message = record.getMessage()
+    assert message.startswith("Cannot verify the selected database or its Alembic history (OperationalError).\n")
+    assert "Traceback (most recent call last):" in message and ", in connect\n" in message
+    assert "sqlalchemy.exc.OperationalError: (builtins.RuntimeError) connection failed" in message
+    assert "postgresql://metatables:[redacted]@db.internal.test:5432/runtime" in message
+    assert PASSWORD not in caplog.text
+
+
+def test_inspection_failure_names_the_database_server_answer(tmp_path, caplog):
+    failure = OperationalError(None, None, ServerError(f"FATAL: password authentication failed; dsn={DSN}"))
+    target = failing_target(tmp_path, failure)
+    with caplog.at_level(logging.ERROR, logger="metatables.bootstrap"):
+        target.inspect()
+    assert ('(OperationalError 28P01: password authentication failed for user "metatables")'
+            in target.error)
+    assert PASSWORD not in target.error and "dsn" not in target.error
+    assert PASSWORD not in caplog.text
+
+
+def test_runtime_upgrade_fails_with_the_cause(tmp_path, caplog):
+    # `metatables runtime upgrade` prints this BootstrapError and fails the Job.
+    failure = OperationalError(None, None, RuntimeError(f"could not connect to {DSN}: timeout expired"))
+    target = failing_target(tmp_path, failure)
+    with caplog.at_level(logging.ERROR, logger="metatables.bootstrap"), pytest.raises(BootstrapError) as raised:
+        target.migrate(uuid4())
+    assert str(raised.value).startswith("Cannot verify the selected database or its Alembic history (OperationalError). ")
+    assert PASSWORD not in str(raised.value)
+    records = logged(caplog)
+    assert records and all("timeout expired" in record.getMessage() for record in records)
+    assert PASSWORD not in caplog.text

{mainsequence_metatable-0.1.12.dev25 → mainsequence_metatable-0.1.14}/uv.lock

@@ -632,7 +632,7 @@ server = [
 
 [[package]]
 name = "mainsequence-metatable"
-version = "0.1.12"
+version = "0.1.14"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },