pola-rs/polars · error · ValueError

'pre_execution_query' is only supported in connectorx versio

Error message

'pre_execution_query' is only supported in connectorx version 0.4.2 or later

What it means

Raised by _read_sql_connectorx when pre_execution_query is supplied but the installed connectorx is older than 0.4.2. The pre_execution_query feature (running setup statements before the main query) only exists in connectorx >= 0.4.2; older versions would silently ignore it, so polars raises instead.

Source

Thrown at py-polars/src/polars/io/database/_utils.py:52

def _read_sql_connectorx(
    query: str | list[str],
    connection_uri: str,
    partition_on: str | None = None,
    partition_range: tuple[int, int] | None = None,
    partition_num: int | None = None,
    protocol: str | None = None,
    schema_overrides: SchemaDict | None = None,
    pre_execution_query: str | list[str] | None = None,
) -> DataFrame:
    from polars import DataFrame

    cx = import_optional("connectorx")

    if parse_version(cx.__version__) < (0, 4, 2):
        if pre_execution_query:
            msg = "'pre_execution_query' is only supported in connectorx version 0.4.2 or later"
            raise ValueError(msg)
        return_type = "arrow2"
        pre_execution_args = {}
    else:
        return_type = "arrow"
        pre_execution_args = {"pre_execution_query": pre_execution_query}

    try:
        tbl = cx.read_sql(
            conn=connection_uri,
            query=query,
            return_type=return_type,
            partition_on=partition_on,
            partition_range=partition_range,
            partition_num=partition_num,
            protocol=protocol,
            **pre_execution_args,
        )
    except BaseException as err:

View on GitHub (pinned to df599052da)

Solutions

1. Upgrade: pip install -U 'connectorx>=0.4.2'
2. If upgrading is impossible, drop pre_execution_query and run the setup statement separately over an adbc/SQLAlchemy connection before reading with connectorx
3. Pin connectorx>=0.4.2 in requirements once you rely on the parameter

Example fix

# before (connectorx 0.3.x)
pl.read_database_uri(q, uri, engine="connectorx", pre_execution_query="SET TIME ZONE 'UTC'")

# after
pip install -U 'connectorx>=0.4.2'

from importlib.metadata import version
from packaging.version import parse

if parse(version("connectorx")) < (0, 4, 2):
    raise RuntimeError("connectorx>=0.4.2 required for pre_execution_query")

When it happens

Trigger: pl.read_database_uri(..., engine='connectorx', pre_execution_query='SET ...') with connectorx < 0.4.2 installed; pinned/older connectorx in a locked environment combined with code using the newer parameter.

Common situations: Corporate environments with pinned connectorx versions; CI images built before connectorx 0.4.2; notebooks where connectorx was installed long ago and the new parameter was copied from current docs.

Related errors

• `read_database` queries require at least {module_name} versi
• pyarrow is required for adbc-driver-manager < {adbc_version_
• pyarrow is required for adbc-driver-manager < {adbc_version_
• pyarrow is required for adbc-driver-manager < 1.6.0, found {
• the 'connectorx' engine does not support use of `execute_opt

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