Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Enhance SQLAlchemy engine with safe_execute and inspector methods for SnowFlake (#8920)

mauro-cerzosimo463520497e65
diff --git a/marimo/_sql/engines/sqlalchemy.py b/marimo/_sql/engines/sqlalchemy.py
index dd2163e00c..638e7ab186 100644
--- a/marimo/_sql/engines/sqlalchemy.py
+++ b/marimo/_sql/engines/sqlalchemy.py
@@ -1,7 +1,19 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import TYPE_CHECKING, Any, Literal, Optional, Union
+import functools
+import re
+from contextlib import contextmanager
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Callable,
+ Literal,
+ Optional,
+ ParamSpec,
+ TypeVar,
+ Union,
+)
from marimo import _loggers
from marimo._data.models import (
@@ -24,12 +36,68 @@ from marimo._types.ids import VariableName
LOGGER = _loggers.marimo_logger()
if TYPE_CHECKING:
+ from collections.abc import Iterator
+
import pandas as pd
import polars as pl
from sqlalchemy import Engine, Inspector
from sqlalchemy.engine.cursor import CursorResult
+ from sqlalchemy.engine.interfaces import ReflectedColumn, ReflectedIndex
from sqlalchemy.sql.type_api import TypeEngine
+# Quote if the identifier contains anything other than letters, digits, underscores, or dollar signs.
+_SNOWFLAKE_NEEDS_QUOTING_RE = re.compile(r"[^A-Za-z0-9_$]")
+
+
+# ------------------------------------------------------------------ #
+# Decorators #
+# ------------------------------------------------------------------ #
+
+
+T = TypeVar("T")
+P = ParamSpec("P")
+F = TypeVar("F")
+
+
+def safe_execute(
+ *,
+ fallback: F,
+ message: str = "Operation failed",
+ log_level: Literal["debug", "info", "warning", "error"] = "warning",
+ silent_exceptions: tuple[type[BaseException], ...] = (),
+) -> Callable[[Callable[P, T]], Callable[P, T | F]]:
+ """Catch exceptions, log them, and return a fallback value.
+
+ Args:
+ fallback: Value returned when the wrapped function raises.
+ message: Message written to the logger on failure.
+ log_level: Logger level – must be one of
+ ``'debug'``, ``'info'``, ``'warning'``, or ``'error'``.
+ silent_exceptions: Exception types that should return *fallback*
+ without any logging. Useful for expected control-flow
+ exceptions like ``NotImplementedError``.
+ """
+
+ def decorator(func: Callable[P, T]) -> Callable[P, T | F]:
+ @functools.wraps(func)
+ def wrapper(*args: P.args, **kwargs: P.kwargs) -> T | F:
+ try:
+ return func(*args, **kwargs)
+ except silent_exceptions:
+ return fallback
+ except Exception:
+ getattr(LOGGER, log_level)(message, exc_info=True)
+ return fallback
+
+ return wrapper
+
+ return decorator
+
+
+# ------------------------------------------------------------------ #
+# SQLAlchemyEngine #
+# ------------------------------------------------------------------ #
+
class SQLAlchemyEngine(SQLConnection["Engine"]):
"""SQLAlchemy engine."""
@@ -52,6 +120,56 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
self.default_database = self.get_default_database()
self.default_schema = self.get_default_schema()
+ def _quote_identifier(self, identifier: str) -> str:
+ """Quote an identifier based on the SQL dialect's quoting rules."""
+ dialect_quoting: dict[str, tuple[re.Pattern[str], str, str]] = {
+ "snowflake": (_SNOWFLAKE_NEEDS_QUOTING_RE, '"', '"'),
+ }
+
+ if self.dialect not in dialect_quoting:
+ return identifier
+
+ pattern, open_quote, close_quote = dialect_quoting[self.dialect]
+ if pattern.search(identifier) or identifier != identifier.lower():
+ escaped = identifier.replace(
+ close_quote, close_quote + close_quote
+ )
+ return f"{open_quote}{escaped}{close_quote}"
+ return identifier
+
+ @contextmanager
+ def _get_inspector(self, database: str) -> Iterator[Optional[Inspector]]:
+ """Yield an appropriate SQLAlchemy Inspector for the given database.
+
+ For dialects that require a USE DATABASE command (e.g. Snowflake),
+ this opens a connection, executes the command, and yields an
+ inspector bound to that connection.
+
+ For all other dialects, it yields ``self.inspector`` (which may
+ be ``None``).
+
+ Usage::
+
+ with self._get_inspector(database) as inspector:
+ if inspector is None:
+ return []
+ return inspector.get_schema_names()
+ """
+
+ from sqlalchemy import inspect, text
+
+ _use_database_dialect_command: dict[str, str] = {
+ "snowflake": f"USE DATABASE {self._quote_identifier(database)}",
+ }
+ dialect_command = _use_database_dialect_command.get(self.dialect)
+
+ if dialect_command is not None:
+ with self._connection.connect() as connection:
+ connection.execute(text(dialect_command))
+ yield inspect(connection)
+ else:
+ yield self.inspector
+
@property
def source(self) -> str:
return "sqlalchemy"
@@ -108,7 +226,7 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
@property
def inference_config(self) -> InferenceConfig:
return InferenceConfig(
- auto_discover_schemas=True,
+ auto_discover_schemas="auto",
auto_discover_tables="auto",
auto_discover_columns=False,
)
@@ -166,23 +284,87 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
return database_name or ""
+ @safe_execute(
+ fallback=None,
+ message="Failed to get default schema name",
+ log_level="warning",
+ )
def get_default_schema(self) -> Optional[str]:
"""Get the default schema name"""
if self.inspector is None:
return None
- try:
- default_schema_name = self.inspector.default_schema_name
- # https://github.com/marimo-team/marimo/issues/6436.
- # Upstream bug where default schema name is not a string.
- if default_schema_name is None or not isinstance(
- default_schema_name, str
- ):
- return None
- return str(default_schema_name)
- except Exception:
- LOGGER.warning("Failed to get default schema name", exc_info=True)
+ default_schema_name = self.inspector.default_schema_name
+ # https://github.com/marimo-team/marimo/issues/6436.
+ # Upstream bug where default schema name is not a string.
+ if default_schema_name is None or not isinstance(
+ default_schema_name, str
+ ):
return None
+ return str(default_schema_name)
+
+ # -------------------------------------------------------------- #
+ # Databases resolution #
+ # -------------------------------------------------------------- #
+
+ # Get database names for SNOWFLAKE
+ def _get_snowflake_database_names(self) -> list[str]:
+ """Get database names for Snowflake via 'SHOW DATABASES'.
+
+ If the default database exists in the results, return only that.
+ Otherwise, return all discovered databases.
+
+ Unquoted identifiers are normalized to lowercase for consistency.
+ Identifiers that need quoting are preserved as-is.
+ """
+ from sqlalchemy import text
+
+ with self._connection.connect() as connection:
+ result = connection.execute(text("SHOW DATABASES"))
+ columns = list(result.keys())
+
+ try:
+ name_col_index = columns.index("name")
+ except ValueError as err:
+ raise RuntimeError(
+ "Unexpected SHOW DATABASES result: "
+ f"'name' column not found in {columns}"
+ ) from err
+
+ database_names: list[str] = []
+ for row in result.fetchall():
+ raw_name = str(row[name_col_index])
+ if (
+ _SNOWFLAKE_NEEDS_QUOTING_RE.search(raw_name)
+ or raw_name != raw_name.upper()
+ ):
+ database_names.append(raw_name)
+ else:
+ database_names.append(raw_name.lower())
+
+ if self.default_database:
+ default_lower = self.default_database.lower()
+ for db in database_names:
+ if db.lower() == default_lower:
+ return [db]
+
+ return database_names
+
+ @safe_execute(
+ fallback=[],
+ message="Failed to get database names",
+ log_level="warning",
+ )
+ def _get_database_names(self) -> list[str]:
+ """Get database names using dialect-specific queries.
+
+ Returns a single-element list with the default database when
+ the dialect has no dedicated discovery mechanism.
+ """
+ if self.dialect.lower() == "snowflake":
+ return self._get_snowflake_database_names()
+
+ return [self.default_database] if self.default_database else []
def get_databases(
self,
@@ -194,44 +376,65 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
"""Get all databases from the engine.
Args:
- include_schemas: Whether to include schema information. If False, databases will have empty schemas.
- include_tables: Whether to include table information within schemas. If False, schemas will have empty tables.
- include_table_details: Whether to include each table's detailed information. If False, tables will have empty columns, PK, indexes.
+ include_schemas: Include schema information per database.
+ include_tables: Include table information within each schema.
+ include_table_details: Include columns, PKs, and indexes
+ for each table.
Returns:
List of Database objects representing the database structure.
- Note: This operation can be performance intensive when fetching full metadata.
+ Note:
+ This operation can be performance-intensive when fetching
+ full metadata.
"""
+ should_include_schemas = self._resolve_should_auto_discover(
+ include_schemas
+ )
+ should_include_tables = self._resolve_should_auto_discover(
+ include_tables
+ )
+ should_include_details = self._resolve_should_auto_discover(
+ include_table_details
+ )
+
databases: list[Database] = []
- if self.default_database is None:
- return databases
- database_name = self.default_database
-
- schemas = (
- self.get_schemas(
- database=database_name,
- include_tables=self._resolve_should_auto_discover(
- include_tables
- ),
- include_table_details=self._resolve_should_auto_discover(
- include_table_details
- ),
+ for database_name in self._get_database_names():
+ schemas = (
+ self.get_schemas(
+ database=database_name,
+ include_tables=should_include_tables,
+ include_table_details=should_include_details,
+ )
+ if should_include_schemas
+ else []
)
- if self._resolve_should_auto_discover(include_schemas)
- else []
- )
- databases.append(
- Database(
- name=database_name,
- dialect=self.dialect,
- schemas=schemas,
- engine=self._engine_name,
+ databases.append(
+ Database(
+ name=database_name,
+ dialect=self.dialect,
+ schemas=schemas,
+ engine=self._engine_name,
+ )
)
- )
+
return databases
+ # -------------------------------------------------------------- #
+ # Schemas resolution #
+ # -------------------------------------------------------------- #
+
+ @safe_execute(
+ fallback=[], message="Failed to get schema names", log_level="warning"
+ )
+ def _get_schema_names(self, database: str) -> list[str]:
+
+ with self._get_inspector(database) as inspector:
+ if inspector is None:
+ return []
+ return inspector.get_schema_names()
+
def get_schemas(
self,
*,
@@ -241,13 +444,11 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
) -> list[Schema]:
"""Get all schemas and optionally their tables. Keys are schema names."""
- if self.inspector is None:
- return []
- try:
- schema_names = self.inspector.get_schema_names()
- except Exception:
- LOGGER.warning("Failed to get schema names", exc_info=True)
- return []
+ if database is None:
+ schema_names: list[str] = []
+ else:
+ schema_names = self._get_schema_names(database)
+
schemas: list[Schema] = []
for schema in schema_names:
@@ -269,20 +470,34 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
return ["information_schema", "pg_catalog"]
return ["information_schema"]
+ # -------------------------------------------------------------- #
+ # Tables resolution #
+ # -------------------------------------------------------------- #
+
+ @safe_execute(
+ fallback=([], []),
+ message="Failed to get tables in schema",
+ log_level="warning",
+ )
+ def _get_table_names(
+ self, schema: str, database: str
+ ) -> tuple[list[str], list[str]]:
+
+ with self._get_inspector(database) as inspector:
+ if inspector is None:
+ return [], []
+ return inspector.get_table_names(
+ schema=schema
+ ), inspector.get_view_names(schema=schema)
+
def get_tables_in_schema(
self, *, schema: str, database: str, include_table_details: bool
) -> list[DataTable]:
"""Return all tables in a schema."""
- _ = database
- if self.inspector is None:
- return []
- try:
- table_names = self.inspector.get_table_names(schema=schema)
- view_names = self.inspector.get_view_names(schema=schema)
- except Exception:
- LOGGER.warning("Failed to get tables in schema", exc_info=True)
- return []
+ table_names, view_names = self._get_table_names(
+ schema=schema, database=database
+ )
tables: list[tuple[DataTableType, str]] = []
for name in table_names:
@@ -319,48 +534,77 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
return data_tables
+ # -------------------------------------------------------------- #
+ # Table Details resolution #
+ # -------------------------------------------------------------- #
+
+ @safe_execute(
+ fallback=None,
+ message="Failed to get table details",
+ log_level="warning",
+ )
+ def _get_columns(
+ self, table_name: str, schema: str, database: str
+ ) -> Optional[list[ReflectedColumn]]:
+
+ with self._get_inspector(database) as inspector:
+ if inspector is None:
+ return None
+ return inspector.get_columns(table_name, schema=schema)
+
+ @safe_execute(fallback=[], message="Failed to get primary keys")
+ def _fetch_primary_keys(
+ self, table_name: str, schema: str, database: str
+ ) -> list[str]:
+
+ with self._get_inspector(database) as inspector:
+ if inspector is None:
+ return []
+ return inspector.get_pk_constraint(table_name, schema=schema).get(
+ "constrained_columns", []
+ )
+
+ @safe_execute(fallback=[], message="Failed to get indexes")
+ def _fetch_indexes(
+ self, table_name: str, schema: str, database: str
+ ) -> list[str]:
+
+ with self._get_inspector(database) as inspector:
+ if inspector is None:
+ return []
+ indexes = inspector.get_indexes(table_name, schema=schema)
+ return self._extract_index_columns(indexes)
+
+ @staticmethod
+ def _extract_index_columns(indexes: list[ReflectedIndex]) -> list[str]:
+ """Extract and deduplicate column names from a list of index definitions."""
+ index_columns: list[str] = []
+ seen: set[str] = set()
+ for index in indexes:
+ if index_cols := index.get("column_names"):
+ for col in index_cols:
+ if col is not None and col not in seen:
+ seen.add(col)
+ index_columns.append(col)
+ return index_columns
+
def get_table_details(
self, *, table_name: str, schema_name: str, database_name: str
) -> Optional[DataTable]:
"""Get a single table from the engine."""
- _ = database_name
- if self.inspector is None:
- return None
- try:
- columns = self.inspector.get_columns(
- table_name, schema=schema_name
- )
- except Exception:
- LOGGER.warning(
- f"Failed to get table {table_name} in schema {schema_name}",
- exc_info=True,
- )
+ columns = self._get_columns(
+ table_name, schema=schema_name, database=database_name
+ )
+ if columns is None:
return None
- primary_keys: list[str] = []
- index_list: list[str] = []
-
- try:
- primary_keys = self.inspector.get_pk_constraint(
- table_name, schema=schema_name
- )["constrained_columns"]
- except Exception:
- pass
-
- # TODO: Handle multi column PK and indexes
- try:
- indexes = self.inspector.get_indexes(
- table_name, schema=schema_name
- )
- for index in indexes:
- if index_cols := index["column_names"]:
- index_list.extend(
- col for col in index_cols if col is not None
- )
- except Exception:
- LOGGER.warning("Failed to get indexes", exc_info=True)
- pass
+ primary_keys = self._fetch_primary_keys(
+ table_name, schema_name, database_name
+ )
+ index_list = self._fetch_indexes(
+ table_name, schema_name, database_name
+ )
cols: list[DataTableColumn] = []
for col in columns:
@@ -393,29 +637,29 @@ class SQLAlchemyEngine(SQLConnection["Engine"]):
indexes=index_list,
)
+ @safe_execute(
+ fallback=None,
+ message="Failed to get column type",
+ log_level="warning",
+ silent_exceptions=(NotImplementedError,),
+ )
def _get_python_type(
self, engine_type: TypeEngine[Any]
) -> DataType | None:
- try:
- col_type = engine_type.python_type
- return sql_type_to_data_type(str(col_type))
- except NotImplementedError:
- return None
- except Exception:
- LOGGER.debug("Failed to get python type", exc_info=True)
- return None
-
+ col_type = engine_type.python_type
+ return sql_type_to_data_type(str(col_type))
+
+ @safe_execute(
+ fallback=None,
+ message="Failed to get generic type",
+ log_level="debug",
+ silent_exceptions=(NotImplementedError,),
+ )
def _get_generic_type(
self, engine_type: TypeEngine[Any]
) -> DataType | None:
- try:
- col_type = engine_type.as_generic()
- return sql_type_to_data_type(str(col_type))
- except NotImplementedError:
- return None
- except Exception:
- LOGGER.debug("Failed to get generic type", exc_info=True)
- return None
+ col_type = engine_type.as_generic()
+ return sql_type_to_data_type(str(col_type))
def _resolve_should_auto_discover(
self,
diff --git a/tests/_sql/test_sqlalchemy.py b/tests/_sql/test_sqlalchemy.py
index 67dd50cc03..0fc23c705b 100644
--- a/tests/_sql/test_sqlalchemy.py
+++ b/tests/_sql/test_sqlalchemy.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+from contextlib import contextmanager
from typing import TYPE_CHECKING
from unittest import mock
@@ -9,9 +10,7 @@ import pytest
from marimo._data.models import Database, DataTable, DataTableColumn, Schema
from marimo._dependencies.dependencies import DependencyManager
-from marimo._sql.engines.sqlalchemy import (
- SQLAlchemyEngine,
-)
+from marimo._sql.engines.sqlalchemy import SQLAlchemyEngine, safe_execute
from marimo._sql.engines.types import EngineCatalog, QueryEngine
from marimo._sql.sql import sql
from marimo._types.ids import VariableName
@@ -709,3 +708,550 @@ def test_sqlalchemy_engine_get_cursor_metadata(
metadata = SQLAlchemyEngine.get_cursor_metadata(result)
assert metadata is not None
assert metadata["sql_statement_type"] == "Query / Unknown"
+
+
+# ------------------------
+# Decoracotors
+# ------------------------
+
+
+def test_returns_function_result_on_success():
+ @safe_execute(fallback=None)
+ def add(a, b):
+ return a + b
+
+ assert add(1, 2) == 3
+
+
+def test_returns_fallback_on_exception():
+ @safe_execute(fallback="oops")
+ def fail():
+ raise ValueError("boom")
+
+ assert fail() == "oops"
+
+
[email protected]("marimo._sql.engines.sqlalchemy.LOGGER")
+def test_logs_on_exception(mock_logger):
+ @safe_execute(
+ fallback=None, message="something broke", log_level="warning"
+ )
+ def fail():
+ raise TypeError("bad type")
+
+ fail()
+
+ mock_logger.warning.assert_called_once_with(
+ "something broke", exc_info=True
+ )
+
+
[email protected]("marimo._sql.engines.sqlalchemy.LOGGER")
+def test_respects_log_level_debug(mock_logger):
+ @safe_execute(fallback=None, message="debug msg", log_level="debug")
+ def fail():
+ raise RuntimeError
+
+ fail()
+
+ mock_logger.debug.assert_called_once_with("debug msg", exc_info=True)
+
+
[email protected]("marimo._sql.engines.sqlalchemy.LOGGER")
+def test_respects_log_level_error(mock_logger):
+ @safe_execute(fallback=None, message="error msg", log_level="error")
+ def fail():
+ raise RuntimeError
+
+ fail()
+
+ mock_logger.error.assert_called_once_with("error msg", exc_info=True)
+
+
[email protected]("marimo._sql.engines.sqlalchemy.LOGGER")
+def test_silent_exceptions_no_logging(mock_logger):
+ @safe_execute(
+ fallback=[],
+ silent_exceptions=(NotImplementedError,),
+ )
+ def fail():
+ raise NotImplementedError
+
+ result = fail()
+
+ assert result == []
+ mock_logger.warning.assert_not_called()
+ mock_logger.debug.assert_not_called()
+ mock_logger.error.assert_not_called()
+ mock_logger.info.assert_not_called()
+
+
[email protected]("marimo._sql.engines.sqlalchemy.LOGGER")
+def test_silent_exceptions_still_logs_other_errors(mock_logger):
+ @safe_execute(
+ fallback=-1,
+ message="caught",
+ log_level="error",
+ silent_exceptions=(NotImplementedError,),
+ )
+ def fail():
+ raise ValueError("not silent")
+
+ result = fail()
+
+ assert result == -1
+ mock_logger.error.assert_called_once_with("caught", exc_info=True)
+
+
+def test_preserves_function_metadata():
+ @safe_execute(fallback=None)
+ def my_func():
+ """My docstring."""
+ pass
+
+ assert my_func.__name__ == "my_func"
+ assert my_func.__doc__ == "My docstring."
+
+
+def test_passes_args_and_kwargs():
+ @safe_execute(fallback=None)
+ def greet(name, greeting="Hello"):
+ return f"{greeting}, {name}!"
+
+ assert greet("Alice") == "Hello, Alice!"
+ assert greet("Bob", greeting="Hi") == "Hi, Bob!"
+
+
+def test_fallback_can_be_any_type():
+ for fallback in (0, False, "", [], {}):
+
+ @safe_execute(fallback=fallback)
+ def fail():
+ raise RuntimeError
+
+ assert fail() == fallback
+
+
+# ------------------------
+# Tests for inspector methods
+# ------------------------
+
+
+def make_engine():
+ """Factory to create a SQLAlchemyEngine with a mocked Snowflake inspector."""
+
+ def _factory(
+ *,
+ dialect="snowflake",
+ default_database="MY_DB",
+ schema_names=None,
+ table_names=None,
+ view_names=None,
+ table_columns=None,
+ columns=None,
+ rows=None,
+ pk_constraint=None,
+ indexes=None,
+ inspector=True,
+ ):
+ if columns is None:
+ columns = [
+ "created_on",
+ "name",
+ "is_default",
+ "is_current",
+ "origin",
+ ]
+ if rows is None:
+ rows = []
+
+ # -- Mock query results --
+ mock_result = mock.MagicMock()
+ mock_result.keys.return_value = columns
+ mock_result.fetchall.return_value = rows
+
+ mock_conn = mock.MagicMock()
+ mock_conn.execute.return_value = mock_result
+
+ # -- Mock inspector --
+ mock_inspector = None
+ if inspector:
+ mock_inspector = mock.MagicMock()
+ mock_inspector.get_schema_names.return_value = schema_names or []
+ mock_inspector.get_table_names.return_value = table_names or []
+ mock_inspector.get_view_names.return_value = view_names or []
+ mock_inspector.get_columns.return_value = table_columns or []
+ mock_inspector.get_pk_constraint.return_value = pk_constraint or {
+ "constrained_columns": []
+ }
+ mock_inspector.get_indexes.return_value = indexes or []
+
+ # -- Mock SQLAlchemy engine --
+ mock_sa_engine = mock.MagicMock()
+ mock_sa_engine.dialect.name = dialect
+ mock_sa_engine.url.database = default_database
+ mock_sa_engine.connect.return_value = mock.MagicMock(
+ __enter__=mock.MagicMock(return_value=mock_conn),
+ __exit__=mock.MagicMock(return_value=False),
+ )
+
+ # Patch inspect() so __init__ assigns our configured mock
+ with mock.patch("sqlalchemy.inspect", return_value=mock_inspector):
+ engine = SQLAlchemyEngine(
+ mock_sa_engine, engine_name=VariableName("test")
+ )
+
+ # Point _connection to the mock so execute() calls work
+ engine._connection = mock_sa_engine
+
+ # Override _get_inspector to yield our mock inspector.
+ # Uses *_args, **_kwargs to match any signature the real
+ # method may have (e.g. database parameter) without
+ # global side effects.
+ @contextmanager
+ def fake_get_inspector(database=None):
+ _ = database # ignore parameter
+ yield mock_inspector
+
+ engine._get_inspector = fake_get_inspector
+
+ # Expose mocks for test assertions
+ engine._mock_inspector = mock_inspector
+ engine._mock_conn = mock_conn
+
+ return engine
+
+ return _factory
+
+
+# ------------------------------------------------------------------ #
+# _get_inspector
+# ------------------------------------------------------------------ #
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_inspector_executes_use_database():
+ """executes dialect command and inspects the connection."""
+ mock_conn = mock.MagicMock()
+ mock_command = mock.MagicMock()
+
+ mock_sa_engine = mock.MagicMock()
+ mock_sa_engine.dialect.name = "snowflake"
+ mock_sa_engine.url.database = "MY_DB"
+ mock_sa_engine.connect.return_value.__enter__ = mock.MagicMock(
+ return_value=mock_conn
+ )
+ mock_sa_engine.connect.return_value.__exit__ = mock.MagicMock(
+ return_value=False
+ )
+
+ engine = SQLAlchemyEngine(mock_sa_engine, engine_name=VariableName("test"))
+
+ with mock.patch(
+ "sqlalchemy.inspect", return_value=mock_command
+ ) as patched_inspect:
+ with engine._get_inspector("my_db") as inspector:
+ assert inspector is mock_command
+ patched_inspect.assert_called_once_with(mock_conn)
+
+ # Verify USE DATABASE was executed
+ executed = mock_conn.execute.call_args[0][0]
+ assert str(executed) == "USE DATABASE my_db"
+
+ with mock.patch(
+ "sqlalchemy.inspect", return_value=mock_command
+ ) as patched_inspect:
+ with engine._get_inspector("MY_DB@MYDB") as inspector:
+ assert inspector is mock_command
+ patched_inspect.assert_called_once_with(mock_conn)
+
+ # Verify USE DATABASE was executed
+ executed = mock_conn.execute.call_args[0][0]
+ assert str(executed) == 'USE DATABASE "MY_DB@MYDB"'
+
+ with mock.patch(
+ "sqlalchemy.inspect", return_value=mock_command
+ ) as patched_inspect:
+ with engine._get_inspector("MY_db") as inspector:
+ assert inspector is mock_command
+ patched_inspect.assert_called_once_with(mock_conn)
+
+ # Verify USE DATABASE was executed
+ executed = mock_conn.execute.call_args[0][0]
+ assert str(executed) == 'USE DATABASE "MY_db"'
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_inspector_yields_existing_inspector_for_non_use_database_dialect():
+ """For dialects without USE DATABASE, yield self.inspector directly."""
+ mock_sa_engine = mock.MagicMock()
+ mock_sa_engine.dialect.name = "sqlite"
+ mock_sa_engine.url.database = ":memory:"
+
+ engine = SQLAlchemyEngine(mock_sa_engine, engine_name=VariableName("test"))
+
+ mock_inspector = mock.MagicMock()
+ engine.inspector = mock_inspector
+
+ with engine._get_inspector("any_database") as inspector:
+ assert inspector is mock_inspector
+
+ # Verify that NO connection was opened and no command was executed
+ mock_sa_engine.connect.assert_not_called()
+
+
+# ------------------------------------------------------------------ #
+# _get_schema_names
+# ------------------------------------------------------------------ #
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_schema_names(make_engine):
+ engine = make_engine(schema_names=["public", "staging"])
+ assert engine._get_schema_names("MY_DB") == ["public", "staging"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_schema_names_no_inspector(make_engine):
+ engine = make_engine(inspector=False)
+ assert engine._get_schema_names("MY_DB") == []
+
+
+# ------------------------------------------------------------------ #
+# _get_table_names
+# ------------------------------------------------------------------ #
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_table_names(make_engine):
+ engine = make_engine(
+ table_names=["users", "orders"], view_names=["active_users"]
+ )
+ tables, views = engine._get_table_names(schema="public", database="MY_DB")
+ assert tables == ["users", "orders"]
+ assert views == ["active_users"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_table_names_no_inspector(make_engine):
+ engine = make_engine(inspector=False)
+ assert engine._get_table_names(schema="public", database="MY_DB") == (
+ [],
+ [],
+ )
+
+
+# ------------------------------------------------------------------ #
+# _get_columns
+# ------------------------------------------------------------------ #
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_columns(make_engine):
+ cols = [
+ {"name": "id", "type": "INTEGER"},
+ {"name": "name", "type": "TEXT"},
+ ]
+ engine = make_engine(table_columns=cols)
+ result = engine._get_columns("users", schema="public", database="MY_DB")
+ assert result == cols
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_columns_no_inspector(make_engine):
+ engine = make_engine(inspector=False)
+ assert (
+ engine._get_columns("users", schema="public", database="MY_DB") is None
+ )
+
+
+# ------------------------------------------------------------------ #
+# _fetch_primary_keys
+# ------------------------------------------------------------------ #
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_fetch_primary_keys(make_engine):
+ engine = make_engine(
+ pk_constraint={"constrained_columns": ["id", "tenant_id"]}
+ )
+ result = engine._fetch_primary_keys(
+ "users", schema="public", database="MY_DB"
+ )
+ assert result == ["id", "tenant_id"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_fetch_primary_keys_no_inspector(make_engine):
+ engine = make_engine(inspector=False)
+ result = engine._fetch_primary_keys(
+ "users", schema="public", database="MY_DB"
+ )
+ assert result == []
+
+
+# ------------------------------------------------------------------ #
+# _fetch_indexes
+# ------------------------------------------------------------------ #
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_fetch_indexes(make_engine):
+ engine = make_engine(
+ indexes=[
+ {"column_names": ["email"], "name": "idx_email", "unique": True},
+ {"column_names": ["name"], "name": "idx_name", "unique": False},
+ ]
+ )
+ result = engine._fetch_indexes("users", schema="public", database="MY_DB")
+ assert result == ["email", "name"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_fetch_indexes_no_inspector(make_engine):
+ engine = make_engine(inspector=False)
+ result = engine._fetch_indexes("users", schema="public", database="MY_DB")
+ assert result == []
+
+
+# ------------------------------------------------------------------ #
+# _extract_index_columns (static, no mocking needed)
+# ------------------------------------------------------------------ #
+
+
+def test_extract_index_columns_deduplicates():
+ indexes = [
+ {"column_names": ["col_a", "col_b"]},
+ {"column_names": ["col_b", "col_c"]},
+ ]
+ assert SQLAlchemyEngine._extract_index_columns(indexes) == [
+ "col_a",
+ "col_b",
+ "col_c",
+ ]
+
+
+def test_extract_index_columns_skips_none():
+ indexes = [{"column_names": [None, "col_a", None]}]
+ assert SQLAlchemyEngine._extract_index_columns(indexes) == ["col_a"]
+
+
+def test_extract_index_columns_missing_key():
+ indexes = [{"name": "idx"}, {"column_names": ["col_a"]}]
+ assert SQLAlchemyEngine._extract_index_columns(indexes) == ["col_a"]
+
+
+def test_extract_index_columns_empty():
+ assert SQLAlchemyEngine._extract_index_columns([]) == []
+
+
+# ---------------------------------
+# Snowflake-specific GET databases
+# ---------------------------------
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_returns_all_in_lower_case_when_no_default(make_engine):
+ engine = make_engine(
+ default_database=None,
+ rows=[
+ ("2025-01-01", "DB_A", "N", "N", ""),
+ ("2025-01-02", "DB_B", "N", "N", ""),
+ ],
+ )
+ assert engine._get_snowflake_database_names() == ["db_a", "db_b"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_returns_only_default_when_present(make_engine):
+ engine = make_engine(
+ default_database="db_B",
+ rows=[
+ ("2025-01-01", "DB_A", "N", "N", ""),
+ ("2025-01-02", "DB_B", "N", "Y", ""),
+ ],
+ )
+ assert engine._get_snowflake_database_names() == ["db_b"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_get_snowflake_database_names_lowercases_unless_special_characters(
+ make_engine,
+):
+ engine = make_engine(
+ default_database=None,
+ rows=[
+ ("2025-01-01", "DB_A", "N", "N", ""),
+ ("2025-01-02", "DB_B", "N", "Y", ""),
+ ("2025-01-02", "USER@snow", "N", "Y", ""),
+ ],
+ )
+ assert engine._get_snowflake_database_names() == [
+ "db_a",
+ "db_b",
+ "USER@snow",
+ ]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_returns_all_when_default_not_in_results(make_engine):
+ engine = make_engine(
+ default_database="MISSING",
+ rows=[
+ ("2025-01-01", "DB_A", "N", "N", ""),
+ ("2025-01-02", "DB_B", "N", "Y", ""),
+ ],
+ )
+ assert engine._get_snowflake_database_names() == ["db_a", "db_b"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_returns_empty_list_when_no_rows(make_engine):
+ engine = make_engine(rows=[])
+ assert engine._get_snowflake_database_names() == []
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_raises_when_name_column_missing(make_engine):
+ engine = make_engine(columns=["id", "owner", "comment"])
+ with pytest.raises(RuntimeError, match="'name' column not found"):
+ engine._get_snowflake_database_names()
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_executes_show_databases(make_engine):
+ engine = make_engine()
+ engine._get_snowflake_database_names()
+ executed_sql = engine._mock_conn.execute.call_args[0][0]
+ assert str(executed_sql) == "SHOW DATABASES"
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_name_column_at_different_index(make_engine):
+ engine = make_engine(
+ columns=["id", "owner", "name"],
+ rows=[(1, "ADMIN", "MY_DB")],
+ )
+ assert engine._get_snowflake_database_names() == ["my_db"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_database_names_coerced_to_str(make_engine):
+ engine = make_engine(columns=["name"], rows=[(123,), (456,)])
+ assert engine._get_snowflake_database_names() == ["123", "456"]
+
+
[email protected](not HAS_SQLALCHEMY, reason="SQLAlchemy not installed")
+def test_snowflake_get_database_names_delegates(make_engine):
+ """Snowflake dialect delegates to _get_snowflake_database_names."""
+ engine = make_engine(default_database="MY_DB")
+
+ expected = ["DB_A", "DB_B"]
+ with mock.patch.object(
+ engine, "_get_snowflake_database_names", return_value=expected
+ ) as mocked:
+ result = engine._get_database_names()
+
+ mocked.assert_called_once()
+ assert result == expected