pola-rs/polars · error · ValueError

the 'connectorx' engine does not support use of `execute_opt

Error message

the 'connectorx' engine does not support use of `execute_options`

What it means

Raised by read_database_uri() when engine='connectorx' and execute_options is supplied. The connectorx engine takes no per-execution options; parameter binding and similar execution knobs are only supported by the adbc engine.

Source

Thrown at py-polars/src/polars/io/database/functions.py:502

    >>> df = pl.read_database_uri(
    ...     "SELECT * FROM employees WHERE hourly_rate BETWEEN ? AND ?",
    ...     "sqlite:///:memory:",
    ...     engine="adbc",
    ...     execute_options={"parameters": (40, 20)},
    ... )  # doctest: +SKIP
    """
    from polars.io.database._utils import _read_sql_adbc, _read_sql_connectorx

    if not isinstance(uri, str):
        msg = f"expected connection to be a URI string; found {qualified_type_name(uri)!r}"
        raise TypeError(msg)
    elif engine is None:
        engine = "connectorx"

    if engine == "connectorx":
        if execute_options:
            msg = "the 'connectorx' engine does not support use of `execute_options`"
            raise ValueError(msg)
        if pre_execution_query:
            issue_unstable_warning(
                "the 'pre-execution-query' parameter is considered unstable."
            )
        return _read_sql_connectorx(
            query,
            connection_uri=uri,
            partition_on=partition_on,
            partition_range=partition_range,
            partition_num=partition_num,
            protocol=protocol,
            schema_overrides=schema_overrides,
            pre_execution_query=pre_execution_query,
        )
    elif engine == "adbc":
        if not isinstance(query, str):
            msg = f"only a single SQL query string is accepted for adbc, got a {qualified_type_name(query)!r} type"
            raise ValueError(msg)

View on GitHub (pinned to df599052da)

Solutions

Remove execute_options when using connectorx, or
Switch to engine='adbc' if you need execute_options like parameter binding

Example fix

# before
pl.read_database_uri(q, uri, engine="connectorx", execute_options={"parameters": (40, 20)})

# after
pl.read_database_uri(q, uri, engine="adbc", execute_options={"parameters": (40, 20)})

Defensive patterns

Strategy: validation

Validate before calling

engine = engine or "connectorx"
if execute_options and engine == "connectorx":
    engine = "adbc"  # or drop execute_options

Prevention

Encode the rule 'parameters => adbc' in your DB helper layer
Keep engine choice explicit at every call site instead of defaulted
Remember connectorx handles multi-query/partitioning; adbc handles execute_options

When it happens

Trigger: pl.read_database_uri(query, uri, engine='connectorx', execute_options={'parameters': (...)})

Common situations: Switching engines for performance while keeping parameterized-query code; code copied from an adbc example run against the default (connectorx) engine.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/04d8f82c7ba46a67. Report an issue: GitHub.