pola-rs/polars · error · TypeError

expected connection to be a URI string; found {qualified_typ

Error message

expected connection to be a URI string; found {qualified_type_name(uri)!r}

What it means

Raised by read_database_uri() when the uri argument is not a str. The URI-based reader is string-only; passing an engine, connection object, cursor, or None is a type error, reported with the qualified type name of what was actually received.

Source

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

    ...     "sqlite:///:memory:",
    ...     engine="adbc",
    ...     execute_options={"parameters": (30,)},
    ... )  # doctest: +SKIP

    Or pass multiple parameters:

    >>> 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,

View on GitHub (pinned to df599052da)

Solutions

Pass the URI as a string: pl.read_database_uri(query, 'postgresql://host/db')
If you hold a connection object, call pl.read_database(query, connection) instead
Check argument order — uri is the second positional parameter

Example fix

# before
pl.read_database_uri(q, sqlalchemy_engine)

# after
pl.read_database_uri(q, "postgresql://user:pw@host/db")
# or, with an engine object
pl.read_database(q, sqlalchemy_engine.connect())

Defensive patterns

Strategy: type-guard

Validate before calling

if not isinstance(uri, str):
    uri = str(uri)  # or raise early with your own message

Type guard

def is_uri_string(value: object) -> TypeGuard[str]:
    return isinstance(value, str)

Prevention

Annotate helper params as uri: str vs connection: object to catch this statically
Never pass an Engine where a URI string is documented
Use keyword arguments (query=, uri=) to avoid positional mixups

When it happens

Trigger: pl.read_database_uri(query, engine_obj) or passing a SQLAlchemy Engine/Connection where the URI string belongs; argument order swaps (passing execute_options or engine in the uri slot).

Common situations: Mixed codebases using both read_database and read_database_uri; refactoring that changed what a variable holds; positional-argument mixups.

Related errors

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