Skip to content

数据库

从数据库读取

Polars 可以使用 pl.read_database_uri 和 pl.read_database 函数从数据库中读取数据。

read_database_uri 和 read_database 的区别

如果你想使用一个称为uri的连接字符串来指定数据库连接，请使用pl.read_database_uri。例如，以下代码片段展示了一个查询，用于从Postgres数据库中的foo表读取所有列，其中我们使用uri进行连接：

read_database_uri 

import polars as pl

uri = "postgresql://username:password@server:port/database"
query = "SELECT * FROM foo"

pl.read_database_uri(query=query, uri=uri)

另一方面，如果你想通过使用像SQLAlchemy这样的库创建的连接引擎进行连接，请使用pl.read_database。

read_database 

import polars as pl
from sqlalchemy import create_engine

conn = create_engine(f"sqlite:///test.db")

query = "SELECT * FROM foo"

pl.read_database(query=query, connection=conn.connect())

请注意，如果您使用的是SQLAlchemy或DBAPI2连接，pl.read_database_uri可能比pl.read_database更快，因为这些连接可能会将数据逐行加载到Python中，然后再将数据复制到列式的Apache Arrow格式中。

引擎

Polars 本身不管理从数据库的连接和数据传输。相反，外部库（称为 引擎）负责处理这些任务。

当使用pl.read_database时，您在创建连接对象时指定引擎。当使用pl.read_database_uri时，您可以指定两种引擎之一来从数据库读取：

两个引擎都原生支持Apache Arrow，因此可以直接将数据读取到Polars的DataFrame中，而无需复制数据。

ConnectorX

ConnectorX 是默认引擎，并且支持多种数据库，包括 Postgres、Mysql、SQL Server 和 Redshift。ConnectorX 是用 Rust 编写的，并以 Arrow 格式存储数据，以实现与 Polars 的零拷贝传输。

要从支持的数据库中读取数据，使用ConnectorX时，你需要在安装Polars时激活额外的依赖项ConnectorX，或者手动安装它。

$ pip install connectorx

ADBC

ADBC（Arrow数据库连接）是由Apache Arrow项目支持的引擎。ADBC旨在成为连接数据库的API标准，并在多种语言中实现该标准的库。

ADBC 目前还处于早期阶段，因此对不同数据库的支持有限。目前，ADBC 的驱动程序仅适用于 Postgres、SQLite 和 Snowflake。要安装 ADBC，您需要为您的数据库安装相应的驱动程序。例如，要安装 SQLite 的驱动程序，您可以运行：

$ pip install adbc-driver-sqlite

由于ADBC不是默认引擎，您必须将引擎指定为pl.read_database_uri的参数。

read_database_uri 

uri = "postgresql://username:password@server:port/database"
query = "SELECT * FROM foo"

pl.read_database_uri(query=query, uri=uri, engine="adbc")

写入数据库

我们可以使用pl.write_database函数将数据写入数据库。

引擎

与上述从数据库读取一样，Polars 使用一个引擎来写入数据库。目前支持的引擎有：

SQLAlchemy

使用默认的引擎SQLAlchemy，你可以写入任何SQLAlchemy支持的数据库。要使用这个引擎，你需要安装SQLAlchemy和Pandas。

$ pip install SQLAlchemy pandas

在这个例子中，我们将DataFrame写入数据库中名为records的表中

write_database 

uri = "postgresql://username:password@server:port/database"
df = pl.DataFrame({"foo": [1, 2, 3]})

df.write_database(table_name="records",  connection=uri)

在SQLAlchemy方法中，Polars将DataFrame转换为由PyArrow支持的Pandas DataFrame，然后使用SQLAlchemy方法在Pandas DataFrame上写入数据库。

ADBC

ADBC 也可以用于写入数据库。支持使用 ADBC 进行写入的数据库与支持读取的数据库相同。如上所示，您需要为您的数据库安装适当的 ADBC 驱动程序。

write_database 

uri = "postgresql://username:password@server:port/database"
df = pl.DataFrame({"foo": [1, 2, 3]})

df.write_database(table_name="records", connection=uri, engine="adbc")