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://localhost: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 中定义的功能，但并非所有情况都已完全实现（尤其是在绑定参数和预处理语句方面）。

绑定参数和预处理语句¶

PostgreSQL 驱动程序仅支持执行不返回结果集的带参数的预处理语句（基本上，带有参数的 INSERT）。返回结果集的查询使用预处理语句很困难，因为该驱动程序是围绕使用 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 canonical extension type 的 Arrow 实现，扩展类型元数据也始终存在。这有助于区分驱动程序是有意返回 binary 列还是返回 binary 列作为回退。

警告

目前，驱动程序还会将名为 ADBC:posgresql:typname 的元数据键附加到未知列的模式字段，但这已被弃用，转而支持 Opaque 类型，您不应依赖此键继续存在。

软件版本¶

对于 Python wheels，附带的 PostgreSQL 客户端库版本为 15.2。对于 conda-forge 包，libpq 的版本与您 Conda 环境中的 libpq 版本相同。

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