muscles-data-sqlalchemy 0.1.0__tar.gz

muscles_data_sqlalchemy-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: muscles-data-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy SqlResourcePort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-sqlalchemy
+
+SQLAlchemy adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns the
+SQLAlchemy-backed `SqlResourcePort` adapter.
+
+Use this package when a project wants direct SQLAlchemy sessions through the
+same data resource runtime without wiring `muscles-sql` first.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- Executable example:
+  [`example_data_sqlalchemy_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_sqlalchemy_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import SqlResourcePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_sqlalchemy import SqlAlchemySqlResourceFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(SqlAlchemySqlResourceFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+sql = runtime.require_port("sql.local", SqlResourcePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    sql.local:
+      type: sqlalchemy
+      url: sqlite:///:memory:
+      name: local_sqlite
+      pool_pre_ping: true
+      native_client: false
+```
+
+`data.resources.list` does not create the engine. The engine/session factory is
+created lazily by `session()`, `session_factory()`, explicit native access or
+`data.doctor`.
+
+Application code should use `SqlResourcePort`; direct engine/session-factory
+access is only an advanced escape hatch with `native_client: true`.
+
+See `muscular-example/example_data_sqlalchemy_1` for an executable example.

muscles_data_sqlalchemy-0.1.0/README.md

@@ -0,0 +1,68 @@
+# muscles-data-sqlalchemy
+
+SQLAlchemy adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns the
+SQLAlchemy-backed `SqlResourcePort` adapter.
+
+Use this package when a project wants direct SQLAlchemy sessions through the
+same data resource runtime without wiring `muscles-sql` first.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- Executable example:
+  [`example_data_sqlalchemy_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_sqlalchemy_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import SqlResourcePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_sqlalchemy import SqlAlchemySqlResourceFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(SqlAlchemySqlResourceFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+sql = runtime.require_port("sql.local", SqlResourcePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    sql.local:
+      type: sqlalchemy
+      url: sqlite:///:memory:
+      name: local_sqlite
+      pool_pre_ping: true
+      native_client: false
+```
+
+`data.resources.list` does not create the engine. The engine/session factory is
+created lazily by `session()`, `session_factory()`, explicit native access or
+`data.doctor`.
+
+Application code should use `SqlResourcePort`; direct engine/session-factory
+access is only an advanced escape hatch with `native_client: true`.
+
+See `muscular-example/example_data_sqlalchemy_1` for an executable example.

muscles_data_sqlalchemy-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "muscles-data-sqlalchemy"
+version = "0.1.0"
+description = "SQLAlchemy SqlResourcePort adapter for muscles-data"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Denis B.", email = "denis@butko.info" }]
+dependencies = [
+  "muscles-data>=0.1.0,<1.0.0",
+  "SQLAlchemy>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "integration: tests that require the local backend integration stack",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

muscles_data_sqlalchemy-0.1.0/setup.cfg

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

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .adapter import (
+    SqlAlchemyAdapterError,
+    SqlAlchemyClientMissingError,
+    SqlAlchemyConfigError,
+    SqlAlchemyConnectionError,
+    SqlAlchemySqlResourceAdapter,
+    SqlAlchemySqlResourceFactory,
+)
+
+
+__all__ = [
+    "SqlAlchemyAdapterError",
+    "SqlAlchemyClientMissingError",
+    "SqlAlchemyConfigError",
+    "SqlAlchemyConnectionError",
+    "SqlAlchemySqlResourceAdapter",
+    "SqlAlchemySqlResourceFactory",
+]

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy/adapter.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import importlib
+import threading
+from collections.abc import Callable
+from dataclasses import asdict
+from typing import Any, Mapping
+
+from muscles_data.config import DataResourceConfig
+from muscles_data.errors import DataError
+from muscles_data.models import DataCapability, HealthResult, InspectResult
+
+
+_ENGINE_UNSET = object()
+_SESSION_FACTORY_UNSET = object()
+_ALLOWED_OPTIONS = {
+    "url",
+    "url_env",
+    "name",
+    "native_client",
+    "echo",
+    "pool_pre_ping",
+    "pool_size",
+    "max_overflow",
+    "connect_args",
+    "future",
+}
+_ENGINE_OPTIONS = {"echo", "pool_pre_ping", "pool_size", "max_overflow", "connect_args", "future"}
+
+
+class SqlAlchemyAdapterError(DataError):
+    """Base error for direct SQLAlchemy resource adapter failures."""
+
+
+class SqlAlchemyConfigError(ValueError, SqlAlchemyAdapterError):
+    """Raised when a SQLAlchemy resource config cannot be mapped safely."""
+
+
+class SqlAlchemyClientMissingError(SqlAlchemyAdapterError):
+    """Raised when SQLAlchemy is not installed for a direct SQLAlchemy resource."""
+
+
+class SqlAlchemyConnectionError(SqlAlchemyAdapterError):
+    """Raised when a SQLAlchemy engine/session operation fails."""
+
+
+class SqlAlchemySqlResourceAdapter:
+    resource_type = "sqlalchemy"
+
+    def __init__(
+        self,
+        config: DataResourceConfig,
+        *,
+        sqlalchemy_provider: Callable[[], Any] | None = None,
+    ) -> None:
+        self.config = config
+        self._sqlalchemy_provider = sqlalchemy_provider
+        self._sqlalchemy: Any | None = None
+        self._engine: Any = _ENGINE_UNSET
+        self._session_factory: Any = _SESSION_FACTORY_UNSET
+        self._lock = threading.RLock()
+        self.closed = False
+
+    def connection_name(self) -> str:
+        return str(self.config.options.get("name", self.config.name))
+
+    def session(self):
+        try:
+            return self.session_factory()()
+        except (SqlAlchemyClientMissingError, SqlAlchemyConfigError, SqlAlchemyConnectionError):
+            raise
+        except Exception as exc:
+            raise SqlAlchemyConnectionError(self._safe_error(exc)) from exc
+
+    def session_factory(self):
+        if self._session_factory is _SESSION_FACTORY_UNSET:
+            with self._lock:
+                if self._session_factory is _SESSION_FACTORY_UNSET:
+                    self._sqlalchemy_module()
+                    try:
+                        orm = importlib.import_module("sqlalchemy.orm")
+                        self._session_factory = orm.sessionmaker(bind=self._engine_instance())
+                    except (SqlAlchemyClientMissingError, SqlAlchemyConfigError, SqlAlchemyConnectionError):
+                        raise
+                    except Exception as exc:
+                        raise SqlAlchemyConnectionError(self._safe_error(exc)) from exc
+        return self._session_factory
+
+    def inspect(self) -> Mapping[str, Any]:
+        return asdict(
+            InspectResult(
+                name=self.config.name,
+                type=self.config.type,
+                capabilities=[],
+                initialized=self._engine is not _ENGINE_UNSET,
+                status="ok",
+                options=self.config.safe_options(),
+                details={
+                    "backend": "sqlalchemy",
+                    "connection": self.connection_name(),
+                    "engine_initialized": self._engine is not _ENGINE_UNSET,
+                },
+            )
+        )
+
+    def doctor(self) -> Mapping[str, Any]:
+        try:
+            sqlalchemy = self._sqlalchemy_module()
+            with self._engine_instance().connect() as connection:
+                connection.execute(sqlalchemy.text("SELECT 1"))
+        except Exception as exc:
+            return {
+                "status": "failed",
+                "message": self._safe_error(exc),
+                "details": {"backend": "sqlalchemy", "connection": self.connection_name()},
+            }
+        return {
+            "status": "ok",
+            "message": "SQLAlchemy connection is available",
+            "details": {"backend": "sqlalchemy", "connection": self.connection_name()},
+        }
+
+    def health(self) -> HealthResult:
+        doctor = self.doctor()
+        return HealthResult(
+            status=str(doctor.get("status", "failed")),
+            message=doctor.get("message"),
+            details=dict(doctor.get("details", {}) or {}),
+        )
+
+    def close(self) -> None:
+        if self._engine is not _ENGINE_UNSET:
+            dispose = getattr(self._engine, "dispose", None)
+            if callable(dispose):
+                dispose()
+        self.closed = True
+
+    def native_client(self):
+        return {"engine": self._engine_instance(), "session_factory": self.session_factory()}
+
+    def _engine_instance(self):
+        if self._engine is _ENGINE_UNSET:
+            with self._lock:
+                if self._engine is _ENGINE_UNSET:
+                    self._engine = self._create_engine()
+        return self._engine
+
+    def _create_engine(self):
+        self._validate_options()
+        sqlalchemy = self._sqlalchemy_module()
+        options = self.config.resolved_options()
+        kwargs = _engine_options(options)
+        try:
+            return sqlalchemy.create_engine(str(options["url"]), **kwargs)
+        except Exception as exc:
+            raise SqlAlchemyConnectionError(self._safe_error(exc)) from exc
+
+    def _sqlalchemy_module(self):
+        if self._sqlalchemy is None:
+            module = self._sqlalchemy_provider() if self._sqlalchemy_provider else _default_sqlalchemy_module()
+            if module is None:
+                raise SqlAlchemyClientMissingError("Install SQLAlchemy or muscles-data-sqlalchemy to use type=sqlalchemy")
+            self._sqlalchemy = module
+        return self._sqlalchemy
+
+    def _validate_options(self) -> None:
+        unknown = sorted(set(self.config.options) - _ALLOWED_OPTIONS)
+        if unknown:
+            names = ", ".join(unknown)
+            raise SqlAlchemyConfigError(f"Unsupported SQLAlchemy resource options: {names}")
+        if not self.config.options.get("url") and not self.config.options.get("url_env"):
+            raise SqlAlchemyConfigError("SQLAlchemy resource requires url or url_env")
+        connect_args = self.config.options.get("connect_args")
+        if connect_args is not None and not isinstance(connect_args, Mapping):
+            raise SqlAlchemyConfigError("SQLAlchemy connect_args must be a mapping")
+
+    def _safe_error(self, exc: Exception) -> str:
+        message = str(exc)
+        try:
+            url = str(self.config.resolved_options().get("url", ""))
+        except Exception:
+            url = str(self.config.options.get("url", ""))
+        if url:
+            message = message.replace(url, "***")
+        safe_url = self.config.safe_options().get("url")
+        if isinstance(safe_url, str) and safe_url != url:
+            message = message.replace(safe_url, "***")
+        return message
+
+
+class SqlAlchemySqlResourceFactory:
+    resource_type = "sqlalchemy"
+
+    def __init__(self, *, sqlalchemy_provider: Callable[[], Any] | None = None) -> None:
+        self._sqlalchemy_provider = sqlalchemy_provider
+
+    def capabilities(self, config: DataResourceConfig) -> set[DataCapability]:
+        native = {DataCapability.NATIVE_CLIENT} if bool(config.options.get("native_client")) else set()
+        return {DataCapability.SQL_SESSION, DataCapability.HEALTHCHECK} | native
+
+    def create(self, config: DataResourceConfig) -> SqlAlchemySqlResourceAdapter:
+        return SqlAlchemySqlResourceAdapter(config, sqlalchemy_provider=self._sqlalchemy_provider)
+
+
+def _engine_options(options: Mapping[str, Any]) -> dict[str, Any]:
+    output = {key: options[key] for key in _ENGINE_OPTIONS if key in options}
+    output.setdefault("future", True)
+    return output
+
+
+def _default_sqlalchemy_module():
+    try:
+        return importlib.import_module("sqlalchemy")
+    except Exception as exc:
+        raise SqlAlchemyClientMissingError("Install SQLAlchemy or muscles-data-sqlalchemy to use type=sqlalchemy") from exc

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: muscles-data-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy SqlResourcePort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-sqlalchemy
+
+SQLAlchemy adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns the
+SQLAlchemy-backed `SqlResourcePort` adapter.
+
+Use this package when a project wants direct SQLAlchemy sessions through the
+same data resource runtime without wiring `muscles-sql` first.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- Executable example:
+  [`example_data_sqlalchemy_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_sqlalchemy_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import SqlResourcePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_sqlalchemy import SqlAlchemySqlResourceFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(SqlAlchemySqlResourceFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+sql = runtime.require_port("sql.local", SqlResourcePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    sql.local:
+      type: sqlalchemy
+      url: sqlite:///:memory:
+      name: local_sqlite
+      pool_pre_ping: true
+      native_client: false
+```
+
+`data.resources.list` does not create the engine. The engine/session factory is
+created lazily by `session()`, `session_factory()`, explicit native access or
+`data.doctor`.
+
+Application code should use `SqlResourcePort`; direct engine/session-factory
+access is only an advanced escape hatch with `native_client: true`.
+
+See `muscular-example/example_data_sqlalchemy_1` for an executable example.

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/muscles_data_sqlalchemy/__init__.py
+src/muscles_data_sqlalchemy/adapter.py
+src/muscles_data_sqlalchemy.egg-info/PKG-INFO
+src/muscles_data_sqlalchemy.egg-info/SOURCES.txt
+src/muscles_data_sqlalchemy.egg-info/dependency_links.txt
+src/muscles_data_sqlalchemy.egg-info/requires.txt
+src/muscles_data_sqlalchemy.egg-info/top_level.txt
+tests/test_integration.py
+tests/test_sqlalchemy_adapter.py

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy.egg-info/requires.txt

@@ -0,0 +1,5 @@
+muscles-data<1.0.0,>=0.1.0
+SQLAlchemy<3.0,>=2.0
+
+[dev]
+pytest<9.0,>=8.0

muscles_data_sqlalchemy-0.1.0/src/muscles_data_sqlalchemy.egg-info/top_level.txt

@@ -0,0 +1 @@
+muscles_data_sqlalchemy

muscles_data_sqlalchemy-0.1.0/tests/test_integration.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import pytest
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.ports import SqlResourcePort
+from muscles_data.runtime import DataRuntime
+
+from muscles_data_sqlalchemy import SqlAlchemySqlResourceFactory
+
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(not os.getenv("MUSCLES_DATA_INTEGRATION"), reason="backend integration is disabled"),
+]
+
+
+def _runtime(url: str) -> DataRuntime:
+    config = DataConfig.from_raw(
+        {
+            "data": {
+                "resources": {
+                    "sql.integration": {
+                        "type": "sqlalchemy",
+                        "url": url,
+                        "name": "integration_sql",
+                        "pool_pre_ping": True,
+                    }
+                }
+            }
+        }
+    )
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(SqlAlchemySqlResourceFactory())
+    return DataRuntime(config=config, catalog=catalog)
+
+
+def test_sqlalchemy_real_session_and_health_lifecycle():
+    from sqlalchemy import text
+
+    with TemporaryDirectory() as temporary:
+        runtime = _runtime(f"sqlite:///{Path(temporary) / 'integration.sqlite3'}")
+        try:
+            sql = runtime.require_port("sql.integration", SqlResourcePort)
+            with sql.session() as session:
+                assert session.execute(text("select 1")).scalar_one() == 1
+            assert sql.doctor()["status"] == "ok"
+            assert runtime.doctor()["status"] == "ok"
+            contracts = pytest.importorskip("muscles_data.contracts")
+            contract = getattr(contracts, "assert_sql_resource_contract", None)
+            if contract is not None:
+                contract(lambda: sql)
+        finally:
+            runtime.close()
+
+
+def test_sqlalchemy_postgresql_configuration_when_driver_is_available():
+    pytest.importorskip("psycopg")
+    url = os.getenv("SQLALCHEMY_POSTGRES_URL")
+    if not url:
+        pytest.skip("PostgreSQL integration URL is not configured")
+    from sqlalchemy import text
+
+    runtime = _runtime(url)
+    try:
+        sql = runtime.require_port("sql.integration", SqlResourcePort)
+        with sql.session() as session:
+            assert session.execute(text("select 1")).scalar_one() == 1
+        assert sql.doctor()["status"] == "ok"
+    finally:
+        runtime.close()

muscles_data_sqlalchemy-0.1.0/tests/test_sqlalchemy_adapter.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import pytest
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.config import DataConfig
+from muscles_data.models import DataCapability
+from muscles_data.ports import SqlResourcePort
+from muscles_data.runtime import DataRuntime
+
+from muscles_data_sqlalchemy import (
+    SqlAlchemyClientMissingError,
+    SqlAlchemyConnectionError,
+    SqlAlchemySqlResourceFactory,
+)
+
+
+def _config(url: str = "sqlite:///:memory:") -> dict:
+    return {
+        "data": {
+            "resources": {
+                "sql.local": {
+                    "type": "sqlalchemy",
+                    "url": url,
+                    "name": "local_sqlite",
+                    "native_client": True,
+                }
+            }
+        }
+    }
+
+
+def _runtime(factory: SqlAlchemySqlResourceFactory | None = None, url: str = "sqlite:///:memory:") -> DataRuntime:
+    catalog = DataAdapterCatalog.with_defaults()
+    catalog.register(factory or SqlAlchemySqlResourceFactory())
+    return DataRuntime(config=DataConfig.from_raw(_config(url)), catalog=catalog)
+
+
+def test_sqlalchemy_resource_port_is_external_lazy_and_exposes_sessions():
+    sqlalchemy = pytest.importorskip("sqlalchemy")
+    runtime = _runtime()
+
+    listed = runtime.list_resources()[0]
+    inspected_before = runtime.inspect_resource("sql.local")
+
+    assert listed["type"] == "sqlalchemy"
+    assert "sql_session" in listed["capabilities"]
+    assert "native_client" not in listed["capabilities"]
+    assert listed["initialized"] is False
+    assert inspected_before["initialized"] is False
+    assert inspected_before["options"]["url"] == "***"
+
+    sql = runtime.require_port("sql.local", SqlResourcePort)
+    with sql.session() as session:
+        session.execute(sqlalchemy.text("create table notes (id integer primary key, title varchar)"))
+        session.execute(sqlalchemy.text("insert into notes (title) values ('typed port')"))
+        rows = session.execute(sqlalchemy.text("select title from notes")).fetchall()
+        session.commit()
+
+    native = runtime.require_resource("sql.local", DataCapability.NATIVE_CLIENT).native_client()
+    assert [row[0] for row in rows] == ["typed port"]
+    assert {"engine", "session_factory"} <= set(native)
+    assert sql.inspect()["details"]["backend"] == "sqlalchemy"
+    assert sql.doctor()["status"] == "ok"
+    assert runtime.close()["status"] == "ok"
+
+
+def test_sqlalchemy_safe_failures_and_missing_client():
+    runtime = _runtime(url="missingdialect://user:secret@localhost/app")
+
+    assert runtime.inspect_resource("sql.local")["options"]["url"] == "***"
+    doctor = runtime.doctor()
+    assert doctor["status"] == "failed"
+    assert "secret" not in repr(doctor)
+
+    with pytest.raises(SqlAlchemyConnectionError):
+        runtime.require_port("sql.local", SqlResourcePort).session()
+
+    missing = _runtime(SqlAlchemySqlResourceFactory(sqlalchemy_provider=lambda: None))
+    with pytest.raises(SqlAlchemyClientMissingError):
+        missing.require_port("sql.local", SqlResourcePort).session()