dirigent-block-sql 0.17.0__tar.gz

dirigent_block_sql-0.17.0/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 Morten Olav Hansen <morten@winterop.com>. All rights reserved.
+
+This source code and accompanying documentation are the property of
+Morten Olav Hansen. No license, express or implied, is granted to use, copy,
+modify, merge, publish, distribute, sublicense, or sell copies of this
+software or its derivatives.
+
+The source is published for reference only. Any use beyond reading
+requires written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES,
+OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+Third-party components redistributed with this software, and the licences they
+carry, are listed in THIRD_PARTY_NOTICES.md.

dirigent_block_sql-0.17.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: dirigent-block-sql
+Version: 0.17.0
+Summary: The SQL block family for dirigent: sql.query, sql.execute, and the sql connection kind.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: dirigent-common==0.17.0
+Requires-Dist: dirigent-plugin==0.17.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.52
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# dirigent-block-sql
+
+The SQL block family: `sql.query` reads rows and `sql.execute` writes them, both against the
+database a `sql` connection names.
+
+The connection kind holds the URL and its credential, and the driver is SQLAlchemy's, so any
+dialect with an async driver the worker has installed is addressable.
+
+Engines are packages. A backend that needs more than a driver implements `SqlEngine` and
+registers under the `dirigent.sql.engines.v1` entry-point group, and the family asks it what a
+valid connection to that backend is, where a database written as a relative path lands, what a
+parameter becomes, how a check reaches it, and what a session on it is.
+`dirigent-block-duckdb` is the first, and `duckdb:///warehouse.duckdb` works once it is
+installed.

dirigent_block_sql-0.17.0/README.md

@@ -0,0 +1,14 @@
+# dirigent-block-sql
+
+The SQL block family: `sql.query` reads rows and `sql.execute` writes them, both against the
+database a `sql` connection names.
+
+The connection kind holds the URL and its credential, and the driver is SQLAlchemy's, so any
+dialect with an async driver the worker has installed is addressable.
+
+Engines are packages. A backend that needs more than a driver implements `SqlEngine` and
+registers under the `dirigent.sql.engines.v1` entry-point group, and the family asks it what a
+valid connection to that backend is, where a database written as a relative path lands, what a
+parameter becomes, how a check reaches it, and what a session on it is.
+`dirigent-block-duckdb` is the first, and `duckdb:///warehouse.duckdb` works once it is
+installed.

dirigent_block_sql-0.17.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "dirigent-block-sql"
+version = "0.17.0"
+description = "The SQL block family for dirigent: sql.query, sql.execute, and the sql connection kind."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "dirigent-common==0.17.0",
+    "dirigent-plugin==0.17.0",
+    "sqlalchemy[asyncio]>=2.0.52",
+]
+
+[project.entry-points."dirigent.plugins.v1"]
+block-sql = "dirigent_block_sql:plugin"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.dirigent-common]
+workspace = true
+
+[tool.uv.sources.dirigent-plugin]
+workspace = true

dirigent_block_sql-0.17.0/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "dirigent-block-sql"
+version = "0.17.0"
+description = "The SQL block family for dirigent: sql.query, sql.execute, and the sql connection kind."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "dirigent-common==0.17.0",
+    "dirigent-plugin==0.17.0",
+    "sqlalchemy[asyncio]>=2.0.52",
+]
+
+[project.entry-points."dirigent.plugins.v1"]
+block-sql = "dirigent_block_sql:plugin"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+dirigent-common = { workspace = true }
+dirigent-plugin = { workspace = true }

dirigent_block_sql-0.17.0/src/dirigent_block_sql/__init__.py

@@ -0,0 +1,34 @@
+"""The SQL block family: reading and writing a database through one connection kind."""
+
+from dirigent_block_sql.engines import SqlAlchemyEngine, SqlEngine, SqlSession
+from dirigent_block_sql.markers import ENGINES_GROUP
+from dirigent_block_sql.sql import SqlConnectionConfig, SqlConnectionKind, SqlExecuteOperator, SqlQueryOperator
+from dirigent_plugin import Contribution, extension
+
+
+class SqlBlocks:
+    """The plugin object the host discovers under the dirigent.plugins.v1 entry-point group."""
+
+    @extension
+    def contribute(self) -> Contribution:
+        """Contribute the two SQL blocks and the connection kind that addresses a database."""
+        return Contribution(
+            operators=[SqlQueryOperator(), SqlExecuteOperator()],
+            connection_kinds=[SqlConnectionKind()],
+        )
+
+
+plugin = SqlBlocks()
+
+__all__ = [
+    "ENGINES_GROUP",
+    "SqlAlchemyEngine",
+    "SqlBlocks",
+    "SqlConnectionConfig",
+    "SqlConnectionKind",
+    "SqlEngine",
+    "SqlExecuteOperator",
+    "SqlQueryOperator",
+    "SqlSession",
+    "plugin",
+]

dirigent_block_sql-0.17.0/src/dirigent_block_sql/engines.py

