pola-rs/polars · error · ValueError

write_database `if_table_exists` must be one of {allowed}, g

Error message

write_database `if_table_exists` must be one of {allowed}, got {if_table_exists!r}

What it means

Error "write_database `if_table_exists` must be one of {allowed}, got {if_table_exists!r}" thrown in pola-rs/polars.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:4472

        ...     "mssql+pyodbc://user:pass@server:1433/test?"
        ...     "driver=ODBC+Driver+18+for+SQL+Server"
        ... )
        >>> engine = create_engine(pyodbc_uri, fast_executemany=True)  # doctest: +SKIP
        >>> df.write_database(
        ...     table_name="target_table",
        ...     connection=engine,
        ... )  # doctest: +SKIP

        Returns
        -------
        int
            The number of rows affected, if the driver provides this information.
            Otherwise, returns -1.
        """
        if if_table_exists not in (valid_write_modes := get_args(DbWriteMode)):
            allowed = ", ".join(repr(m) for m in valid_write_modes)
            msg = f"write_database `if_table_exists` must be one of {{{allowed}}}, got {if_table_exists!r}"
            raise ValueError(msg)

        connection_module_root = type(connection).__module__.split(".", 1)[0]

        if engine is None:
            if isinstance(connection, str) or connection_module_root == "sqlalchemy":
                engine = "sqlalchemy"
            elif connection_module_root.startswith("adbc"):
                engine = "adbc"

        def unpack_table_name(name: str) -> tuple[str | None, str | None, str]:
            """Unpack optionally qualified table name to catalog/schema/table tuple."""
            from csv import reader as delimited_read

            components: list[str | None] = next(delimited_read([name], delimiter="."))  # type: ignore[arg-type]
            if len(components) > 3:
                msg = f"`table_name` appears to be invalid: '{name}'"
                raise ValueError(msg)
            catalog, schema, tbl = ([None] * (3 - len(components))) + components

View on GitHub (pinned to df599052da)

When it happens

Trigger: Thrown at py-polars/src/polars/dataframe/frame.py:4472 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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