データベース
データベースから読み込む
Polars は pl.read_database_uri および pl.read_database 関数を使ってデータベースから読み込むことができます。
read_database_uri と read_database の違い
接続文字列（URI）を使ってデータベース接続を指定したい場合は pl.read_database_uri を使います。以下のスニペットは、Postgres データベースの foo テーブルのすべての列を読み込む例で、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 を使います。
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())
pl.read_database_uri は、SQLAlchemy や DBAPI2 接続を使っている場合、 pl.read_database よりも高速です。これは、これらの接続ではデータがまずPythonの行単位で読み込まれ、その後列単位のApache Arrowフォーマットにコピーされるためです。
エンジン
Polars は自身でデータベースからの接続やデータ転送を管理しません。代わりに、外部ライブラリ（「 エンジン 」と呼ばれる）がこれを処理します。
pl.read_database を使用する際は、接続オブジェクトを作成するときにエンジンを指定します。pl.read_database_uri を使用する際は、2つのエンジンのいずれかを指定してデータベースから読み取ることができます:
両方のエンジンは Apache Arrow のネイティブサポートを持っているため、データをコピーすることなく Polars の DataFrame に直接読み込むことができます。
ConnectorX
ConnectorX はデフォルトのエンジンで、Postgres、Mysql、SQL Server、Redshift など多数のデータベースをサポートしています。ConnectorX は Rust で書かれており、Polars への zero-copy を可能にするために Arrow 形式でデータを保存します。
ConnectorX を使ってサポートされているデータベースから読み取るには、Polars をインストールする際に追加の依存関係 ConnectorX を有効にするか、手動で以下のようにインストールする必要があります:
$ pip install connectorx
ADBC
ADBC（Arrow Database Connectivity）は、Apache Arrow プロジェクトでサポートされているエンジンです。ADBC は、データベースに接続するための API 標準と、この標準を実装したさまざまな言語のライブラリを目指しています。
ADBC はまだ初期段階なので、さまざまなデータベースへの対応は限られています。現時点では、ADBC のドライバーは Postgres、SQLite、Snowflake でのみ利用可能です。ADBC をインストールするには、お使いのデータベース用のドライバーをインストールする必要があります。例えば、SQLite 用のドライバーをインストールするには、以下のように実行します:
$ pip install adbc-driver-sqlite
ADBC がデフォルトのエンジンではないため、pl.read_database_uri の引数でエンジンを指定する必要があります。
uri = "postgresql://username:password@server:port/database"
query = "SELECT * FROM foo"
pl.read_database_uri(query=query, uri=uri, engine="adbc")
データベースへの書き込み
Polars を使ってデータベースに書き込むには、pl.write_database 関数を使います。
エンジン
上記のデータベースからの読み込みと同様に、Polars はデータベースへの書き込みにも エンジン を使います。現在サポートされているエンジンは以下の通りです:
- SQLAlchemy
- Arrow Database Connectivity (ADBC)
SQLAlchemy
デフォルトの SQLAlchemy エンジンを使えば、SQLAlchemy がサポートするあらゆるデータベースに書き込むことができます。このエンジンを使うには、SQLAlchemy と Pandas をインストールする必要があります。
$ pip install SQLAlchemy pandas
この例では、DataFrame を records というテーブルにデータベースに書き込みます。
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 に変換し、その後 Pandas DataFrame の SQLAlchemy メソッドを使ってデータベースに書き込みます。
ADBC
ADBC を使ってデータベースに書き込むこともできます。書き込みは、ADBC で読み取りがサポートされているデータベースと同じものでサポートされています。上述のように、お使いのデータベース用の適切な ADBC ドライバをインストールする必要があります。
uri = "postgresql://username:password@server:port/database"
df = pl.DataFrame({"foo": [1, 2, 3]})
df.write_database(table_name="records", connection=uri, engine="adbc")