目录

libpq

C 编程语言 API

libpq 是 PostgreSQL 的官方C应用程序编程接口，它提供了一套库函数，使客户端应用程序能够与 PostgreSQL 服务器通信。

其他应用程序接口，如 C++、Perl、Python、Tcl 和 ECPG，以及像 psql 这样的客户端应用程序，都基于 libpq，并继承了它的一些行为和环境配置。

历史说明：libpq 中的“pq”源自 PostQUEL（参见 PostgreSQL 简史）。

用法

编译时特性可用性

从 PostgreSQL 14 开始，libpq 提供了一系列 LIBPQ_HAS_XXX 宏，可用于测试特定特性的存在。请参见 src/interfaces/libpq/libpq-fe.h。

变更历史

不完整，仍在进行中！

  • PostgreSQL 19
    • 添加了连接参数 servicefile（提交 092f3c63）
  • PostgreSQL 18
    • 添加了函数 PQfullProtocolVersion()（提交 cdb6b0fd）
    • 类型 pg_int64 已弃用（提交 3c86223c）
    • 添加了 min_protocol_version 和 max_protocol_version 连接参数（提交 285613c6）
    • 添加了 sslkeylogfile（提交 2da74d8d）
    • 添加了 oauth_issuer、oauth_client_id、oauth_client_secret 和 oauth_scope 连接参数（提交 b3f0be78）
    • 添加了函数 PQservice()（提交 4b99fed7） 在提交 fef6da9e 中已撤销）
  • PostgreSQL 17
    • 添加了用于关闭 Portal 和 Statement 的以下函数（提交 28b57265）
      • PQclosePrepared()
      • PQclosePortal()
      • PQsendClosePrepared()
      • PQsendClosePortal()
    • 添加了函数 PQchangePassword()（提交 a7be2a6c）
    • 添加了函数 PQsendPipelineSync()（提交 4794c2d3）
    • 添加了以下非阻塞查询取消函数（提交 61461a30）
      • PQcancelCreate()
      • PQcancelStart()
      • PQcancelPoll()
      • PQcancelReset()
      • PQcancelBlocking()
    • 添加了函数 PQsocketPoll() （提交 f5e4dedf）
    • 添加了函数 PQsetChunkedRowsMod() （提交 4643a2b2）
    • 添加了连接参数 sslnegotiation（提交 d39a49c1）
  • PostgreSQL 16
    • 添加了 require_auth 连接参数（提交 3a465cc6）
    • 在可用时使用 SOCK_CLOEXEC 和 SOCK_NONBLOCK（提交 bfc9497e）
    • 添加了连接参数 sslcertmode（提交 36f40ce2）
    • 添加了连接参数 load_balance_hosts，提供连接负载均衡支持（提交 7f5b1981）
    • 添加了连接参数 gssdelegation（初始提交 6633cfb2）
  • PostgreSQL 15
    • 支持服务器主题备用名称中的 IPv4 和 IPv6 地址（提交 c1932e54)
    • PQcancel() 现在使用 PGconn 的 tcp_user_timeout 和 tcp_keepalives_{count|idle|interval} 设置（提交 5987feb7）
    • PQsslAttribute(NULL, "library") 在不需要连接句柄的情况下返回正在使用的 SSL 库的名称（提交 ebc8b7d4）
  • PostgreSQL 14
    • in_hot_standby 现在由 PQparameterStatus() 报告（提交 bf8a662c）
    • 添加了 pipeline 模式（提交 acb7e4eb）
    • 改进了 PQtrace() 的输出格式（提交 198b3716）
    • 在 target_session_attrs 中添加了选项 read-only、primary、standby 和 prefer-standby（提交 ee28cacf）
    • SSL 连接默认设置了服务器名称指示（SNI）（提交 5c55dc8b）
    • 添加了连接参数 sslsni（提交 5c55dc8b）
    • 添加了连接参数 sslcrldir（提交 f5465fad）
    • 移除了已弃用的连接参数 authtype 和 tty（提交 14d9b376）
  • PostgreSQL 13
    • 添加了连接参数 ssl_min_protocol_version 和 ssl_max_protocol_version（初始提交 ff8ca5fa）
    • 添加了连接参数 channel_binding（提交 d6e612f8）
    • 添加了连接参数 sslpassword（提交 e60b480d）
  • PostgreSQL 12
    • 向函数 PQsetErrorVerbosity() 添加了 SQLSTATE 详细级别（提交 7bac3aca）
    • 添加了连接参数 gssencmode（提交 b0b39f72）
    • 添加了连接参数 tcp_user_timeout（提交 249d6499）
  • PostgreSQL 10
  • PostgreSQL 9.4
    • 添加了函数 PQhostaddr()（提交 9f80f483）
    • PQconndefaults() 现在会忽略无效的服务文件（提交 9e0a97f1）
    • 支持 TLS 协议版本超出 TLSv1（提交 820f08ca）
  • PostgreSQL 9.3
    • 添加了函数 PQconninfo()（提交 65c3bf19）
  • PostgreSQL 9.2
    • 添加了函数 PQsetSingleRowMode()（提交 ea56ed9a）
    • 添加了连接参数 sslcompression（提交 64aea1eb）
  • PostgreSQL 9.1
    • 添加了连接参数 client_encoding（提交 02e14562）
    • 添加了连接参数 requirepeer（初始提交 040aee29）
    • 添加了函数 PQlibVersion()（提交 de9a4c27）
  • PostgreSQL 9.0
  • PostgreSQL 8.4
    • sslmode 连接参数添加了值 verify-ca 和 verify-full（提交 e883d0b5）
    • 支持通配符服务器证书（初始提交 cb10467d）
    • 现在可以指定客户端证书的文件位置（提交 5f3724dd）
    • 当没有剩余的数据库连接时，OpenSSL 回调函数将不再被注册（提交 4e816286）
    • 添加了函数 PQinitOpenSSL()（提交 97503a52)
    • 添加了函数 lo_import_with_oid()（提交 8436f9a0）
    • 添加了连接参数 sslcert、sslcrl、sslkey 和 sslrootcert（提交 5f3724dd）
  • PostgreSQL 8.3
    • 添加了连接参数 gsslib（提交 f70866fb）
  • PostgreSQL 8.1
    • 添加了连接参数 krbsrvname（提交 72c53ac3）
  • PostgreSQL 8.0
    • 添加了函数 PQcancel()（提交 44e8a968）
    • 添加了函数 PQprepare()/PQsendPrepared()（提交 9d9cfb1a）
    • 添加了 PQserverVersion()（提交 f79fbb2b）
  • PostgreSQL 7.4
    • 弃用了 tty 选项（提交 cb7fb3ca）
    • 弃用了连接参数 requiressl（提交 397831e1）
    • 添加了连接参数 sslmode（提交 397831e1）
  • PostgreSQL 7.3
    • 添加了连接参数 connect_timeout（提交 f0ed4311）
  • PostgreSQL 7.1
    • 添加了连接参数 service（提交 f2ef4df4）
    • 添加了连接参数 requiressl（提交 7bc654bb）
  • PostgreSQL 7.0
    • 添加了以下函数（提交 3ab5b1f1）
      • PQconnectStart()
      • PQconnectPoll()
      • PQresetStart()
      • PQresetPoll()
      • PQsetenvStart()
      • PQsetenvPoll()
      • PQsetenvAbort()
    • 添加了非阻塞模式支持，包括以下函数（提交 10d7287a）
      • PQsetnonblocking()
      • PQisnonblocking()
      • PQflush()
    • 添加了连接参数 hostaddr（提交 3ab5b1f1）
  • PostgreSQL 6.3
    • 弃用了连接参数 authtype（提交 d5bbe2ac）
  • PostgreSQL 6.1
    • 添加了连接参数 authtype 和 password（提交 3a7c93e7）
  • PostgreSQL 6.0
    • 添加了函数 PQconnectdb()（提交 4aa1734f）
    • 添加了连接参数 user、dbname、host、port、tty 和 options（提交 4aa1734f）

