feat(python): Support passing instantiated adbc/alchemy connection objects to write_database

[alexander-beedie]

Closes #16095.
Closes #16053.
Closes #15538.

Also: ref #7852.

---

So, The Great Database Write Rewrite™ is still pending, but this PR closes a number of outstanding Issues and enables various opt-in speedups to ensure that we can take better advantage of the underlying engines that we currently call in to (sqlalchemy/pandas and adbc).

ℹ️ This is a non-breaking change; all existing usage is unaffected.

Updates

• Can now supply an instantiated SQLAlchemy or ADBC connection directly; no longer limited to passing just the URI.
• This allows such connections to be established with specific optimisations, such as fast_executemany for pyodbc mssql connections, and other per-connection configuration parameters.
• Adds a new engine_options parameter that gets passed down to the chosen engine's underlying insert method (eg: pandas' to_sql if using SQLAlchemy, or adbc_ingest if using ADBC).

Examples

Establish a pyodbc connection using "fast_executemany=True" and insert using that:

from sqlalchemy import create_engine
import polars as pl

pyodbc_uri = (
    "mssql+pyodbc://user:pass@server:1433/test?"
    "driver=ODBC+Driver+18+for+SQL+Server"
)
conn = create_engine(pyodbc_uri, fast_executemany=True)

df.write_database(
    table_name="target_table",
    connection=conn,
)

Use a regular URI connection and pass "method='multi'" down to the to_sql insert method:

df.write_database(
    connection="hive://user:pass@server:port/database",
    table_name="target_table",
    engine="sqlalchemy",
    engine_options={"method": "multi"},
)

[ritchie46]

So, The Great Database Write Rewrite™ is still pending

I want your magic on this one so bad! ^^

Closes #16095.
Closes #16053.
Closes #15538.
Also: ref #7852.

Quite some birds in one stone. 👏

[ma-dentalcorp]

@alexander-beedie Thank you for the updates. To confirm, these updates are not yet available, right?
I upgraded my polars to latest version 0.20.25 but can't seem to use these features yet.

[alexander-beedie]

@alexander-beedie Thank you for the updates. To confirm, these updates are not yet available, right?

Correct - coming in 0.20.26 (soon) ;)

[MrAlexBailey]

Do you need a documentation update for this? Happy to make a PR if so.

[alexander-beedie]

Do you need a documentation update for this? Happy to make a PR if so.

@MrAlexBailey An update to the User Guide docs would be very welcome! (The function docstring itself has some examples/explanation, but a guide entry with more detail would be great 😎)