PostgreSQL 驱动程序¶

适用于: C/C++、GLib/Ruby、Go、Python、R

PostgreSQL 驱动程序提供对任何支持 PostgreSQL 线路协议的数据库的访问。它封装了 libpq，PostgreSQL 的客户端库。该项目感谢 0x0L 的 pgeon 提供了整体方法。

注意

此项目与 PostgreSQL 无任何关联。

注意

PostgreSQL 驱动程序处于测试阶段。性能/优化以及对复杂类型和不同 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 以获得最佳性能构建的，而 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:posgresql:typname 的元数据键附加到未知列的模式字段，但这已弃用，取而代之的是不透明类型，并且您不应依赖此键继续存在。

软件版本¶

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

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