sql-safe-mcp 1.2.0__tar.gz → 1.3.0__tar.gz

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/CHANGELOG.md

@@ -7,6 +7,21 @@ categories `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-09-21
+
+### Added
+
+- Diagnostic logging to stderr, controlled by the new `logging.level` setting (`DEBUG`, `INFO`,
+  `WARNING`, or `ERROR`; default `INFO`). It records each database connection attempt (server alias,
+  database, elapsed time, and on failure the driver error class, SQLSTATE or code, and message with
+  the connection URL's user name and password masked and its host shown as the server alias) and each tool operation's outcome.
+  Connection URLs, credentials, keys, tokens, SQL, bind values, and rows are never logged.
+
+### Changed
+
+- `TIMEOUT` and `CONNECTION_FAILED` errors now carry a `Reference` that matches the `reference=`
+  field of the log line for the same failure.
+
 ## [1.2.0] - 2026-09-20
 
 ### Added

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-safe-mcp
-Version: 1.2.0
+Version: 1.3.0
 Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
 License: MIT License
         
@@ -44,12 +44,12 @@ A read-only, PII-safe SQL Server, MySQL and MariaDB MCP server for coding agents
 
 [![CI](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/proprock/sql-safe-mcp)](https://github.com/proprock/sql-safe-mcp/releases)
-[![PyPI Version](https://img.shields.io/pypi/v/sql-safe-mcp)](https://pypi.org/project/sql-safe-mcp/)
+[![PyPI Version](https://img.shields.io/pypi/v/sql-safe-mcp?cacheSeconds=3600)](https://pypi.org/project/sql-safe-mcp/)
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 [![Model Context Protocol compatible](https://img.shields.io/badge/Model_Context_Protocol-compatible-000000?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
-[![MCP Registry: io.github.proprock/sql-safe-mcp](https://img.shields.io/badge/MCP_Registry-io.github.proprock%2Fsql--mini--mcp-000000?logo=modelcontextprotocol&logoColor=white)](server.json)
+[![MCP Registry: io.github.proprock/sql-safe-mcp](https://img.shields.io/badge/MCP_Registry-io.github.proprock%2Fsql--safe--mcp-000000?logo=modelcontextprotocol&logoColor=white)](server.json)
 
 <img src="https://raw.githubusercontent.com/proprock/sql-safe-mcp/master/images/luna-guard.jpg" alt="Read the data. Protect the identity." width="760">
 
@@ -90,6 +90,14 @@ databases, tables, columns, keys, indexes, stored procedures - and, on servers y
   case-insensitive name filters, and stored procedure lists that do not expand definitions.
 - **Errors an agent can act on** - an ambiguous name lists the candidate schemas. Errors never
   contain connection details, credentials, keys, tokens, or rows.
+- **Tested against attacks, not just examples** - the SQL and PII boundary is checked with an
+  adversarial corpus of hostile statements, property-based tests (token isolation, tamper
+  resistance), a live attack run against a really writable login with before/after snapshots, and
+  mutation testing. Results are in
+  [Verification of the SQL boundary](SECURITY-MODEL.md#verification-of-the-sql-boundary).
+- **Diagnosable failures** - a timeout or connection error carries a `Reference`, and the stderr
+  log records the connection stage, elapsed time, and driver error for the same reference, with
+  credentials removed. See [Logging](docs/configuration.md#logging).
 - **On PyPI** - `uvx sql-safe-mcp`, no repo clone required.
 
 | Tool | Access | Purpose |
@@ -129,7 +137,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.2.0`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.3.0`.
 
 Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -152,6 +160,32 @@ servers:
     connection_url: "${REPORTING_SQL_URL}"
 ```
 
