{"record":{"id":"0ae3f520d0c5291f","repo":"pola-rs/polars","slug":"string-uri-is-invalid-here-call-read-database-ur","errorCode":null,"errorMessage":"string URI is invalid here; call `read_database_uri` instead","messagePattern":"string URI is invalid here; call `read_database_uri` instead","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/database/functions.py","lineNumber":256,"sourceCode":"    ...         query=\"SELECT * FROM test\",\n    ...         url=\"http://localhost:8000\",\n    ...     )\n    ... )  # doctest: +SKIP\n\n    \"\"\"  # noqa: W505\n    if isinstance(connection, str):\n        # check for odbc connection string\n        if re.search(r\"\\bdriver\\s*=\\s*{[^}]+?}\", connection, re.IGNORECASE):\n            _ = import_optional(\n                module_name=\"arrow_odbc\",\n                err_prefix=\"use of ODBC connection string requires the\",\n                err_suffix=\"package\",\n            )\n            connection = ODBCCursorProxy(connection)\n        elif \"://\" in connection:\n            # otherwise looks like a mistaken call to read_database_uri\n            msg = \"string URI is invalid here; call `read_database_uri` instead\"\n            raise ValueError(msg)\n        else:\n            msg = \"unable to identify string connection as valid ODBC (no driver)\"\n            raise ValueError(msg)\n\n    # adbc_driver_manager must be >= 1.7.0 to support passing Python sequences into\n    # parameterised queries (via execute_options) without PyArrow installed\n    if (\n        execute_options is not None\n        and not _PYARROW_AVAILABLE\n        and type(connection).__module__.split(\".\", 1)[0].startswith(\"adbc\")\n    ):\n        adbc_version_no_pyarrow_required = \"1.7.0\"\n        adbc_driver_manager = import_optional(\"adbc_driver_manager\")\n        adbc_str_version = getattr(adbc_driver_manager, \"__version__\", \"0.0\")\n        if not parse_version(adbc_str_version) >= parse_version(\n            adbc_version_no_pyarrow_required\n        ):\n            msg = (","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/database/functions.py#L238-L274","documentation":"Raised by read_database() when the connection argument is a string containing '://', i.e. a URI. read_database expects a live connection/cursor object; URI-based access has a dedicated function, read_database_uri, so polars redirects you instead of trying to interpret the URI as a connection.","triggerScenarios":"pl.read_database(query, 'postgresql://user:pass@host/db') — passing a URI string where a connection object is required.","commonSituations":"Confusing the two database entry points (names differ by only a suffix); porting code between them; copy-pasting a connection string from environment variables into the wrong function.","solutions":["Use pl.read_database_uri(query, uri) for string URIs (with engine='connectorx' or 'adbc')","Or keep read_database and pass a real connection object, e.g. sqlalchemy.create_engine(uri).connect()"],"exampleFix":"# before\npl.read_database(\"SELECT * FROM t\", \"postgresql://user:pw@host/db\")\n\n# after\npl.read_database_uri(\"SELECT * FROM t\", \"postgresql://user:pw@host/db\")","handlingStrategy":"validation","validationCode":"def read_any(query: str, conn_or_uri):\n    if isinstance(conn_or_uri, str) and \"://\" in conn_or_uri:\n        return pl.read_database_uri(query, conn_or_uri)\n    return pl.read_database(query, conn_or_uri)","typeGuard":"def is_connection_uri(value: object) -> bool:\n    return isinstance(value, str) and \"://\" in value","tryCatchPattern":null,"preventionTips":["Keep one helper that routes str-URIs to read_database_uri and objects to read_database","Name variables conn (object) vs uri (string) to avoid mixups","Remember ODBC driver strings (driver={...}) are the only strings read_database accepts"],"tags":["database","api-misuse","uri"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}