PostgreSQL 驱动程序¶

PostgreSQL 驱动程序提供对任何支持 PostgreSQL 线协议的数据库的访问。它封装了 libpq，即 PostgreSQL 的客户端库。该项目在整体方法上得益于 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);

您必须在 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 中定义的功能。

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)	(作为解包类型)	(作为解包类型，仅用于二进制/字符串)
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 线协议提供的原始字节。

对于支持不透明规范扩展类型的 Arrow 实现，扩展类型元数据也始终存在。这有助于区分驱动程序何时有意返回二进制列与何时作为回退返回二进制列。

警告

目前，驱动程序还会在未知列的模式字段中附加一个名为 ADBC:postgresql:typname 的元数据键，但此功能已弃用，取而代之的是不透明类型，您不应依赖此键继续存在。

软件版本¶

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

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