pola-rs/polars · error · ModuleUpgradeRequiredError

pyarrow is required for adbc-driver-manager < {adbc_version_

Error message

pyarrow is required for adbc-driver-manager < {adbc_version_no_pyarrow_required} when using parameterized queries (via `execute_options`), found {adbc_str_version}.
Either upgrade `adbc-driver-manager` (suggested) or install `pyarrow`

What it means

Raised by _read_sql_adbc when parameterized queries are used (execute_options is not None), PyArrow is not installed, and adbc-driver-manager is older than the version (1.7.0) that can pass Python sequences as bind parameters without PyArrow. Without either piece, the ADBC binding path cannot serialise query parameters.

Source

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

    # adbc_driver_manager must be >= 1.7.0 to support passing Python sequences into
    # parameterised queries (via execute_options) without PyArrow installed
    adbc_version_no_pyarrow_required = "1.7.0"
    has_required_adbc_version = adbc_version >= parse_version(
        adbc_version_no_pyarrow_required
    )

    if (
        execute_options is not None
        and not _PYARROW_AVAILABLE
        and not has_required_adbc_version
    ):
        msg = (
            "pyarrow is required for adbc-driver-manager < "
            f"{adbc_version_no_pyarrow_required} when using parameterized queries (via "
            f"`execute_options`), found {adbc_str_version}.\nEither upgrade "
            "`adbc-driver-manager` (suggested) or install `pyarrow`"
        )
        raise ModuleUpgradeRequiredError(msg)

    # From adbc_driver_manager version 1.6.0 Cursor.fetch_arrow() was introduced,
    # returning an object implementing the Arrow PyCapsule interface. This should be
    # used regardless of whether PyArrow is available.
    fetch_method_name = (
        "fetch_arrow" if adbc_version >= (1, 6, 0) else "fetch_arrow_table"
    )

    from polars import DataFrame

    with _open_adbc_connection(connection_uri) as conn, conn.cursor() as cursor:
        cursor.execute(query, **(execute_options or {}))
        tbl = getattr(cursor, fetch_method_name)()
        return DataFrame(tbl, schema_overrides=schema_overrides)  # type: ignore[return-value]


def _get_adbc_driver_name_from_uri(connection_uri: str) -> str:
    driver_name = connection_uri.split(":", 1)[0].lower()

View on GitHub (pinned to df599052da)

Solutions

1. Upgrade the driver manager: pip install -U 'adbc-driver-manager>=1.7.0' (suggested by the error itself)
2. Or install pyarrow: pip install pyarrow
3. Or drop execute_options and inline/escape the literals (least preferred, loses parameterization safety)

Example fix

# before: adbc-driver-manager 1.5, no pyarrow
pl.read_database_uri(q, uri, engine="adbc", execute_options={"parameters": (40, 20)})

# after
pip install -U 'adbc-driver-manager>=1.7.0'

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

NEEDS = parse("1.7.0")
if execute_options and parse(version("adbc_driver_manager")) < NEEDS:
    try:
        import pyarrow  # noqa: F401
    except ImportError:
        raise RuntimeError("upgrade adbc-driver-manager>=1.7.0 or install pyarrow")

When it happens

Trigger: pl.read_database_uri(..., engine='adbc', execute_options={'parameters': (...)}) with adbc-driver-manager < 1.7.0 and no pyarrow in the environment.

Common situations: Minimal cloud/lambda images that deliberately exclude pyarrow to save space; adbc-driver-manager installed as a transitive dependency at an older pin; adopting parameterized queries (the safer SQL style) in an existing adbc setup.

Related errors

• pyarrow is required for adbc-driver-manager < {adbc_version_
• `read_database` queries require at least {module_name} versi
• pyarrow is required for adbc-driver-manager < 1.6.0, found {
• 'pre_execution_query' is only supported in connectorx versio
• pandas>=1.5.0 is required for `to_pandas("use_pyarrow_extens

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