PostgreSQL 驅動程式¶

適用於： C/C++、GLib/Ruby、Go、Python、R

PostgreSQL 驅動程式提供對任何支援 PostgreSQL 線路格式的資料庫的存取。它封裝了 libpq，PostgreSQL 的用戶端函式庫。此專案的整體方法歸功於 0x0L 的 pgeon。

注意

此專案與 PostgreSQL 沒有任何關聯。

注意

PostgreSQL 驅動程式目前為 Beta 版。效能/最佳化以及對複雜類型和不同 ADBC 功能的支援仍在進行中。

注意

AWS Redshift 支援非常舊版本的 PostgreSQL 線路協定，並且在 ADBC PostgreSQL 驅動程式中具有基本層級的支援。由於 Redshift 不支援以 PostgreSQL 二進制格式讀取或寫入 COPY，因此連接到 Redshift 資料庫時，不會啟用加速非 Redshift 查詢的最佳化。此功能為實驗性功能。

安裝¶

C/C++

對於 conda-forge 使用者

mamba install libadbc-driver-postgresql

安裝 C/C++ 套件並使用 Go 驅動程式管理器。需要 CGO。

go get github.com/apache/arrow-adbc/go/adbc/drivermgr

Python

# For conda-forge
mamba install adbc-driver-postgresql

# For pip
pip install adbc_driver_postgresql

install.packages("adbcpostgresql")

用法¶

若要連接到資料庫，請在建構 AdbcDatabase 時提供 “uri” 參數。這應該是連線 URI。

C++

#include "arrow-adbc/adbc.h"

// Ignoring error handling
struct AdbcDatabase database;
AdbcDatabaseNew(&database, nullptr);
AdbcDatabaseSetOption(&database, "uri", "postgresql://127.0.0.1:5433", nullptr);
AdbcDatabaseInit(&database, nullptr);

您必須在您的 LD_LIBRARY_PATH 中，或在您執行此執行檔的相同目錄中，擁有 libadbc_driver_postgresql.so。這需要 CGO 並載入 C++ ADBC postgresql 驅動程式。

import (
   "context"

   "github.com/apache/arrow-adbc/go/adbc"
   "github.com/apache/arrow-adbc/go/adbc/drivermgr"
)

func main() {
   var drv drivermgr.Driver
   db, err := drv.NewDatabase(map[string]string{
      "driver": "adbc_driver_postgresql",
      adbc.OptionKeyURI: "postgresql://user:pass@localhost:5433/postgres",
   })
   if err != nil {
      // handle error
   }
   defer db.Close()

   cnxn, err := db.Open(context.Background())
   if err != nil {
      // handle error
   }
   defer cnxn.Close()
}

Python

import adbc_driver_postgresql.dbapi

uri = "postgresql://user:pass@localhost:5433/postgres"
with adbc_driver_postgresql.dbapi.connect(uri) as conn:
    pass

如需更多範例，請參閱 PostgreSQL 食譜。

library(adbcdrivermanager)

# Use the driver manager to connect to a database
uri <- Sys.getenv("ADBC_POSTGRESQL_TEST_URI")
db <- adbc_database_init(adbcpostgresql::adbcpostgresql(), uri = uri)
con <- adbc_connection_init(db)

支援的功能¶

PostgreSQL 驅動程式主要支援 ADBC API 規範 1.0.0 中定義的功能，但並非所有情況都完全實作（尤其是關於綁定參數和預備語句）。

綁定參數與預備語句¶

PostgreSQL 驅動程式僅支援執行不傳回結果集的帶參數預備語句（基本上是帶參數的 INSERT）。傳回結果集的查詢對於預備語句來說很困難，因為驅動程式是圍繞使用 COPY 以獲得最佳效能而建構的，而這在此上下文中不受支援。

大量資料載入¶

支援大量資料載入。從 Arrow 類型到 PostgreSQL 類型的映射與下方相同。

分區結果集¶

不支援分區結果集。

交易¶

支援交易。

類型支援¶

PostgreSQL 允許在運行時定義新類型，因此驅動程式必須建立可用類型的映射。目前在啟動時執行一次。

類型支援目前受到類型以及是讀取還是寫入的限制。

Arrow 類型到 PostgreSQL 類型的映射¶
Arrow 類型	作為綁定參數	在大量資料載入中 [1]
binary	BYTEA	BYTEA
bool	BOOLEAN	BOOLEAN
date32	DATE	DATE
date64	❌	❌
dictionary	（作為解封類型）	（作為解封類型，僅適用於二進制/字串）
duration	INTERVAL	INTERVAL
float32	REAL	REAL
float64	DOUBLE PRECISION	DOUBLE PRECISION
int8	SMALLINT	SMALLINT
int16	SMALLINT	SMALLINT
int32	INTEGER	INTEGER
int64	BIGINT	BIGINT
large_binary	❌	❌
large_string	TEXT	TEXT
month_day_nano_interval	INTERVAL	INTERVAL
string	TEXT	TEXT
timestamp	TIMESTAMP [3]	TIMESTAMP/TIMESTAMP WITH TIMEZONE

PostgreSQL 類型到 Arrow 類型的映射¶
PostgreSQL 類型	在結果集中
ARRAY	list
BIGINT	int64
BINARY	binary
BOOLEAN	bool
CHAR	utf8
DATE	date32
DOUBLE PRECISION	float64
INTEGER	int32
INTERVAL	month_day_nano_interval
NUMERIC	utf8 [2]
REAL	float32
SMALLINT	int16
TEXT	utf8
TIME	time64
TIMESTAMP WITH TIME ZONE	timestamp[unit, UTC]
TIMESTAMP WITHOUT TIME ZONE	timestamp[unit]
VARCHAR	utf8

未知類型¶

沒有直接 Arrow 等效類型的類型仍然可以由驅動程式傳回。在這種情況下，Arrow 類型將為二進制，內容將是 PostgreSQL 線路協定提供的原始字節。

對於支援 Opaque canonical extension type 的 Arrow 實作，擴充類型元數據也始終存在。這有助於區分驅動程式何時有意傳回二進制列，以及何時將二進制列作為後備傳回。

警告

目前，驅動程式還將名為 ADBC:posgresql:typname 的元數據鍵附加到未知列的架構欄位，但這已被棄用，轉而支持 Opaque 類型，您不應依賴此鍵繼續存在。

軟體版本¶

對於 Python wheel，PostgreSQL 用戶端函式庫的出貨版本為 15.2。對於 conda-forge 套件，libpq 的版本與您 Conda 環境中的 libpq 版本相同。

PostgreSQL 驅動程式已針對 PostgreSQL 版本 11 到 16 進行測試。