thunderduck-sqlalchemy 0.1.0__py3-none-any.whl

thunderduck_sqlalchemy/dialect.py

@@ -0,0 +1,242 @@
+"""The SQLAlchemy dialect.
+
+## Connection URL
+
+    thunderduck://:<tdk_token>@api.thunderduck.io/
+    thunderduck://:<tdk_token>@console-api.thunderduck.svc.cluster.local:8000/?ssl=false
+
+The token is the URL *password* (or `?token=`). It is never interpolated into
+a URL that could be logged. `?ssl=false` exists for in-cluster use, where
+talking to the console-api Service directly avoids a round trip through the
+public tunnel. `?poll_ms=` and `?timeout_ms=` mirror the JDBC driver's
+parameter names.
+
+## Reflection without SQL
+
+`get_schema_names` and friends read console-api's `/catalog/schema` tree
+rather than issuing `information_schema` queries -- issuing SQL here would
+start a Kubernetes Job per reflection call. The tree is fetched once per
+DBAPI connection and memoised on it.
+
+`/catalog/tables` would give richer metadata (row counts, nullability) but it
+is a cache that stays empty until a metadata refresh has run, so reflection
+would silently return nothing on a fresh deployment. `/catalog/schema` is
+live, and it is what the JDBC driver uses.
+
+## Why `do_ping` is a lie
+
+`DefaultDialect.do_ping` issues `SELECT 1`. Here that submits a query, starts
+a Kubernetes Job and waits seconds for it -- on every pooled connection
+checkout. A thunderduck connection holds no server-side state, so it cannot
+go stale: reporting healthy without a round trip is both cheaper and more
+accurate. Users should also pass `poolclass=NullPool` (see README).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy.engine import default
+from sqlalchemy.sql import compiler
+
+from . import dbapi as _dbapi
+from . import exceptions as exc
+from .catalog import flatten, split_schema
+from .types import sqlalchemy_type
+
+#: Attribute name used to memoise the flattened catalog on a DBAPI connection.
+_CATALOG_CACHE_ATTR = "_thunderduck_catalog_cache"
+
+
+class ThunderduckIdentifierPreparer(compiler.IdentifierPreparer):
+    """Quotes a composite schema segment-by-segment.
+
+    thunderduck schemas are dotted paths (`lego.public`), because SQLAlchemy
+    only models two name levels while thunderduck has up to three. Quoting the
+    whole thing would emit `"lego.public"` -- a single identifier containing a
+    dot, which resolves to nothing. Splitting first emits
+    `"lego"."public"`, which is what DuckDB (and console-api's sqlglot
+    rewriter) expects.
+    """
+
+    def quote_schema(self, schema: str, force: Any = None) -> str:
+        segments = split_schema(schema)
+        return ".".join(self.quote_identifier(segment) for segment in segments)
+
+    def _requires_quotes(self, value: str) -> bool:
+        """Quote every identifier, not just the ones SQLAlchemy thinks need it.
+
+        `quote_schema` above always quotes its segments, but the stock
+        `format_table` quotes the table name only *conditionally* -- so a plain
+        lowercase table came out as `"lego"."public".lego_sets`, mixing the two
+        styles. Forcing quotes everywhere makes the output uniform.
+
+        Scope: this is a preparer-wide hook, so it force-quotes every identifier
+        SQLAlchemy routes through `quote()` -- columns, labels, aliases, indexes
+        and constraints, not only schema and table names. Bind parameters are
+        unaffected; they never pass through `quote()`.
+
+        That breadth is safe because **DuckDB identifiers are case-insensitive
+        even when quoted** -- verified against duckdb: for a table created as
+        `MyTable`, all of `mytable`, `"mytable"` and `"MYTABLE"` resolve to it.
+        Unlike Postgres, quoting in DuckDB therefore changes only the rendered
+        SQL, never resolution. It also means reserved words and mixed-case names
+        need no special handling.
+
+        Server-side resolution is likewise unaffected: console-api's rewriter
+        matches on sqlglot's `table.catalog`/`.db`/`.name`, which return
+        unquoted text either way.
+        """
+        return True
+
+
+class ThunderduckDialect(default.DefaultDialect):
+    name = "thunderduck"
+    driver = "rest"
+
+    preparer = ThunderduckIdentifierPreparer
+
+    # Every statement is an HTTP round trip plus a Kubernetes Job, so there is
+    # nothing to gain from caching compiled forms, and `NullType` columns make
+    # cache keys unreliable.
+    supports_statement_cache = False
+
+    supports_native_boolean = True
+    supports_native_decimal = True
+    supports_sane_rowcount = False
+    supports_sane_multi_rowcount = False
+    postfetch_lastrowid = False
+    supports_statement_hints = False
+    default_paramstyle = "pyformat"
+    # DuckDB folds unquoted identifiers to lower case and is case-insensitive.
+    requires_name_normalize = False
+    max_identifier_length = 255
+
+    @classmethod
+    def import_dbapi(cls) -> Any:
+        return _dbapi
+
+    # SQLAlchemy 1.4 compatibility: it looks for `dbapi`, 2.0 for `import_dbapi`.
+    @classmethod
+    def dbapi(cls) -> Any:
+        return _dbapi
+
+    def create_connect_args(self, url: Any) -> tuple[list, dict]:
+        query = dict(url.query or {})
+        token = url.password or query.pop("token", None)
+        if not token:
+            raise exc.InterfaceError(
+                "no API token in the connection URL -- use "
+                "thunderduck://:<tdk_token>@host/ or ?token=<tdk_token>"
+            )
+        kwargs: dict[str, Any] = {
+            "host": url.host,
+            "token": token,
+            "use_ssl": str(query.pop("ssl", "true")).lower() not in ("false", "0", "no"),
+        }
+        if url.port:
+            kwargs["port"] = int(url.port)
+        poll_ms = query.pop("poll_ms", None)
+        if poll_ms is not None:
+            kwargs["poll_interval"] = int(poll_ms) / 1000.0
+        timeout_ms = query.pop("timeout_ms", None)
+        if timeout_ms is not None:
+            kwargs["timeout"] = int(timeout_ms) / 1000.0
+        arraysize = query.pop("arraysize", None)
+        if arraysize is not None:
+            kwargs["arraysize"] = int(arraysize)
+        return [], kwargs
+
+    def do_rollback(self, dbapi_connection: Any) -> None:
+        """No transactions to roll back (read-only)."""
+
+    def do_commit(self, dbapi_connection: Any) -> None:
+        """No transactions to commit (read-only)."""
+
+    def do_ping(self, dbapi_connection: Any) -> bool:
+        """Always healthy. See the module docstring for why this issues no SQL."""
+        return True
+
+    # ---- reflection ----
+
+    def _tables(self, connection: Any) -> list:
+        """The flattened catalog for this connection, fetched at most once."""
+        raw = getattr(connection, "connection", connection)
+        raw = getattr(raw, "dbapi_connection", raw)
+        cached = getattr(raw, _CATALOG_CACHE_ATTR, None)
+        if cached is None:
+            cached = flatten(raw.client.catalog_schema())
+            setattr(raw, _CATALOG_CACHE_ATTR, cached)
+        return cached
+
+    def get_schema_names(self, connection: Any, **kw: Any) -> list[str]:
+        return sorted({ref.schema for ref in self._tables(connection)})
+
+    def get_table_names(self, connection: Any, schema: str | None = None, **kw: Any) -> list[str]:
+        return [
+            ref.table
+            for ref in self._tables(connection)
+            if ref.schema == schema and ref.kind != "view"
+        ]
+
+    def get_view_names(self, connection: Any, schema: str | None = None, **kw: Any) -> list[str]:
+        return [
+            ref.table
+            for ref in self._tables(connection)
+            if ref.schema == schema and ref.kind == "view"
+        ]
+
+    def get_columns(
+        self, connection: Any, table_name: str, schema: str | None = None, **kw: Any
+    ) -> list[dict]:
+        ref = self._find(connection, table_name, schema)
+        if ref is None:
+            return []
+        return [
+            {
+                "name": column["name"],
+                "type": sqlalchemy_type(column["type"]),
+                # /catalog/schema carries no nullability, so report the
+                # permissive default rather than inventing a constraint.
+                "nullable": True,
+                "default": None,
+                "autoincrement": False,
+            }
+            for column in ref.columns
+        ]
+
+    def has_table(
+        self, connection: Any, table_name: str, schema: str | None = None, **kw: Any
+    ) -> bool:
+        return self._find(connection, table_name, schema) is not None
+
+    def get_pk_constraint(
+        self, connection: Any, table_name: str, schema: str | None = None, **kw: Any
+    ) -> dict:
+        return {"constrained_columns": [], "name": None}
+
+    def get_foreign_keys(
+        self, connection: Any, table_name: str, schema: str | None = None, **kw: Any
+    ) -> list:
+        return []
+
+    def get_indexes(
+        self, connection: Any, table_name: str, schema: str | None = None, **kw: Any
+    ) -> list:
+        return []
+
+    def get_table_comment(
+        self, connection: Any, table_name: str, schema: str | None = None, **kw: Any
+    ) -> dict:
+        return {"text": None}
+
+    def _find(self, connection: Any, table_name: str, schema: str | None):
+        for ref in self._tables(connection):
+            if ref.table == table_name and (schema is None or ref.schema == schema):
+                return ref
+        return None
+
+
+#: SQLAlchemy resolves `thunderduck://` and `thunderduck+rest://` here via the
+#: entry points declared in pyproject.toml.
+dialect = ThunderduckDialect

thunderduck_sqlalchemy/exceptions.py

@@ -0,0 +1,48 @@
+"""PEP 249 exception hierarchy.
+
+Defined here rather than in `dbapi.py` so every module (client, types,
+dialect) can raise the right class without importing the DBAPI layer, which
+would be a circular import.
+"""
+
+
+class Error(Exception):
+    """Base class for every error this driver raises."""
+
+
+class InterfaceError(Error):
+    """A problem with the driver or the connection itself, not the database.
+
+    Used for bad connection URLs, missing tokens and auth failures.
+    """
+
+
+class DatabaseError(Error):
+    """A problem reported by thunderduck about the request."""
+
+
+class DataError(DatabaseError):
+    """A value could not be represented in SQL (e.g. NaN, a NUL byte)."""
+
+
+class OperationalError(DatabaseError):
+    """A run-time failure outside the caller's control.
+
+    Cancelled queries, poll timeouts and expired result sets.
+    """
+
+
+class IntegrityError(DatabaseError):
+    """Relational integrity was violated. Not raised today (read-only)."""
+
+
+class InternalError(DatabaseError):
+    """The driver reached a state that should be impossible."""
+
+
+class ProgrammingError(DatabaseError):
+    """The caller did something wrong: bad SQL, or an unbindable parameter."""
+
+
+class NotSupportedError(DatabaseError):
+    """A DBAPI feature thunderduck does not have (transactions, DML)."""

thunderduck_sqlalchemy/superset_spec.py

@@ -0,0 +1,124 @@
+"""Superset DB engine spec for thunderduck.
+
+Registered through the `superset.db_engine_specs` entry point in
+pyproject.toml, so simply pip-installing this package into a Superset image is
+enough -- no Superset configuration required.
+
+## Why it subclasses DuckDB's spec
+
+thunderduck executes DuckDB SQL. Superset's `DuckDBEngineSpec` already
+encodes the right time-grain expressions (`DATE_TRUNC` forms), LIMIT handling
+and column-type conversion for that SQL, so inheriting is both less code and
+more correct than re-deriving them.
+
+## Query cancellation
+
+The Java JDBC driver's `Statement.cancel()` is a no-op, so BI tools cannot
+stop a running thunderduck query through it. Here the cursor knows its
+execution uuid, and console-api exposes `POST /executions/{id}/cancel`, so
+Superset's stop button really does kill the Kubernetes Job.
+
+Superset is deliberately NOT a dependency of this package -- it supplies
+itself at runtime. This module therefore imports `superset` at module level
+and is only ever imported by Superset resolving its own entry point. It must
+never wrap that import in a try/except: a silently degraded engine spec would
+give confusing behaviour instead of a clear failure.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from superset.db_engine_specs.base import BaseEngineSpec
+from superset.db_engine_specs.duckdb import DuckDBEngineSpec
+
+
+class ThunderduckEngineSpec(DuckDBEngineSpec):
+    engine = "thunderduck"
+    engine_name = "Thunderduck"
+    default_driver = "rest"
+
+    # No `engine_aliases`. Superset matches a spec on SQLAlchemy's
+    # `url.get_backend_name()`, which is `"thunderduck"` for BOTH
+    # `thunderduck://` and `thunderduck+rest://` (verified) -- the dotted
+    # `thunderduck.rest` form exists only as an entry-point KEY in
+    # pyproject.toml, which is a different namespace and never appears in a URL.
+    # An alias for it would therefore be dead config, so `engine` alone covers
+    # both driver spellings.
+
+    # Read-only service: no file uploads, no CTAS/CVAS.
+    supports_file_upload = False
+
+    # Ordinary SELECT capabilities, stated explicitly rather than inherited so
+    # a change in a future Superset default is visible here.
+    allows_alias_in_select = True
+    allows_subqueries = True
+
+    sqlalchemy_uri_placeholder = "thunderduck://:{api_token}@api.thunderduck.io/"
+
+    @staticmethod
+    def get_extra_params(database: Any, source: Any = None) -> dict[str, Any]:
+        """Skip DuckDB's `connect_args["config"]` injection.
+
+        `DuckDBEngineSpec.get_extra_params` appends a user-agent by injecting
+        `engine_params.connect_args.config`, which is a DuckDB *file* setting.
+        Our `connect()` has an explicit keyword-only signature and rejects an
+        unknown `config` kwarg with TypeError -- so inheriting this makes it
+        impossible to add a thunderduck database in Superset AT ALL. Reproduced
+        live in a 6.1.0 container: both Test Connection and database creation
+        fail. Delegating to BaseEngineSpec keeps the useful behaviour and drops
+        the DuckDB-specific part.
+        """
+        return BaseEngineSpec.get_extra_params(database)
+
+    @classmethod
+    def fetch_data(cls, cursor: Any, limit: int | None = None) -> list[Any]:
+        """Skip DuckDB's cursor.description assignment.
+
+        `DuckDBEngineSpec.fetch_data` works around duckdb-engine's issue #1322
+        (cursor.description becomes None after fetchall) by capturing and
+        reassigning it: `cursor.description = description`. Our Cursor.description
+        is a read-only property, so that raises AttributeError *after the query
+        has already run as a Kubernetes Job* -- the customer is charged and gets
+        a 500 error. Delegating to BaseEngineSpec skips the DuckDB workaround
+        and works correctly here.
+
+        This exemplifies the inheritance rule: we want DuckDB SQL behaviour
+        (time expressions, type conversion, LIMIT handling), not duckdb-engine's
+        Python driver workarounds. Override driver-specific hacks; inherit SQL.
+        """
+        return super(DuckDBEngineSpec, cls).fetch_data(cursor, limit)
+
+    # NOTE: `has_implicit_cancel` is deliberately NOT overridden -- it must stay
+    # False (BaseEngineSpec's default, which DuckDBEngineSpec also keeps).
+    #
+    # Returning True makes `superset/sql/execution/executor.py` return success
+    # from the stop-query path *immediately*, without ever calling
+    # `cancel_query` -- so the UI would report a query stopped while its
+    # Kubernetes Job kept running and kept costing money. The flag means "the
+    # live cursor cancels implicitly", which is not us: our cancel is an
+    # explicit REST call.
+    #
+    # Honest status of stop-button support: it does NOT work yet, and the reason
+    # is structural rather than a missing flag. Superset only records a cancel
+    # id when `has_query_id_before_execute` is False, and it does so *after*
+    # `execute()` returns; our `execute()` blocks until the query has finished,
+    # so by then there is nothing left to cancel. Making the stop button work
+    # needs a genuinely async execute path (submit, return, poll in
+    # `handle_cursor`) -- a real follow-up, not a tweak. The two hooks below are
+    # correct and ready for that day; cancellation already works today for
+    # Python callers via `cursor.cancel()` (verified live against a running
+    # query, which reached terminal status `cancelled`).
+
+    @classmethod
+    def get_cancel_query_id(cls, cursor: Any, query: Any) -> str | None:
+        """thunderduck's own execution uuid identifies the run to cancel."""
+        return getattr(cursor, "execution_id", None)
+
+    @classmethod
+    def cancel_query(cls, cursor: Any, query: Any, cancel_query_id: str) -> bool:
+        try:
+            cursor.cancel()
+        except Exception:  # noqa: BLE001 - Superset expects a bool, not a raise
+            return False
+        return True