@@ -0,0 +1,321 @@
+"""The engine contract the ``sql`` family drives a database through, and the registry of engines.
+
+An engine is one backend -- what a URL's scheme names -- and the decisions that differ from one
+backend to the next: what makes a connection to it valid, where a database written as a relative
+path lands, what a parameter has to become before the database sees it, how a check reaches it,
+and what a session on it is. Everything else about ``sql.query`` and ``sql.execute`` is the same
+whichever engine answers.
+
+Any dialect with an async driver is the generic path here, and a backend that needs more than a
+driver -- DuckDB, which has no async driver at all -- is a package contributing an engine under
+the ``dirigent.sql.engines.v1`` entry-point group. A block cannot reach the plugin host, so the
+family loads that group itself, once per process.
+"""
+
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Mapping, Sequence
+from contextlib import AbstractAsyncContextManager
+from functools import cache
+from typing import TYPE_CHECKING, Any, ClassVar, Final, Protocol
+
+import sqlalchemy
+import sqlalchemy.exc
+from pluginkit import PluginManager
+from sqlalchemy.engine import URL
+from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine
+from sqlalchemy.pool import NullPool
+from sqlalchemy.sql.elements import TextClause
+
+from dirigent_block_sql import markers
+from dirigent_block_sql.markers import ENGINES_GROUP
+from dirigent_block_sql.messages import (
+    CONNECT_TIMED_OUT,
+    DRIVER_NOT_INSTALLED,
+    ENGINE_PACKAGE_MISSING,
+    NO_ASYNC_DRIVER,
+    READ_ONLY_UNSUPPORTED,
+)
+from dirigent_common import HealthReport, JsonMap
+from dirigent_plugin import PROJECT_NAME, BlockFailure, ErrorClass, StepContext
+
+if TYPE_CHECKING:
+    from dirigent_block_sql.sql import SqlConnectionConfig
+
+#: How long a connection check may spend reaching the database and asking it for a one.
+CHECK_TIMEOUT_SECONDS = 30.0
+
+#: What a check answers for a database file that exists only while a run is on the worker.
+OUTSIDE_A_RUN: Final = (
+    "a database file relative to a run's work directory exists only inside a run, so there is nothing here to check"
+)
+
+#: The dialects whose sessions can be made read-only, and how each one is told.
+READ_ONLY: Final = {
+    "postgresql": "SET TRANSACTION READ ONLY",
+    "sqlite": "PRAGMA query_only = 1",
+}
+
+#: The distribution that provides each async driver a URL can name, for the install line an
+#: absent one is refused with.
+DRIVER_PACKAGE: Final = {
+    "aiosqlite": "aiosqlite",
+    "asyncpg": "asyncpg",
+    "psycopg": "psycopg[binary]",
+    "aiomysql": "aiomysql",
+    "asyncmy": "asyncmy",
+    "aioodbc": "aioodbc",
+    "aiooracle": "aiooracle",
+    "oracledb": "oracledb",
+}
+
+#: The package each backend that is an engine rather than a driver is carried by, for the
+#: install line a URL naming one is refused with when it is not installed.
+KNOWN_ENGINE_PACKAGES: Final = {"duckdb": "dirigent-block-duckdb"}
+
+
+class DuplicateEngine(Exception):
+    """Two plugins claimed the same backend."""
+
+    def __init__(self, backend: str, first: str, second: str) -> None:
+        """Name the backend and both plugins."""
+        super().__init__(
+            f"backend {backend!r} is contributed by both {first!r} and {second!r}, and a backend is what a "
+            f"connection's url dispatches on, so one of the two packages must be uninstalled."
+        )
+        self.backend = backend
+        self.plugins = (first, second)
+
+
+class SqlSession(Protocol):
+    """The connection surface both blocks drive, whichever engine opened it."""
+
+    async def execute(self, statement: TextClause, parameters: dict[str, Any] | None = None, /) -> Any:
+        """Run one statement and hand back its result, rowcount included."""
+        ...
+
+    def stream(self, statement: TextClause, parameters: dict[str, Any] | None = None, /) -> Awaitable[Any]:
+        """Run one statement and hand back a cursor read a batch at a time.
+
+        Awaited rather than declared ``async`` because SQLAlchemy's own is a context manager
+        that is also awaitable, and a step awaits it.
+        """
+        ...
+
+    def begin(self) -> AbstractAsyncContextManager[Any]:
+        """One transaction, committed when the block leaves cleanly and rolled back otherwise."""
+        ...
+
+
+class SqlEngine(ABC):
+    """One backend of the ``sql`` family: what a URL naming it means, and how a step drives it."""
+
+    backend: ClassVar[str]
+    """The backend a URL names this engine by, as ``URL.get_backend_name()`` spells it."""
+
+    @abstractmethod
+    def validate(self, settings: "SqlConnectionConfig", url: URL) -> None:
+        """Refuse a connection this engine cannot open, saying what about it is refused."""
+
+    def resolve(self, url: URL, ctx: StepContext) -> URL:
+        """The URL a step connects with, for an engine whose database may be a file of the run."""
+        return url
+
+    def bind(self, params: JsonMap, ctx: StepContext) -> dict[str, Any]:
+        """The parameters as this engine receives them."""
+        return dict(params)
+
+    @abstractmethod
+    async def check(self, settings: "SqlConnectionConfig", url: URL) -> HealthReport:
+        """Reach the database and ask it for a one, which is the smallest proof of reach and credential."""
+
+    @abstractmethod
+    def session(
+        self,
+        settings: "SqlConnectionConfig",
+        url: URL,
+        ctx: StepContext,
+        *,
+        statements: Sequence[str],
+        params: JsonMap,
+    ) -> AbstractAsyncContextManager[SqlSession]:
+        """The session a step runs its statements in, opened on entry and closed on exit.
+
+        The statements and the bound parameters are handed over whole, because what a session
+        has to be given -- a scheme's credentials, an extension -- is read off what will run in
+        it.
+        """
+
+
+class SqlAlchemyEngine(SqlEngine):
+    """Any dialect with an async driver, driven through SQLAlchemy's own asyncio layer."""
+
+    #: It answers for every backend no installed engine claims, so it is registered under none.
+    backend: ClassVar[str] = ""
+
+    def validate(self, settings: "SqlConnectionConfig", url: URL) -> None:
+        """Refuse a URL naming no async driver, and ``read_only`` on a dialect that has no mode for it."""
+        backend = url.get_backend_name()
+        if "+" not in url.drivername:
+            package = KNOWN_ENGINE_PACKAGES.get(backend)
+            if package is not None:
+                raise ValueError(ENGINE_PACKAGE_MISSING.render(backend=backend, package=package))
+            raise ValueError(NO_ASYNC_DRIVER.render(driver=repr(url.drivername), driver_name=url.drivername))
+        if settings.read_only and backend not in READ_ONLY:
+            supported = ", ".join(sorted(READ_ONLY))
+            raise ValueError(READ_ONLY_UNSUPPORTED.render(backend=backend, supported=supported))
+
+    def resolve(self, url: URL, ctx: StepContext) -> URL:
+        """A sqlite database written as a relative path is a file in the run's work directory."""
+        return under_work(url, ctx) if _is_run_relative(url) else url
+
+    async def check(self, settings: "SqlConnectionConfig", url: URL) -> HealthReport:
+        """Open a connection and run ``SELECT 1`` over the driver the URL names."""
+        if _is_run_relative(url):
+            return HealthReport(healthy=False, detail=OUTSIDE_A_RUN)
+        try:
+            engine = _engine(url)
+        except BlockFailure as error:
+            return HealthReport(healthy=False, detail=str(error))
+        try:
+            async with asyncio.timeout(CHECK_TIMEOUT_SECONDS), engine.connect() as connection:
+                await connection.execute(sqlalchemy.text("SELECT 1"))
+        except (TimeoutError, sqlalchemy.exc.SQLAlchemyError, OSError) as error:
+            return HealthReport(healthy=False, detail=reason(error))
+        finally:
+            await engine.dispose()
+        return HealthReport(healthy=True, detail=f"{url.get_backend_name()} answered")
+
+    def session(
+        self,
+        settings: "SqlConnectionConfig",
+        url: URL,
+        ctx: StepContext,
+        *,
+        statements: Sequence[str],
+        params: JsonMap,
+    ) -> AbstractAsyncContextManager[SqlSession]:
+        """One async connection, put in the mode the connection kind asked for."""
+        return _Session(settings, url)
+
+
+#: The engine a backend no installed package claims is driven through.
+GENERIC: Final = SqlAlchemyEngine()
+
+
+def under_work(url: URL, ctx: StepContext) -> URL:
+    """The same URL with its database file placed under the run's own work directory."""
+    database = ctx.work / str(url.database)
+    database.parent.mkdir(parents=True, exist_ok=True)
+    return url.set(database=str(database))
+
+
+def reason(error: Exception) -> str:
+    """The one sentence a health report gives for a database that did not answer."""
+    if isinstance(error, TimeoutError):
+        return f"no answer within {CHECK_TIMEOUT_SECONDS:.0f}s"
+    text = str(getattr(error, "orig", None) or error).strip().splitlines()
+    return text[0] if text else type(error).__name__
+
+
+def registry(
+    *,
+    group: str = ENGINES_GROUP,
+    extra: Mapping[str, object] | None = None,
+) -> dict[str, SqlEngine]:
+    """Build the registry: the engine every installed plugin contributes, keyed by backend.
+
+    ``extra`` registers plugin objects that are not installed as distributions.
+    """
+    found: dict[str, SqlEngine] = {}
+    origins: dict[str, str] = {}
+    manager = PluginManager(PROJECT_NAME)
+    manager.add_extension_points(markers)
+    manager.load_entrypoints(group)
+    for name, plugin in (extra or {}).items():
+        manager.register(plugin, name=name)
+    # The hook's return annotation is a declaration, not an enforcement: a plugin may answer
+    # with anything, and anything that is not an engine is not registered.
+    for plugin_name, contributed in manager.caller(markers.engines).collect_with_plugins():
+        for engine in contributed:
+            if not isinstance(engine, SqlEngine):  # pyright: ignore[reportUnnecessaryIsInstance]
+                continue
+            owner = origins.get(engine.backend)
+            if owner is not None:
+                raise DuplicateEngine(engine.backend, owner, plugin_name)
+            origins[engine.backend] = plugin_name
+            found[engine.backend] = engine
+    return found
+
+
+@cache
+def _installed() -> dict[str, SqlEngine]:
+    """The engines this process found, scanned once: a step must not rescan for every statement."""
+    return registry()
+
+
+def engine_for(url: URL) -> SqlEngine:
+    """The engine registered for this URL's backend, or the generic async SQLAlchemy one."""
+    return _installed().get(url.get_backend_name(), GENERIC)
+
+
+def _is_run_relative(url: URL) -> bool:
+    """Whether this is a sqlite file named by a path relative to the run's work directory."""
+    database = url.database or ""
+    if url.get_backend_name() != "sqlite":
+        return False
+    return bool(database) and not database.startswith("/")
+
+
+def _engine(url: URL) -> AsyncEngine:
+    """Build the engine one step uses, naming the package to install when the driver is absent.
+
+    ``NullPool`` because a step opens one connection and the worker process may run the next
+    step against a different database entirely; a pool would outlive what it serves.
+    """
+    try:
+        return create_async_engine(url, poolclass=NullPool)
+    except (ModuleNotFoundError, sqlalchemy.exc.NoSuchModuleError) as error:
+        driver = url.drivername.partition("+")[2]
+        package = DRIVER_PACKAGE.get(driver, driver)
+        raise BlockFailure(
+            DRIVER_NOT_INSTALLED,
+            error_class=ErrorClass.REJECTED,
+            driver=repr(driver),
+            package=repr(package),
+            shipped=", ".join(["asyncpg", "aiosqlite"]),
+        ) from error
+
+
+class _Session:
+    """One connection, opened under the connection's timeout and read-only where it says so."""
+
+    def __init__(self, settings: "SqlConnectionConfig", url: URL) -> None:
+        """Hold what opening this step's connection needs."""
+        self.settings = settings
+        self.url = url
+        self.engine = _engine(url)
+        self.connection: AsyncConnection | None = None
+
+    async def __aenter__(self) -> AsyncConnection:
+        """Open the connection and put it in the mode the connection kind asked for."""
+        try:
+            async with asyncio.timeout(self.settings.connect_timeout.total_seconds()):
+                self.connection = await self.engine.connect()
+        except TimeoutError as error:
+            await self.engine.dispose()
+            raise BlockFailure(
+                CONNECT_TIMED_OUT, error_class=ErrorClass.TRANSIENT, timeout=self.settings.connect_timeout
+            ) from error
+        except BaseException:
+            await self.engine.dispose()
+            raise
+        if self.settings.read_only:
+            await self.connection.execute(sqlalchemy.text(READ_ONLY[self.url.get_backend_name()]))
+        return self.connection
+
+    async def __aexit__(self, *_error: object) -> None:
+        """Close the connection and the engine behind it, however the step left."""
+        if self.connection is not None:
+            await self.connection.close()
+        await self.engine.dispose()

