PostgreSQL 驱动程序¶

PostgreSQL 驱动程序提供对任何支持 PostgreSQL 通信协议的数据库的访问。它封装了 PostgreSQL 的客户端库 libpq。该项目的整体架构借鉴了 0x0L 的 pgeon 项目。

注意

本项目与 PostgreSQL 没有任何关联。

注意

该驱动程序对 Amazon Redshift 提供实验性支持。由于 Redshift 不支持以 PostgreSQL 二进制格式读取或写入 COPY，因此在连接到 Redshift 时，用于加速查询的优化功能将被禁用。功能方面可能还存在其他差异；如果遇到问题，请提交错误报告。

安装¶

C/C++

从 conda-forge 安装 libadbc-driver-postgresql

mamba install libadbc-driver-postgresql

安装 C/C++ 驱动程序，然后使用 Go 驱动程序管理器。需要 CGO。

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

Python

从 conda-forge 安装 adbc-driver-postgresql

mamba install adbc-driver-postgresql

从 PyPI 安装 adbc-driver-postgresql

pip install adbc-driver-postgresql

从 CRAN 安装 adbcpostgresql

install.packages("adbcpostgresql")

此外，该驱动程序可以通过驱动程序管理器从 C/C++、C#、GLib、Go、R、Ruby 和 Rust 使用。

用法¶

要连接到数据库，请在构建 AdbcDatabase 时提供“uri”参数。这应当是一个连接 URI。

C++

#include "arrow-adbc/adbc.h"

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

运行此程序时，必须确保 libadbc_driver_postgresql.so 位于你的 LD_LIBRARY_PATH 中，或与可执行文件位于同一目录中。这需要 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 中定义的功能。

COPY 查询执行¶

为了获得最佳性能，PostgreSQL 驱动程序使用 COPY 执行查询。然而，PostgreSQL 并非在所有查询中都支持此功能（例如 SHOW）。可以通过语句选项 adbc.postgresql.use_copy 来禁用此优化。有关示例，请参见在不使用 COPY 的情况下执行语句。

批量摄取¶

支持批量导入。Arrow 类型到 PostgreSQL 类型的映射与下表相同。

分区结果集¶

不支持分区结果集。

事务¶

支持事务。

类型支持¶

PostgreSQL 允许在运行时定义新类型，因此驱动程序必须构建一个可用类型映射表。目前此操作在启动时执行一次。

根据类型以及是读取还是写入，目前的类型支持有限。

Arrow 类型到 PostgreSQL 类型的映射¶
Arrow 类型	作为绑定参数	在批量导入中 [1]
二进制型 (binary)	BYTEA	BYTEA
bool	BOOLEAN	BOOLEAN
date32	DATE	DATE
date64	❌	❌
字典型 (dictionary)	(作为解包类型)	(作为解包类型，仅用于 binary/string)
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 类型将是 binary，内容为 PostgreSQL 通信协议提供的原始字节。

对于支持 Opaque 标准扩展类型的 Arrow 实现，扩展类型元数据也始终存在。这有助于区分驱动程序是故意返回 binary 列，还是将其作为回退处理返回。

警告

目前，驱动程序还会将名为 ADBC:postgresql:typname 的元数据键附加到未知列的模式字段中，但此方法已被弃用，建议转向使用 Opaque 类型，请勿依赖此键的持续存在。

软件版本¶

对于 Python wheel 包，内置的 PostgreSQL 客户端库版本为 16.9。对于 conda-forge 包，libpq 的版本与你 Conda 环境中的 libpq 版本一致。

PostgreSQL 驱动程序已在 PostgreSQL 11 至 16 版本上进行了测试。