示例

以下示例代码演示了如何使用 libpq 连接到 PostgreSQL 服务器并执行一个简单的查询——“SELECT 'hello world'”——然后显示输出。

#include <stdio.h>
#include <stdlib.h>
#include <libpq-fe.h>

static void
exit_nicely(PGconn *conn)
{
    PQfinish(conn);
    exit(1);
}

int
main(int argc, char **argv)
{
    const char *conninfo;
    PGconn     *conn;
    PGresult   *res;

    if (argc > 1)
        conninfo = argv[1];
    else
        conninfo = "dbname=postgres";

    /* Connect to the database */
    conn = PQconnectdb(conninfo);

    /* Verify success of database connection */
    if (PQstatus(conn) != CONNECTION_OK)
    {
        fprintf(stderr, "Connection to database failed: %s",
                PQerrorMessage(conn));
        exit_nicely(conn);
    }

    /* Execute a simple query and display the results */
    res = PQexec(conn, "SELECT 'Hello World'");
    printf("%s\n", PQgetvalue(res, 0, 0));

    PQclear(res);

    /* close the connection to the database and cleanup */
    PQfinish(conn);

    return 0;
}

更多示例可以在 PostgreSQL 手册以及 PostgreSQL 源代码分发版中的 src/test/examples/ 目录中找到。

分类

应用程序接口

反馈

请在此处 提交有关“libpq”的任何评论、建议或更正。