thunderduck_sqlalchemy/types.py

@@ -0,0 +1,232 @@
+"""DuckDB type names -> SQLAlchemy types, and Python values -> SQL literals.
+
+## Two directions, two failure policies
+
+Reading (`sqlalchemy_type`) is a *display* concern: an unrecognised type name
+degrades to `NullType` so an exotic column never breaks a whole query.
+
+Writing (`render_literal`) is a *security* boundary. console-api's
+`POST /queries` accepts raw SQL only -- there is no server-side parameter
+bind -- so this module renders literals into the statement. An unrecognised
+Python type therefore raises: a silent `str()` fallback is precisely how a
+wrong-type bug or an injected string reaches generated SQL.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import math
+import re
+from decimal import Decimal
+from typing import Any
+
+from sqlalchemy import types as sqltypes
+
+from . import exceptions as exc
+
+# `Uuid` arrived in SQLAlchemy 2.0. This package supports 1.4 as well (Superset
+# 6.1.0 pins sqlalchemy<2), so resolve it dynamically rather than importing it:
+# on 1.4 a UUID column reflects as String, which is usable, instead of the
+# module failing to import at all.
+_UUID_TYPE: Any = getattr(sqltypes, "Uuid", sqltypes.String)
+
+# NOTE: `/catalog/schema` reports the SOURCE system's type names, not DuckDB's.
+# A PostgreSQL-backed catalog yields `character varying`, `double precision`,
+# `jsonb` and friends -- verified against the live deployment, where a table's
+# columns came back as `integer`, `character varying`, `character`. So this map
+# has to cover both vocabularies; a miss is not cosmetic, because a column that
+# degrades to NullType loses its filters and groupings in a BI tool.
+_SIMPLE_TYPES: dict[str, Any] = {
+    "BOOLEAN": sqltypes.Boolean,
+    "BOOL": sqltypes.Boolean,
+    # --- PostgreSQL spellings ---
+    "CHARACTER VARYING": sqltypes.String,
+    "CHARACTER": sqltypes.String,
+    "BPCHAR": sqltypes.String,
+    "DOUBLE PRECISION": sqltypes.Float,
+    "JSONB": sqltypes.JSON,
+    "SMALLSERIAL": sqltypes.SmallInteger,
+    "SERIAL": sqltypes.Integer,
+    "BIGSERIAL": sqltypes.BigInteger,
+    "OID": sqltypes.Integer,
+    "MONEY": sqltypes.Numeric,
+    "INET": sqltypes.String,
+    "CIDR": sqltypes.String,
+    "MACADDR": sqltypes.String,
+    "XML": sqltypes.String,
+    "BIT": sqltypes.String,
+    "BIT VARYING": sqltypes.String,
+    "TINYINT": sqltypes.SmallInteger,
+    "SMALLINT": sqltypes.SmallInteger,
+    "INTEGER": sqltypes.Integer,
+    "INT": sqltypes.Integer,
+    "BIGINT": sqltypes.BigInteger,
+    "HUGEINT": sqltypes.BigInteger,
+    "UBIGINT": sqltypes.BigInteger,
+    "UINTEGER": sqltypes.Integer,
+    "USMALLINT": sqltypes.SmallInteger,
+    "UTINYINT": sqltypes.SmallInteger,
+    "FLOAT": sqltypes.Float,
+    "REAL": sqltypes.Float,
+    "DOUBLE": sqltypes.Float,
+    "VARCHAR": sqltypes.String,
+    "TEXT": sqltypes.String,
+    "STRING": sqltypes.String,
+    "DATE": sqltypes.Date,
+    "TIME": sqltypes.Time,
+    "BLOB": sqltypes.LargeBinary,
+    "BYTEA": sqltypes.LargeBinary,
+    "UUID": _UUID_TYPE,
+    "JSON": sqltypes.JSON,
+    "INTERVAL": sqltypes.Interval,
+}
+
+_DECIMAL_RE = re.compile(r"^(?:DECIMAL|NUMERIC)\s*\(\s*(\d+)\s*,\s*(\d+)\s*\)$")
+
+
+def sqlalchemy_type(duckdb_type: str) -> Any:
+    """Map one `column_types` entry onto a SQLAlchemy type instance."""
+    name = (duckdb_type or "").strip().upper()
+
+    if name.endswith("[]"):
+        return sqltypes.ARRAY(sqlalchemy_type(name[:-2]))
+
+    if name.startswith("TIMESTAMP"):
+        # TIMESTAMP, TIMESTAMP WITH TIME ZONE, TIMESTAMPTZ, TIMESTAMP_NS ...
+        timezone = "WITH TIME ZONE" in name or name.endswith("TZ")
+        return sqltypes.DateTime(timezone=timezone)
+
+    # Must come AFTER the TIMESTAMP branch -- "TIMESTAMP..." also starts with
+    # "TIME". Covers PostgreSQL's `time without time zone` / `time with time
+    # zone` as well as a bare `TIME`.
+    if name.startswith("TIME"):
+        return sqltypes.Time(timezone="WITH TIME ZONE" in name)
+
+    decimal_match = _DECIMAL_RE.match(name)
+    if decimal_match:
+        precision, scale = decimal_match.groups()
+        return sqltypes.Numeric(precision=int(precision), scale=int(scale))
+    if name in ("DECIMAL", "NUMERIC"):
+        return sqltypes.Numeric()
+
+    simple = _SIMPLE_TYPES.get(name)
+    if simple is not None:
+        return simple()
+
+    # A bare `ARRAY` with no element type -- PostgreSQL reports this for array
+    # columns. Keep it an ARRAY so a consumer still knows the shape, with an
+    # unknown item type rather than losing the column entirely.
+    if name == "ARRAY":
+        return sqltypes.ARRAY(sqltypes.NullType())
+
+    # VARCHAR(255) and friends: strip the parameters and retry once.
+    base = name.split("(", 1)[0].strip()
+    simple = _SIMPLE_TYPES.get(base)
+    if simple is not None:
+        return simple()
+
+    return sqltypes.NullType()
+
+
+def render_literal(value: Any) -> str:
+    """Render one Python value as a DuckDB SQL literal.
+
+    Strict by design: anything not explicitly handled raises.
+    """
+    if value is None:
+        return "NULL"
+    # bool before int -- bool is a subclass of int in Python.
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise exc.DataError(f"cannot render non-finite float {value!r} as SQL")
+        return repr(value)
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise exc.DataError(f"cannot render non-finite decimal {value!r} as SQL")
+        return str(value)
+    if isinstance(value, str):
+        return _quote_string(value)
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return f"unhex('{bytes(value).hex()}')::BLOB"
+    if isinstance(value, dt.datetime):
+        return f"'{value.isoformat(sep=' ')}'::TIMESTAMP"
+    if isinstance(value, dt.date):
+        return f"'{value.isoformat()}'::DATE"
+    if isinstance(value, dt.time):
+        return f"'{value.isoformat()}'::TIME"
+    if isinstance(value, (list, tuple, set, frozenset)):
+        items = ", ".join(render_literal(v) for v in value)
+        return f"[{items}]"
+    raise exc.ProgrammingError(
+        f"cannot bind a value of type {type(value).__name__} -- "
+        "thunderduck renders parameters client-side and only supports "
+        "None, bool, int, float, Decimal, str, bytes, date/time/datetime and sequences"
+    )
+
+
+def _quote_string(value: str) -> str:
+    if "\x00" in value:
+        raise exc.DataError("cannot bind a string containing a NUL byte")
+    # DuckDB does not process backslash escapes in standard single-quoted
+    # strings, so doubling the quote character is the whole escape.
+    return "'" + value.replace("'", "''") + "'"
+
+
+def render_sql(sql: str, params: Any) -> str:
+    """Substitute `pyformat` parameters into `sql`.
+
+    With no params the statement is returned untouched -- important, because
+    literal `%` signs are common in SQL (`like '%x%'`) and must not be treated
+    as placeholders.
+    """
+    if params is None or (hasattr(params, "__len__") and len(params) == 0 and not sql_needs(sql)):
+        return sql
+    if isinstance(params, dict):
+        try:
+            return sql % {k: render_literal(v) for k, v in params.items()}
+        except KeyError as err:
+            raise exc.ProgrammingError(f"missing bind parameter {err.args[0]!r}") from None
+        except (TypeError, ValueError) as err:
+            raise exc.ProgrammingError(_placeholder_hint(err)) from None
+    if isinstance(params, (list, tuple)):
+        rendered = tuple(render_literal(v) for v in params)
+        try:
+            return sql % rendered
+        except (TypeError, ValueError) as err:
+            raise exc.ProgrammingError(_placeholder_hint(err, len(rendered))) from None
+    raise exc.ProgrammingError(
+        f"parameters must be a mapping or a sequence, got {type(params).__name__}"
+    )
+
+
+def sql_needs(sql: str) -> bool:
+    """True if the statement contains a pyformat placeholder."""
+    return "%(" in sql or "%s" in sql
+
+
+def _placeholder_hint(err: Exception, supplied: int | None = None) -> str:
+    """Turn Python's opaque format error into actionable advice.
+
+    Python does NOT distinguish the two ways this fails: both "too few
+    parameters supplied" and "the statement contains an unescaped literal
+    percent sign" surface as
+    `TypeError: not enough arguments for format string` (verified on 3.10-3.13
+    -- an earlier version of this code wrongly assumed ValueError and reported
+    every failure as a count mismatch). Since we cannot tell them apart, the
+    message names both causes rather than guessing.
+
+    `paramstyle` is `pyformat`, so -- exactly as with psycopg2 -- a literal
+    percent sign must be written `%%` when parameters are supplied. SQLAlchemy
+    does this automatically when it compiles; hand-written raw SQL does not.
+    """
+    counted = f" {supplied} parameter(s) were supplied." if supplied is not None else ""
+    return (
+        f"could not bind parameters ({err}).{counted} Either the number of "
+        "placeholders does not match the parameters, or the statement contains "
+        "a literal percent sign that must be escaped as '%%' "
+        "(e.g. LIKE '%%abc%%') -- thunderduck uses the 'pyformat' paramstyle"
+    )