데이터베이스
데이터베이스
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:***@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())
주의할 점은, SQLAlchemy나 DBAPI2 커넥션을 쓰는 경우 pl.read_database_uri가 pl.read_database보다 빠를 가능성이 크다는 거예요. 그런 커넥션들은 데이터를 행 단위(row-wise)로 Python에 불러온 뒤, 다시 컬럼 단위(column-wise)의 Apache Arrow 형식으로 복사해야 하거든요.
엔진
Polars는 데이터베이스 연결과 데이터 전송을 직접 관리하지 않고, *엔진(engine)*이라고 부르는 외부 라이브러리가 대신 처리합니다.
pl.read_database를 쓸 때는 커넥션 객체를 만들면서 엔진을 지정해요. pl.read_database_uri를 쓸 때는 다음 두 엔진 중 하나를 지정해 데이터베이스에서 읽을 수 있습니다.
두 엔진 모두 Apache Arrow를 네이티브로 지원해서, 데이터를 복사하지 않고 Polars DataFrame으로 직접 읽을 수 있어요.
ConnectorX
ConnectorX는 기본 엔진이며 Postgres, MySQL, SQL Server, Redshift를 포함한 수많은 데이터베이스를 지원합니다. ConnectorX는 Rust로 작성됐고 데이터를 Arrow 형식으로 저장해 Polars로 zero-copy 전송이 가능해요.
지원되는 데이터베이스 중 하나에서 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:***@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:***@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:***@server:port/database"
df = pl.DataFrame({"foo": [1, 2, 3]})
df.write_database(table_name="records", connection=uri, engine="adbc")