pola-rs/polars · error · ModuleUpgradeRequiredError

`read_database` queries require at least {module_name} versi

Error message

`read_database` queries require at least {module_name} version {minimum_version}

What it means

Before using an Arrow-based fetch path, ConnectionExecutor._check_module_version imports the driver module, reads its __version__/version, and compares against the minimum polars requires for that path (ARROW_DRIVER_REGISTRY entries, e.g. aiosqlite, adbc_driver_manager, turbodbc). If the installed version is older, it raises ModuleUpgradeRequiredError (a ModuleNotFoundError subclass), after first trying any lower-requirement fallback driver properties in the registry. The with suppress(AttributeError) means a module with no version attribute passes silently - only a parseable, too-old version raises.

Source

Thrown at py-polars/src/polars/io/database/_executor.py:151

        if self.can_close_cursor and hasattr(self.cursor, "close"):
            from sqlalchemy.ext.asyncio.exc import AsyncContextNotStarted

            with suppress(AsyncContextNotStarted):
                await self.cursor.close()

    @staticmethod
    def _check_module_version(module_name: str, minimum_version: str) -> None:
        """Check the module version against a minimum required version."""
        mod = __import__(module_name)
        with suppress(AttributeError):
            module_version: tuple[int, ...] | None = None
            for version_attr in ("__version__", "version"):
                if isinstance(ver := getattr(mod, version_attr, None), str):
                    module_version = parse_version(ver)
                    break
            if module_version and module_version < parse_version(minimum_version):
                msg = f"`read_database` queries require at least {module_name} version {minimum_version}"
                raise ModuleUpgradeRequiredError(msg)

    def _fetch_arrow(
        self,
        driver_properties: ArrowDriverProperties,
        *,
        batch_size: int | None,
        iter_batches: bool,
    ) -> Iterable[pa.RecordBatch]:
        """Yield Arrow data as a generator of one or more RecordBatches or Tables."""
        fetch_batches = driver_properties["fetch_batches"]
        if not iter_batches or fetch_batches is None:
            fetch_method = driver_properties["fetch_all"]
            res = getattr(self.result, fetch_method)()

            if isinstance(res, Iterable):
                yield from res
            else:
                yield res

View on GitHub (pinned to df599052da)

Solutions

  1. Upgrade the named module to at least the stated minimum: pip install -U 'adbc-driver-manager>=<minimum_version>' (use the module_name/minimum_version from the message)
  2. If you cannot upgrade, choose a different connection style (e.g. plain DBAPI cursor instead of ADBC, or read_database_uri with connectorx)
  3. Check for dependency constraints forcing the old version: pip check / pip install --upgrade --force-reinstall <module>

Example fix

# before: ModuleUpgradeRequiredError: `read_database` queries require at least adbc_driver_manager version 0.9.0
pl.read_database('SELECT * FROM t', connection=adbc_conn)

# after
# pip install -U 'adbc-driver-manager>=0.9.0'
pl.read_database('SELECT * FROM t', connection=adbc_conn)
Defensive patterns

Strategy: validation

Validate before calling

from importlib import metadata

def ensure_version(module_name: str, minimum: str) -> None:
    installed = metadata.version(module_name)
    if tuple(map(int, installed.split('.')[:3])) < tuple(
        map(int, minimum.split('.')[:3])
    ):
        raise RuntimeError(
            f'{module_name} {installed} too old for polars; need >= {minimum}'
        )

ensure_version('adbc_driver_manager', '0.9.0')
df = pl.read_database(query, connection=adbc_conn)

Try / catch

from polars.exceptions import ModuleUpgradeRequiredError

try:
    df = pl.read_database(query, connection=conn)
except ModuleUpgradeRequiredError as err:
    # message names module + minimum version; surface to deployment tooling
    raise RuntimeError(f'dependency upgrade required: {err}') from err

Prevention

When it happens

Trigger: pl.read_database(...) with an ADBC/turbodbc/aiosqlite-backed connection whose package is below the registry minimum, e.g. adbc-driver-manager 0.5 when the path requires >=0.9; docker images or lambda layers pinning old driver wheels; pip resolving an old version due to a conflicting constraint.

Common situations: Locked dependency files (requirements.txt, poetry.lock) holding drivers back; CI image caching an old wheel; upgrading polars without upgrading the database driver stack.

Related errors

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