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_database() when an ADBC connection object is used with execute_options (parameterized query), PyArrow is not installed, and adbc-driver-manager is below 1.7.0. Passing Python sequences as bind parameters through ADBC without PyArrow requires driver-manager >= 1.7.0; older stacks need PyArrow to serialise parameters.

Source

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

    # parameterised queries (via execute_options) without PyArrow installed
    if (
        execute_options is not None
        and not _PYARROW_AVAILABLE
        and type(connection).__module__.split(".", 1)[0].startswith("adbc")
    ):
        adbc_version_no_pyarrow_required = "1.7.0"
        adbc_driver_manager = import_optional("adbc_driver_manager")
        adbc_str_version = getattr(adbc_driver_manager, "__version__", "0.0")
        if not parse_version(adbc_str_version) >= parse_version(
            adbc_version_no_pyarrow_required
        ):
            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)

    # return frame from arbitrary connections using the executor abstraction
    with ConnectionExecutor(connection) as cx:
        return cx.execute(
            query=query,
            options=execute_options,
        ).to_polars(
            batch_size=batch_size,
            iter_batches=iter_batches,
            schema_overrides=schema_overrides,
            infer_schema_length=infer_schema_length,
        )


@overload
def read_database_uri(
    query: str,
    uri: str,

View on GitHub (pinned to df599052da)

Solutions

Upgrade adbc-driver-manager to >= 1.7.0: pip install -U 'adbc-driver-manager>=1.7.0'
Or install pyarrow: pip install pyarrow
Or remove execute_options and bind values another way (e.g. SQLAlchemy connection with proper escaping)

Example fix

# before: adbc-driver-manager 1.6, no pyarrow
pl.read_database(q, adbc_conn, execute_options={"parameters": (40, 20)})

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

Defensive patterns

Strategy: validation

Validate before calling

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

if execute_options and not _PYARROW_AVAILABLE:
    if parse(version("adbc_driver_manager")) < parse("1.7.0"):
        raise RuntimeError("upgrade adbc-driver-manager>=1.7.0 or install pyarrow")

Type guard

def is_adbc_connection(conn: object) -> bool:
    return type(conn).__module__.split(".", 1)[0].startswith("adbc")

Prevention

Gate execute_options on a startup version/dependency check for adbc connections
Pin adbc-driver-manager>=1.7.0 in pyarrow-free deployments
Route parameterized reads through SQLAlchemy when the adbc stack cannot be upgraded

When it happens

Trigger: pl.read_database(query, adbc_connection, execute_options={'parameters': (...)}) in an environment with adbc-driver-manager < 1.7.0 and no pyarrow.

Common situations: Reusing an adbc connection object (e.g. from adbc_driver_sqlite.dbapi.connect) with read_database; pyarrow-free deployments; driver-manager pinned below 1.7.0 while adopting parameter binding.

Related errors

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