+`connection_url` is a SQLAlchemy URL whose dialect must match `engine`. It is a secret, so keep the
+credentials in environment variables and reference them with `${NAME}`:
+
+```yaml
+servers:
+  # The whole URL comes from one variable (it may hold any valid URL).
+  reporting:
+    engine: sqlserver
+    connection_url: "${REPORTING_SQL_URL}"
+
+  # SQL Server (mssql+pyodbc), URL assembled from parts. Embedded placeholders are
+  # URL-encoded, so a password containing @ or / is safe.
+  billing:
+    engine: sqlserver
+    connection_url: >-
+      mssql+pyodbc://${BILLING_USER}:${BILLING_PASSWORD}@${BILLING_HOST}/master
+      ?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes
+
+  # MySQL or MariaDB (mysql+pymysql). Use engine: mariadb for MariaDB.
+  shop:
+    engine: mysql
+    connection_url: "mysql+pymysql://${SHOP_USER}:${SHOP_PASSWORD}@db.internal/shop"
+```
+
+A missing variable, or an `engine` that does not match the URL dialect, stops the server at startup.
+
 Point the server at the file with `SQL_SAFE_MCP_CONFIG` (or `--config`), and check it without
 connecting to any database:
 

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/README.md

@@ -6,12 +6,12 @@ A read-only, PII-safe SQL Server, MySQL and MariaDB MCP server for coding agents
 
 [![CI](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/proprock/sql-safe-mcp/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/proprock/sql-safe-mcp)](https://github.com/proprock/sql-safe-mcp/releases)
-[![PyPI Version](https://img.shields.io/pypi/v/sql-safe-mcp)](https://pypi.org/project/sql-safe-mcp/)
+[![PyPI Version](https://img.shields.io/pypi/v/sql-safe-mcp?cacheSeconds=3600)](https://pypi.org/project/sql-safe-mcp/)
 [![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 [![Model Context Protocol compatible](https://img.shields.io/badge/Model_Context_Protocol-compatible-000000?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
-[![MCP Registry: io.github.proprock/sql-safe-mcp](https://img.shields.io/badge/MCP_Registry-io.github.proprock%2Fsql--mini--mcp-000000?logo=modelcontextprotocol&logoColor=white)](server.json)
+[![MCP Registry: io.github.proprock/sql-safe-mcp](https://img.shields.io/badge/MCP_Registry-io.github.proprock%2Fsql--safe--mcp-000000?logo=modelcontextprotocol&logoColor=white)](server.json)
 
 <img src="https://raw.githubusercontent.com/proprock/sql-safe-mcp/master/images/luna-guard.jpg" alt="Read the data. Protect the identity." width="760">
 
@@ -52,6 +52,14 @@ databases, tables, columns, keys, indexes, stored procedures - and, on servers y
   case-insensitive name filters, and stored procedure lists that do not expand definitions.
 - **Errors an agent can act on** - an ambiguous name lists the candidate schemas. Errors never
   contain connection details, credentials, keys, tokens, or rows.
+- **Tested against attacks, not just examples** - the SQL and PII boundary is checked with an
+  adversarial corpus of hostile statements, property-based tests (token isolation, tamper
+  resistance), a live attack run against a really writable login with before/after snapshots, and
+  mutation testing. Results are in
+  [Verification of the SQL boundary](SECURITY-MODEL.md#verification-of-the-sql-boundary).
+- **Diagnosable failures** - a timeout or connection error carries a `Reference`, and the stderr
+  log records the connection stage, elapsed time, and driver error for the same reference, with
+  credentials removed. See [Logging](docs/configuration.md#logging).
 - **On PyPI** - `uvx sql-safe-mcp`, no repo clone required.
 
 | Tool | Access | Purpose |
@@ -91,7 +99,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.2.0`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.3.0`.
 
 Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -114,6 +122,32 @@ servers:
     connection_url: "${REPORTING_SQL_URL}"
 ```
 
+`connection_url` is a SQLAlchemy URL whose dialect must match `engine`. It is a secret, so keep the
+credentials in environment variables and reference them with `${NAME}`:
+
+```yaml
+servers:
+  # The whole URL comes from one variable (it may hold any valid URL).
+  reporting:
+    engine: sqlserver
+    connection_url: "${REPORTING_SQL_URL}"
+
+  # SQL Server (mssql+pyodbc), URL assembled from parts. Embedded placeholders are
+  # URL-encoded, so a password containing @ or / is safe.
+  billing:
+    engine: sqlserver
+    connection_url: >-
+      mssql+pyodbc://${BILLING_USER}:${BILLING_PASSWORD}@${BILLING_HOST}/master
+      ?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes
+
+  # MySQL or MariaDB (mysql+pymysql). Use engine: mariadb for MariaDB.
+  shop:
+    engine: mysql
+    connection_url: "mysql+pymysql://${SHOP_USER}:${SHOP_PASSWORD}@db.internal/shop"
+```
+
+A missing variable, or an `engine` that does not match the URL dialect, stops the server at startup.
+
 Point the server at the file with `SQL_SAFE_MCP_CONFIG` (or `--config`), and check it without
 connecting to any database:
 

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-safe-mcp"
-version = "1.2.0"
+version = "1.3.0"
 description = "Minimal, read-only, PII-safe MCP server for SQL databases."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/proprock/sql-safe-mcp",
     "source": "github"
   },
-  "version": "1.2.0",
+  "version": "1.3.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "sql-safe-mcp",
-      "version": "1.2.0",
+      "version": "1.3.0",
       "transport": {
         "type": "stdio"
       }

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/sql-safe-mcp.example.yaml

@@ -1,5 +1,8 @@
 version: 1
 
+logging:
+  level: INFO
+
 runtime:
   max_concurrent_db_operations: 8
   engine_cache_size: 32

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/src/sql_safe_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Minimal, PII-safe MCP server for relational databases."""
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/src/sql_safe_mcp/config.py

@@ -43,6 +43,12 @@ class RuntimeConfig(BaseModel):
         return self
 
 
+class LoggingConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+
+
 class PiiRule(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
@@ -113,6 +119,7 @@ class AppConfig(BaseModel):
 
     version: Literal[1]
     runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
     servers: dict[str, ServerConfig] = Field(min_length=1)
 
     @model_validator(mode="after")

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/src/sql_safe_mcp/db/registry.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import logging
+import time
 from collections import OrderedDict
 from collections.abc import Callable
 from threading import RLock
@@ -9,9 +11,11 @@ import anyio
 from sqlalchemy import Engine, create_engine, event
 
 from sql_safe_mcp.config import AppConfig
+from sql_safe_mcp.diagnostics import describe_error, secrets_for
 from sql_safe_mcp.errors import DomainError, ErrorCode
 
 T = TypeVar("T")
+logger = logging.getLogger(__name__)
 
 
 class EngineRegistry:
@@ -48,6 +52,30 @@ class EngineRegistry:
             **options,
         )
 
+        secrets = secrets_for(server.connection_url.get_secret_value(), alias)
+
+        @event.listens_for(engine, "do_connect")
+        def connect_and_log(dialect: Any, _record: Any, cargs: Any, cparams: Any) -> Any:
+            started = time.perf_counter()
+            try:
+                connection = dialect.connect(*cargs, **cparams)
+            except Exception as exc:
+                logger.warning(
+                    "connect failed server=%s database=%s elapsed_ms=%d error=%s",
+                    alias,
+                    database or "-",
+                    (time.perf_counter() - started) * 1000,
+                    describe_error(exc, secrets),
+                )
+                raise
+            logger.info(
+                "connect ok server=%s database=%s elapsed_ms=%d",
+                alias,
+                database or "-",
+                (time.perf_counter() - started) * 1000,
+            )
+            return connection
+
         @event.listens_for(engine, "connect")
         def set_connection_timeout(dbapi_connection: Any, _record: Any) -> None:
             if hasattr(dbapi_connection, "timeout"):
@@ -95,8 +123,17 @@ class EngineRegistry:
                 return engine
             engine = self._create_engine(alias, database)
             self._engines[key] = engine
+            logger.debug(
+                "engine created server=%s engine=%s database=%s",
+                alias,
+                self._config.servers[alias].engine,
+                database or "-",
+            )
             if len(self._engines) > self._config.runtime.engine_cache_size:
-                _, evicted = self._engines.popitem(last=False)
+                evicted_key, evicted = self._engines.popitem(last=False)
+                logger.debug(
+                    "engine evicted server=%s database=%s", evicted_key[0], evicted_key[1] or "-"
+                )
         if evicted is not None:
             evicted.dispose()
         return engine

sql_safe_mcp-1.3.0/src/sql_safe_mcp/diagnostics.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Iterable
+from urllib.parse import quote
+
+from sqlalchemy.engine import make_url
+
+_MAX_MESSAGE_CHARS = 500
+_CONTROL_CHARACTERS = re.compile(r"[\x00-\x1f\x7f]+")
+
+
+def configure_logging(level: str) -> None:
+    logging.getLogger("sql_safe_mcp").setLevel(level)
+    # SQLAlchemy inherits the root level and would echo statements with bind values at DEBUG.
+    logging.getLogger("sqlalchemy").setLevel(logging.WARNING)
+
+
+def secrets_for(url: str, alias: str) -> tuple[tuple[str, str], ...]:
+    """Redactions for a connection URL: credentials become ``***``, the host the server alias."""
+    try:
+        parsed = make_url(url)
+    except Exception:
+        return ()
+    found: dict[str, str] = {}
+    for value, replacement in (
+        (parsed.password, "***"),
+        (parsed.username, "***"),
+        (parsed.host, alias),
+    ):
+        if value:
+            found[value] = replacement
+            found[quote(value, safe="")] = replacement
+    return tuple(found.items())
+
+
+def _driver_parts(exc: BaseException) -> tuple[str, str, str]:
+    orig = getattr(exc, "orig", None) or exc
+    args = orig.args
+    if len(args) >= 2 and isinstance(args[0], int):
+        return type(orig).__name__, f" code={args[0]}", str(args[1])
+    if len(args) >= 2 and isinstance(args[0], str) and isinstance(args[1], str):
+        return type(orig).__name__, f" sqlstate={args[0]}", args[1]
+    return type(orig).__name__, "", str(orig)
+
+
+def _secret_pattern(secret: str) -> str:
+    # Whole-word only where the edge is a word character, so "sa" spares "usage" but a
+    # password ending in punctuation is still removed.
+    start = r"(?<!\w)" if re.match(r"\w", secret[0]) else ""
+    end = r"(?!\w)" if re.match(r"\w", secret[-1]) else ""
+    return f"{start}{re.escape(secret)}{end}"
+
+
+def describe_error(exc: BaseException, redactions: Iterable[tuple[str, str]]) -> str:
+    """One log-safe line for a driver error: class, SQLSTATE or code, redacted message."""
+    name, code, message = _driver_parts(exc)
+    for secret, replacement in sorted(set(redactions), key=lambda pair: len(pair[0]), reverse=True):
+        if secret:
+            message = re.sub(
+                _secret_pattern(secret),
+                lambda _, text=replacement: text,
+                message,
+                flags=re.IGNORECASE,
+            )
+    message = _CONTROL_CHARACTERS.sub(" ", message).strip()
+    if len(message) > _MAX_MESSAGE_CHARS:
+        message = message[:_MAX_MESSAGE_CHARS] + "..."
+    return f"{name}{code} message={message}"

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/src/sql_safe_mcp/mcp_server.py

@@ -10,6 +10,7 @@ from mcp_types import ToolAnnotations
 
 from sql_safe_mcp.config import AppConfig
 from sql_safe_mcp.db.registry import EngineRegistry
+from sql_safe_mcp.diagnostics import configure_logging
 from sql_safe_mcp.errors import DomainError
 from sql_safe_mcp.models import (
     DatabaseList,
@@ -47,11 +48,13 @@ def create_server(config: AppConfig) -> MCPServer[AppContext]:
         finally:
             registry.dispose()
 
+    configure_logging(config.logging.level)
     server: MCPServer[AppContext] = MCPServer(
         "sql-safe-mcp",
         description="Minimal, read-only, PII-safe SQL database navigation.",
-        version="1.2.0",
+        version="1.3.0",
         lifespan=lifespan,
+        log_level=config.logging.level,
     )
 
     @server.tool(annotations=READ_ONLY)

{sql_safe_mcp-1.2.0 → sql_safe_mcp-1.3.0}/src/sql_safe_mcp/service.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import logging
+import time
 from collections.abc import Callable
 from typing import TypeVar
+from uuid import uuid4
 
 from sqlalchemy import Connection, Engine
 from sqlalchemy.exc import DBAPIError, OperationalError, SQLAlchemyError
@@ -13,6 +15,7 @@ from sql_safe_mcp.db.extras import extras_for
 from sql_safe_mcp.db.reflection import get_table_definition as reflect_table_definition
 from sql_safe_mcp.db.reflection import list_tables as reflect_tables
 from sql_safe_mcp.db.registry import EngineRegistry
+from sql_safe_mcp.diagnostics import describe_error, secrets_for
 from sql_safe_mcp.errors import DomainError, ErrorCode
 from sql_safe_mcp.models import (
     ColumnSource,
@@ -42,6 +45,24 @@ _SCHEMA_CACHE_TTL_SECONDS = 300.0
 T = TypeVar("T")
 
 
+def _timeout_error() -> DomainError:
+    return DomainError(
+        ErrorCode.TIMEOUT,
+        "The database operation timed out.",
+        retryable=True,
+        correlation_id=uuid4().hex,
+    )
+
+
+def _connection_error() -> DomainError:
+    return DomainError(
+        ErrorCode.CONNECTION_FAILED,
+        "Could not connect to the configured database server.",
+        retryable=True,
+        correlation_id=uuid4().hex,
+    )
+
+
 def _contains(value: str, needle: str | None) -> bool:
     return needle is None or needle.casefold() in value.casefold()
 
@@ -76,55 +97,95 @@ class DatabaseService:
                 "Call list_servers to discover configured aliases.",
             ) from exc
 
-    async def _run(self, alias: str, database: str | None, operation: Callable[[Engine], T]) -> T:
+    def _classified(
+        self,
+        alias: str,
+        database: str | None,
+        operation: str,
+        error: DomainError,
+        cause: BaseException,
+    ) -> DomainError:
+        secrets = secrets_for(self.config.servers[alias].connection_url.get_secret_value(), alias)
+        logger.warning(
+            "operation failed server=%s database=%s operation=%s code=%s reference=%s error=%s",
+            alias,
+            database or "-",
+            operation,
+            error.code,
+            error.correlation_id or "-",
+            describe_error(cause, secrets),
+        )
+        return error
+
+    def _unexpected(
+        self, message: str, alias: str, database: str | None, operation: str, cause: BaseException
+    ) -> DomainError:
+        error = DomainError.unexpected()
+        logger.error(
+            "%s; server=%s database=%s operation=%s error_class=%s reference=%s",
+            message,
+            alias,
+            database or "-",
+            operation,
+            type(cause).__name__,
+            error.correlation_id,
+        )
+        return error
+
+    async def _run(
+        self,
+        alias: str,
+        database: str | None,
+        operation_name: str,
+        operation: Callable[[Engine], T],
+    ) -> T:
         self._server(alias)
+        started = time.perf_counter()
         try:
-            return await self.registry.run(alias, database, operation)
+            result = await self.registry.run(alias, database, operation)
         except DomainError:
             raise
         except SQLAlchemyTimeoutError as exc:
-            raise DomainError(
-                ErrorCode.TIMEOUT,
-                "The database operation timed out.",
-                retryable=True,
-            ) from exc
+            raise self._classified(alias, database, operation_name, _timeout_error(), exc) from exc
         except DBAPIError as exc:
             message = str(exc.orig).casefold()
             if any(value in message for value in ("timeout", "timed out", "hyt00", "hyt01")):
-                raise DomainError(
-                    ErrorCode.TIMEOUT, "The database operation timed out.", retryable=True
+                raise self._classified(
+                    alias, database, operation_name, _timeout_error(), exc
                 ) from exc
             if any(value in message for value in ("permission", "denied", "not authorized")):
-                raise DomainError(
-                    ErrorCode.ACCESS_DENIED, "The database denied this operation."
+                raise self._classified(
+                    alias,
+                    database,
+                    operation_name,
+                    DomainError(ErrorCode.ACCESS_DENIED, "The database denied this operation."),
+                    exc,
                 ) from exc
             if any(
                 value in message for value in ("cannot open database", "(4060)", "08001", "08004")
-            ):
-                raise DomainError(
-                    ErrorCode.CONNECTION_FAILED,
-                    "Could not connect to the configured database server.",
-                    retryable=True,
-                ) from exc
-            if isinstance(exc, OperationalError):
-                raise DomainError(
-                    ErrorCode.CONNECTION_FAILED,
-                    "Could not connect to the configured database server.",
-                    retryable=True,
+            ) or isinstance(exc, OperationalError):
+                raise self._classified(
+                    alias, database, operation_name, _connection_error(), exc
                 ) from exc
-            error = DomainError.unexpected()
-            logger.error("Database operation failed; reference=%s", error.correlation_id)
-            raise error from exc
+            raise self._unexpected(
+                "Database operation failed", alias, database, operation_name, exc
+            ) from exc
         except SQLAlchemyError as exc:
-            error = DomainError.unexpected()
-            logger.error("SQLAlchemy operation failed; reference=%s", error.correlation_id)
-            raise error from exc
+            raise self._unexpected(
+                "SQLAlchemy operation failed", alias, database, operation_name, exc
+            ) from exc
         except Exception as exc:
-            error = DomainError.unexpected()
-            logger.error(
-                "Unexpected database operation failure; reference=%s", error.correlation_id
-            )
-            raise error from exc
+            raise self._unexpected(
+                "Unexpected database operation failure", alias, database, operation_name, exc
+            ) from exc
+        logger.info(
+            "operation ok server=%s database=%s operation=%s elapsed_ms=%d",
+            alias,
+            database or "-",
+            operation_name,
+            (time.perf_counter() - started) * 1000,
+        )
+        return result
 
     def list_servers(self) -> ServerList:
         return ServerList(
@@ -143,7 +204,7 @@ class DatabaseService:
             with engine.connect() as connection:
                 return extras_for(configured.engine).list_databases(connection)
 
-        names = await self._run(server, None, operation)
+        names = await self._run(server, None, "list_databases", operation)
         return DatabaseList(
             databases=[
                 DatabaseSummary(name=name)
@@ -165,7 +226,7 @@ class DatabaseService:
             with engine.connect() as connection:
                 return reflect_tables(connection)
 
-        tables = await self._run(server, database, operation)
+        tables = await self._run(server, database, "list_tables", operation)
         selected = [
             table
             for table in tables
@@ -204,7 +265,7 @@ class DatabaseService:
                 selected = self._resolve_table(reflect_tables(connection), table, schema)
                 return reflect_table_definition(connection, selected.schema_, selected.name)
 
-        return await self._run(server, database, operation)
+        return await self._run(server, database, "get_table_definition", operation)
 
     async def list_stored_procedures(
         self,
@@ -219,7 +280,7 @@ class DatabaseService:
             with engine.connect() as connection:
                 return extras_for(configured.engine).list_stored_procedures(connection, database)
 
-        procedures = await self._run(server, database, operation)
+        procedures = await self._run(server, database, "list_stored_procedures", operation)
         selected = [
             item
             for item in procedures
@@ -258,7 +319,7 @@ class DatabaseService:
                     connection, database, selected.schema_, selected.name
                 )
 
-        result = await self._run(server, database, operation)
+        result = await self._run(server, database, "get_stored_procedure", operation)
         if result is None:
             raise DomainError(ErrorCode.NOT_FOUND, f"Stored procedure {name!r} was not found.")
         if (
@@ -322,4 +383,4 @@ class DatabaseService:
                 truncated=executed.truncated,
             )
 
-        return await self._run(server, database, operation)
+        return await self._run(server, database, "execute_sql", operation)