dirigent_block_sql-0.17.0/src/dirigent_block_sql/markers.py

@@ -0,0 +1,18 @@
+"""The extension point an engine of the ``sql`` family is contributed through."""
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final
+
+from dirigent_plugin import extension_point
+
+if TYPE_CHECKING:
+    from dirigent_block_sql.engines import SqlEngine
+
+#: The version is part of the group name, so an incompatible contract ships as a new group.
+ENGINES_GROUP: Final = "dirigent.sql.engines.v1"
+
+
+@extension_point
+def engines() -> "Sequence[SqlEngine]":
+    """Collect the engines a plugin adds to the ``sql`` family, once per process."""
+    raise NotImplementedError("an extension point is a declaration; call it via PluginManager.caller(...)")

dirigent_block_sql-0.17.0/src/dirigent_block_sql/messages.py

@@ -0,0 +1,65 @@
+"""Every refusal the sql family makes, catalogued under the ``sql`` prefix."""
+
+from dirigent_common import Catalogue
+
+SQL = Catalogue("sql")
+
+DRIVER_NOT_INSTALLED = SQL.define(
+    "driver_not_installed",
+    "the {driver} driver this url names is not installed on the worker; add the {package} "
+    "package to the image, or use a driver that ships with it ({shipped})",
+)
+
+CONNECT_TIMED_OUT = SQL.define("connect_timed_out", "the database did not answer within {timeout}")
+
+READ_ONLY_CONNECTION = SQL.define(
+    "read_only_connection",
+    "connection {connection} is read_only, and sql.execute writes; "
+    "read it with sql.query, or point this step at a connection that may write",
+)
+
+TOO_MANY_ROWS = SQL.define(
+    "too_many_rows",
+    "the query returned more than max_rows ({maximum}) rows; raise max_rows, or narrow the query",
+)
+
+NO_JSON_SPELLING = SQL.define("no_json_spelling", "a column of this result has no JSON spelling: {detail}")
+
+
+# What a config refuses at validation. Pydantic owns the code a validator's refusal reaches
+# the wire under, so these are rendered into the ``ValueError`` it wraps.
+
+ENGINE_PACKAGE_MISSING = SQL.define(
+    "engine_package_missing",
+    "{backend} needs the engine package: uv pip install {package}",
+)
+
+NO_ASYNC_DRIVER = SQL.define(
+    "no_async_driver",
+    "{driver} names no driver, and these blocks speak to a database over an "
+    "async one; write the driver in the url, as in "
+    "{driver_name}+asyncpg:// or {driver_name}+aiosqlite://",
+)
+
+READ_ONLY_UNSUPPORTED = SQL.define(
+    "read_only_unsupported",
+    "read_only has no meaning on {backend}: only {supported} can be told to "
+    "refuse writes for the length of a session, and a connection that cannot be "
+    "is not marked as one that is",
+)
+
+INLINE_PASSWORD = SQL.define(
+    "inline_password",
+    "this url carries a password inline, where it would sit unencrypted in a plain "
+    "field; take it out of the url and set the sealed password field instead",
+)
+
+EMPTY_STATEMENT = SQL.define("empty_statement", "statement {index} is empty")
+
+NOT_A_DATABASE_URL = SQL.define("not_a_database_url", "{url} is not a database url: {detail}")
+
+MORE_THAN_ONE_STATEMENT = SQL.define(
+    "more_than_one_statement",
+    "this is more than one statement: a ';' ends the first and there is more after it. "
+    "sql.query runs one statement, and sql.execute takes a list, one statement per entry",
+)

