polars.DataFrame.write_database#

DataFrame.write_database(
table_name: str,
connection: ConnectionOrCursor | str,
*,
if_table_exists: DbWriteMode = 'fail',
engine: DbWriteEngine | None = None,
engine_options: dict[str, Any] | None = None,
) → int[source]#

将Polars DataFrame中的数据写入数据库。

在版本0.20.26中添加：除了URI字符串外，还支持实例化的连接对象，以及一个新的engine_options参数。

Parameters:
table_name

目标SQL数据库中要创建或追加的表的模式限定名称。如果您的表名包含特殊字符，则应使用引号括起来。

connection

一个针对目标数据库的现有SQLAlchemy或ADBC连接，或者将用于实例化此类连接的URI字符串，例如：

  • “postgresql://user:pass@server:port/database”

  • “sqlite:////path/to/database.db”

if_table_exists{‘append’, ‘replace’, ‘fail’}

插入模式：

  • 'replace' 将创建一个新的数据库表，覆盖现有的表。

  • 'append' 将会附加到现有的表中。

  • 如果表已经存在，‘fail’将会失败。

engine{‘sqlalchemy’, ‘adbc’}

选择用于写入帧数据的引擎；仅在提供URI字符串时需要（如果未设置，则默认为‘sqlalchemy’）

engine_options

传递给与由选项engine指定的引擎相关联的插入方法的附加选项。

  • 将engine设置为“sqlalchemy”目前使用Pandas的to_sql方法进行插入（尽管这最终将被原生解决方案所取代）。

  • 将 engine 设置为 "adbc" 时，使用 ADBC 光标的 adbc_ingest 方法进行插入。

Returns:
int

受影响的行数，如果驱动程序提供此信息。 否则，返回-1。

示例

使用PostgreSQL URI和ADBC引擎插入到临时表中：

>>> df.write_database(
...     table_name="target_table",
...     connection="postgresql://user:pass@server:port/database",
...     engine="adbc",
...     engine_options={"temporary": True},
... )

使用pyodbc SQLAlchemy 连接到 SQL Server 并插入到表中，该连接实例化时使用了“fast_executemany=True”以提高性能：

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