dirigent_block_sql-0.17.0/src/dirigent_block_sql/sql.py

@@ -0,0 +1,480 @@
+"""``sql.query`` and ``sql.execute``: read from and write to a database over a ``sql`` connection.
+
+Reading a table and writing a table are the two most common things a pipeline does, and until
+these blocks the answer was ``shell.run`` with ``psql`` -- an unsafe block, a credential on a
+command line, and a result that arrives as text somebody has to parse.
+
+Both blocks are **ordinary**. They run no command a document supplies and reach nothing but the
+database their connection names, which is a narrower grant than ``shell.run``.
+
+Nothing a document writes ever reaches the SQL text. A statement is a constant in the document
+and every value is a named bind parameter, so ``${...}`` resolves into ``params`` and a value
+that looks like SQL stays a value.
+
+The engine is whatever the connection's URL names: any dialect with an async driver is driven
+from here, and a backend needing more than a driver is an installed package contributing a
+:class:`~dirigent_block_sql.engines.SqlEngine`, which every decision that differs by backend is
+asked of.
+"""
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Sequence
+from datetime import timedelta
+from typing import Annotated, Any, ClassVar, Final
+
+import sqlalchemy
+import sqlalchemy.exc
+from pydantic import BaseModel, Field, SecretStr, model_validator
+from sqlalchemy.engine import URL, make_url
+
+from dirigent_block_sql.engines import SqlSession, engine_for
+from dirigent_block_sql.messages import (
+    EMPTY_STATEMENT,
+    INLINE_PASSWORD,
+    MORE_THAN_ONE_STATEMENT,
+    NO_JSON_SPELLING,
+    NOT_A_DATABASE_URL,
+    READ_ONLY_CONNECTION,
+    TOO_MANY_ROWS,
+)
+from dirigent_common import (
+    SQL_MEDIA_TYPE,
+    BlockModel,
+    Duration,
+    HealthReport,
+    JsonList,
+    JsonMap,
+    spelled,
+)
+from dirigent_plugin import (
+    BlockFailure,
+    ConnectionKind,
+    ConnectionRef,
+    ErrorClass,
+    Operator,
+    OperatorSpec,
+    RemoteHandle,
+    StepContext,
+)
+
+#: How many rows are read out of the cursor at a time, inline or on the way to storage.
+BATCH = 1000
+
+#: The dialects that can be given a per-statement deadline the server itself enforces.
+STATEMENT_TIMEOUT: Final = {"postgresql": "SET LOCAL statement_timeout = {milliseconds}"}
+
+#: What a driver says when the database could not be reached, rather than refusing the request.
+UNREACHABLE: Final = (
+    "connection refused",
+    "could not connect",
+    "could not translate host name",
+    "name or service not known",
+    "connection reset",
+    "server closed the connection",
+    "timeout expired",
+    "too many clients",
+    "the database system is starting up",
+    "database is locked",
+)
+
+
+class SqlConnectionConfig(BlockModel):
+    """One database, the sealed password that opens it, and whether it may be written to."""
+
+    url: str = Field(min_length=1)
+    """The database as a SQLAlchemy URL, driver included:
+    ``postgresql+asyncpg://user@host:5432/db`` or ``sqlite+aiosqlite:///data.db``.
+
+    A backend carried by an engine package writes the driver differently or not at all, and
+    that engine is what says so; a URL naming one that is not installed is refused with the
+    package to install.
+
+    A URL carrying a password inline is refused: the secret belongs in ``password``, where it
+    is encrypted at rest and redacted in every API response, and a plain field is neither.
+
+    A sqlite database written as a relative path is relative to the run's work directory,
+    which is where a database a pipeline builds for itself belongs. It is local to the worker
+    that made it, so a later step reading it must be on the same worker."""
+
+    password: SecretStr | None = None
+    """The password, sealed, merged into the URL when a connection is opened and nowhere else."""
+
+    read_only: bool = False
+    """Refuse to write through this connection.
+
+    Every session it opens is put in the dialect's own read-only mode, so a statement that
+    writes is refused by the database rather than by a check here, and ``sql.execute`` refuses
+    the connection outright. A dialect with no read-only mode is refused rather than silently
+    left writable."""
+
+    connect_timeout: Duration = timedelta(seconds=10)
+    """How long opening a connection may take before the step fails as a transient error."""
+
+    @model_validator(mode="after")
+    def _check_shape(self) -> "SqlConnectionConfig":
+        """Refuse a URL that is unparseable, carrying its own password, or one no engine opens."""
+        url = _parse(self.url)
+        if url.password is not None:
+            raise ValueError(INLINE_PASSWORD.render())
+        engine_for(url).validate(self, url)
+        return self
+
+
+class SqlConnectionKind(ConnectionKind):
+    """The connection kind the ``sql.*`` blocks resolve their database through."""
+
+    id: ClassVar[str] = "sql"
+    config_model: ClassVar[type[BaseModel]] = SqlConnectionConfig
+
+    async def check(self, config: BaseModel) -> HealthReport:
+        """Ask the URL's own engine to reach the database, which is the smallest proof of reach."""
+        settings = SqlConnectionConfig.model_validate(config.model_dump())
+        url = _with_password(settings)
+        return await engine_for(url).check(settings, url)
+
+
+class SqlQueryConfig(BlockModel):
+    """One statement, and the values bound into it."""
+
+    connection: ConnectionRef
+    """The ``sql`` connection naming the database and holding its password."""
+
+    sql: Annotated[str, Field(min_length=1, json_schema_extra={"contentMediaType": SQL_MEDIA_TYPE})]
+    """One statement, and one only. A document that needs two writes two steps, or uses
+    ``sql.execute``, which is the block that runs several as one transaction."""
+
+    params: JsonMap = Field(default_factory=dict[str, Any])
+    """Values bound by name, written ``:name`` in the statement.
+
+    This is where a ``${...}`` reference belongs. A parameter is sent to the database beside
+    the statement and never spliced into it, so a value that reads as SQL is still a value.
+    Nothing in ``sql`` is substituted, which also means a table or column name cannot come
+    from a parameter: only a value can.
+
+    An engine whose tables can be files is handed a storage URI as the file it opens, within
+    the run's own directories; every other engine is handed the value as it was written."""
+
+    max_rows: int = Field(default=1000, ge=1)
+    """How many rows may be carried inline in the step's output.
+
+    A result past this fails the step rather than being truncated: half an answer is not a
+    smaller answer, and a step acting on it would be acting on something the database never
+    said. Rows that belong in a file are handed to ``storage.write``."""
+
+    timeout: Duration = timedelta(minutes=5)
+    """How long the statement may run.
+
+    Set as the database's own statement timeout where the dialect has one, and enforced here
+    in every case, so a query that hangs ends the step rather than the deadline."""
+
+    @model_validator(mode="after")
+    def _check_shape(self) -> "SqlQueryConfig":
+        """Refuse a config whose ``sql`` is more than the one statement this block runs."""
+        _check_single(self.sql)
+        return self
+
+
+class SqlQueryOutput(BlockModel):
+    """What one query returned."""
+
+    rows: JsonList
+    """The rows as objects keyed by column name, which a later step reads or writes out."""
+
+    row_count: int
+    """How many rows the query returned."""
+
+    columns: list[str]
+    """The column names, in the order the query selected them."""
+
+    duration_ms: int
+
+
+class SqlQueryOperator(Operator[SqlQueryConfig, SqlQueryOutput]):
+    """Runs one statement against a database and reports its rows."""
+
+    spec = OperatorSpec(
+        id="sql.query",
+        summary="Run one SQL statement and return its rows.",
+        idempotent=True,
+    )
+    config_model: ClassVar[type[BaseModel]] = SqlQueryConfig
+    output_model: ClassVar[type[BaseModel]] = SqlQueryOutput
+
+    async def execute(self, config: SqlQueryConfig, ctx: StepContext) -> SqlQueryOutput | RemoteHandle:
+        """Open a session, run the statement, and hand the rows on as the step's output."""
+        settings = ctx.connection(config.connection, SqlConnectionConfig)
+        url = _resolved(settings, ctx)
+        engine = engine_for(url)
+        params = engine.bind(config.params, ctx)
+        started = time.monotonic()
+        async with engine.session(settings, url, ctx, statements=[config.sql], params=params) as session:
+            await _limit(session, settings, config.timeout)
+            # The deadline covers running the statement and reading the rows out of it, because
+            # a query that hangs hangs in either.
+            async with asyncio.timeout(config.timeout.total_seconds()):
+                result = await session.stream(sqlalchemy.text(config.sql), params)
+                columns = list(result.keys())
+                rows = await _inline(result, config.max_rows)
+        duration = round((time.monotonic() - started) * 1000)
+        ctx.log.info(
+            "query ran",
+            connection=config.connection,
+            row_count=len(rows),
+            duration_ms=duration,
+        )
+        return SqlQueryOutput(
+            rows=rows,
+            row_count=len(rows),
+            columns=columns,
+            duration_ms=duration,
+        )
+
+    def classify_error(self, error: Exception) -> ErrorClass:
+        """A database that could not be reached is transient; one that refused the statement is not."""
+        return classify(error)
+
+
+class SqlExecuteConfig(BlockModel):
+    """The statements one transaction runs, and the values bound into all of them."""
+
+    connection: ConnectionRef
+    """The ``sql`` connection naming the database and holding its password. A connection
+    marked ``read_only`` is refused: this block writes."""
+
+    statements: list[str] = Field(min_length=1)
+    """The statements, run in order inside one transaction. They all commit or none of them
+    does, so a migration, an insert and the index it needs are one step and not three."""
+
+    params: JsonMap = Field(default_factory=dict[str, Any])
+    """Values bound by name, written ``:name``, and shared by every statement.
+
+    A statement that names no parameter simply binds none of them. An engine whose tables can
+    be files is handed a storage URI as the file it opens, within the run's own directories."""
+
+    timeout: Duration = timedelta(minutes=5)
+    """How long the whole transaction may run.
+
+    Set as the database's own statement timeout where the dialect has one, and enforced here
+    in every case, so statements that hang end the step rather than the deadline."""
+
+    @model_validator(mode="after")
+    def _check_shape(self) -> "SqlExecuteConfig":
+        """Refuse a list whose entries are empty or hold more than one statement each."""
+        for index, statement in enumerate(self.statements):
+            if not statement.strip():
+                raise ValueError(EMPTY_STATEMENT.render(index=index))
+            _check_single(statement)
+        return self
+
+
+class SqlExecuteOutput(BlockModel):
+    """What the transaction changed."""
+
+    row_counts: list[int]
+    """Rows affected by each statement, in order; ``-1`` where the driver does not say."""
+
+    duration_ms: int
+
+
+class SqlExecuteOperator(Operator[SqlExecuteConfig, SqlExecuteOutput]):
+    """Runs several statements against a database as one transaction."""
+
+    spec = OperatorSpec(
+        id="sql.execute",
+        summary="Run SQL statements against a database in one transaction.",
+        idempotent=False,
+    )
+    config_model: ClassVar[type[BaseModel]] = SqlExecuteConfig
+    output_model: ClassVar[type[BaseModel]] = SqlExecuteOutput
+
+    async def execute(self, config: SqlExecuteConfig, ctx: StepContext) -> SqlExecuteOutput | RemoteHandle:
+        """Run every statement in one transaction and report what each of them touched."""
+        settings = ctx.connection(config.connection, SqlConnectionConfig)
+        if settings.read_only:
+            raise BlockFailure(
+                READ_ONLY_CONNECTION, error_class=ErrorClass.REJECTED, connection=repr(config.connection)
+            )
+        url = _resolved(settings, ctx)
+        engine = engine_for(url)
+        params = engine.bind(config.params, ctx)
+        started = time.monotonic()
+        counts: list[int] = []
+        opened = engine.session(settings, url, ctx, statements=config.statements, params=params)
+        async with opened as session, session.begin():
+            await _limit(session, settings, config.timeout)
+            # The deadline covers every statement together, because the transaction is what
+            # the step commits or loses.
+            async with asyncio.timeout(config.timeout.total_seconds()):
+                for statement in config.statements:
+                    result = await session.execute(sqlalchemy.text(statement), params)
+                    counts.append(result.rowcount)
+        duration = round((time.monotonic() - started) * 1000)
+        ctx.log.info(
+            "statements ran",
+            connection=config.connection,
+            statements=len(config.statements),
+            row_counts=list(counts),
+            duration_ms=duration,
+        )
+        return SqlExecuteOutput(row_counts=counts, duration_ms=duration)
+
+    def classify_error(self, error: Exception) -> ErrorClass:
+        """A database that could not be reached is transient; one that refused a statement is not."""
+        return classify(error)
+
+
+def _parse(url: str) -> URL:
+    """Read a SQLAlchemy URL, saying what is wrong with one that is not."""
+    try:
+        return make_url(url)
+    except sqlalchemy.exc.ArgumentError as error:
+        raise ValueError(NOT_A_DATABASE_URL.render(url=repr(url), detail=str(error))) from error
+
+
+def _with_password(settings: SqlConnectionConfig) -> URL:
+    """The URL with the sealed password merged in, which is the only place the two meet."""
+    url = _parse(settings.url)
+    if settings.password is None:
+        return url
+    return url.set(password=settings.password.get_secret_value())
+
+
+def _resolved(settings: SqlConnectionConfig, ctx: StepContext) -> URL:
+    """The URL a step connects with: the password merged in, and a file of the run made absolute."""
+    url = _with_password(settings)
+    return engine_for(url).resolve(url, ctx)
+
+
+async def _limit(session: SqlSession, settings: SqlConnectionConfig, timeout: timedelta) -> None:
+    """Ask the database to enforce the statement deadline itself, where the dialect has one."""
+    template = STATEMENT_TIMEOUT.get(_parse(settings.url).get_backend_name())
+    if template is None:
+        return
+    await session.execute(sqlalchemy.text(template.format(milliseconds=round(timeout.total_seconds() * 1000))))
+
+
+async def _inline(result: Any, max_rows: int) -> JsonList:
+    """Read the rows into the output, refusing a result the step said it would not hold."""
+    rows: JsonList = []
+    async for batch in _batches(result):
+        rows.extend(spelled_row(one) for one in batch)
+        if len(rows) > max_rows:
+            raise BlockFailure(TOO_MANY_ROWS, error_class=ErrorClass.REJECTED, maximum=max_rows)
+    return rows
+
+
+async def _batches(result: Any) -> AsyncIterator[Sequence[Any]]:
+    """Read the cursor a batch at a time, whatever the driver's own chunking is."""
+    async for partition in result.partitions(BATCH):
+        yield partition
+
+
+def spelled_row(row: Any) -> JsonMap:
+    """One row as an object keyed by column name, every value in its JSON spelling."""
+    mapping: dict[str, Any] = dict(row._mapping)
+    try:
+        return {name: spelled(value) for name, value in mapping.items()}
+    except ValueError as error:
+        raise BlockFailure(NO_JSON_SPELLING, error_class=ErrorClass.REJECTED, detail=str(error)) from error
+
+
+def _check_single(statement: str) -> None:
+    """Refuse text holding more than one statement.
+
+    A ``;`` outside a string literal, an identifier, a comment or a dollar-quoted body ends a
+    statement, so anything but whitespace and comments after one means there are two. Two
+    statements in one field would run outside ``sql.execute``'s transaction, and a document
+    that means to run two says so by listing two.
+    """
+    rest = _after_first_terminator(statement)
+    if rest is not None and _stripped(rest):
+        raise ValueError(MORE_THAN_ONE_STATEMENT.render())
+
+
+def _after_first_terminator(statement: str) -> str | None:
+    """The text following the first statement-ending ``;``, or None when there is none."""
+    index = 0
+    length = len(statement)
+    while index < length:
+        character = statement[index]
+        if character == ";":
+            return statement[index + 1 :]
+        skipped = _skip(statement, index)
+        index = skipped if skipped > index else index + 1
+    return None
+
+
+def _skip(statement: str, index: int) -> int:
+    """The index just past whatever quoted or commented run starts here, or ``index`` if none does."""
+    character = statement[index]
+    if statement.startswith("--", index):
+        end = statement.find("\n", index)
+        return _length_or(statement, end + 1 if end != -1 else -1)
+    if statement.startswith("/*", index):
+        end = statement.find("*/", index + 2)
+        return _length_or(statement, end + 2 if end != -1 else -1)
+    if character in "'\"`":
+        return _skip_quoted(statement, index, character)
+    if character == "$":
+        return _skip_dollar(statement, index)
+    return index
+
+
+def _skip_quoted(statement: str, index: int, quote: str) -> int:
+    """Past a quoted run, in which the quote character is doubled to mean itself."""
+    cursor = index + 1
+    while cursor < len(statement):
+        if statement[cursor] == quote:
+            if statement.startswith(quote * 2, cursor):
+                cursor += 2
+                continue
+            return cursor + 1
+        cursor += 1
+    return len(statement)
+
+
+def _skip_dollar(statement: str, index: int) -> int:
+    """Past a ``$tag$ ... $tag$`` body, which is how PostgreSQL writes a function containing ``;``."""
+    close = statement.find("$", index + 1)
+    if close == -1:
+        return index
+    tag = statement[index : close + 1]
+    if not tag[1:-1].replace("_", "").isalnum() and tag != "$$":
+        return index
+    end = statement.find(tag, close + 1)
+    return _length_or(statement, end + len(tag) if end != -1 else -1)
+
+
+def _length_or(statement: str, end: int) -> int:
+    """An index into the statement, or its end when the run was never closed."""
+    return len(statement) if end == -1 else end
+
+
+def _stripped(text: str) -> str:
+    """The text with whitespace and trailing comments removed, so a comment is not a statement."""
+    rest = text
+    while True:
+        rest = rest.strip()
+        if rest.startswith("--"):
+            _, _, rest = rest.partition("\n")
+            continue
+        if rest.startswith("/*"):
+            _, _, rest = rest.partition("*/")
+            continue
+        return rest
+
+
+def classify(error: Exception) -> ErrorClass:
+    """A database that could not be reached is transient; one that refused the request is not."""
+    if isinstance(error, TimeoutError | sqlalchemy.exc.TimeoutError | sqlalchemy.exc.DisconnectionError):
+        return ErrorClass.TRANSIENT
+    if isinstance(error, sqlalchemy.exc.DBAPIError):
+        if error.connection_invalidated or any(marker in str(error).lower() for marker in UNREACHABLE):
+            return ErrorClass.TRANSIENT
+        return ErrorClass.REJECTED
+    if isinstance(error, sqlalchemy.exc.SQLAlchemyError):
+        return ErrorClass.REJECTED
+    if isinstance(error, OSError):
+        return ErrorClass.TRANSIENT
+    return ErrorClass.UNKNOWN