PQconnectdb 与数据库服务器建立一个新连接。

PGconn *PQconnectdb(const char *conninfo)
       

此例程使用从字符串 conninfo 中取得的参数打开一个新的数据库连接。与下面的 PQsetdbLogin() 不同，该例程的参数集可以在不改变函数签名的情况下扩展，因此应用程序编程首选使用此例程或其非阻塞版本 PQconnectStart / PQconnectPoll。传入的字符串可以为空以使用全部默认参数，也可以包含一个或多个用空白分隔的参数设置。

每个参数设置的形式为 keyword = value。（要写入空值或包含空格的值，请用单引号包围，例如 keyword = 'a value'。值中的单引号必须写作 \'。等号两边的空格是可选的。）目前可识别的参数关键字有：

如果任何参数未指定，则检查相应的环境变量（见"环境变量"一节）。如果环境变量也未设置，则使用硬编码的默认值。返回值是指向一个抽象 struct 的指针，该结构表示到后端的连接。

PQsetdbLogin 与数据库服务器建立一个新连接。

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd)

这是 PQconnectdb 的前身，参数个数固定但功能相同。

PQsetdb 与数据库服务器建立一个新连接。

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName)

这是一个宏，以空指针作为 login 和 pwd 参数调用 PQsetdbLogin()。它主要是为了与旧程序保持向后兼容而保留。

PQconnectStart, PQconnectPoll 以非阻塞方式建立与数据库服务器的连接。

PGconn *PQconnectStart(const char *conninfo)

PostgresPollingStatusType PQconnectPoll(PGconn *conn)

这两个例程用于打开到数据库服务器的连接，同时应用程序的执行线程不会在远程 I/O 上阻塞。

数据库连接使用传给 PQconnectStart 的字符串 conninfo 中的参数建立。该字符串的格式与上面 PQconnectdb 中描述的相同。

只要满足若干限制条件，PQconnectStart 和 PQconnectPoll 都不会阻塞：

首先，调用 conn=PQconnectStart("<connection_info_string>")。如果 conn 为 NULL，说明 libpq 无法分配新的 PGconn 结构。否则返回一个有效的 PGconn 指针（尽管它尚未表示一个有效的数据库连接）。从 PQconnectStart 返回后，调用 status=PQstatus(conn)。如果 status 等于 CONNECTION_BAD，则 PQconnectStart 失败。

如果 PQconnectStart 成功，下一阶段是轮询 libpq，使其继续进行连接序列。循环如下：默认将连接视为'非活跃'。如果 PQconnectPoll 上次返回了 PGRES_POLLING_ACTIVE，则改将其视为'活跃'。如果 PQconnectPoll(conn) 上次返回 PGRES_POLLING_READING，则在 PQsocket(conn) 上为读取执行 select。如果上次返回 PGRES_POLLING_WRITING，则在 PQsocket(conn) 上为写入执行 select。如果尚未调用过 PQconnectPoll（即刚调用完 PQconnectStart 之后），则视同它上次返回的是 PGRES_POLLING_WRITING。如果 select 表明套接字已就绪，将其视为'活跃'。一旦确定此连接处于'活跃'状态，就再次调用 PQconnectPoll(conn)。如果这次调用返回 PGRES_POLLING_FAILED，连接过程已失败。如果返回 PGRES_POLLING_OK，连接已成功建立。

注意，用 select() 确保套接字就绪只是一个（常见的）例子；如果还有其他可用手段，例如 poll() 调用，当然可以改用它。

在连接期间的任何时刻，都可以调用 PQstatus 检查连接状态。如果返回 CONNECTION_BAD，则连接过程已失败；如果返回 CONNECTION_OK，则连接已就绪。如上所述，这两种状态都应能从 PQconnectPoll 的返回值中同样检测到。其他状态只在（且仅会在）异步连接过程中出现，它们指示连接过程的当前阶段，例如可用于向用户提供反馈。这些状态可能包括：

注意，尽管这些常量会保留（为了维护兼容性），应用程序绝不应依赖它们按特定顺序出现、依赖它们全都出现，或依赖状态总是这些已记录的值之一。应用程序可以这样处理：

    switch(PQstatus(conn))
    {
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
    }

注意，如果 PQconnectStart 返回非 NULL 指针，使用完毕后必须调用 PQfinish，以释放该结构和所有关联的内存块。即使 PQconnectStart 或 PQconnectPoll 的调用失败，也必须这样做。

当前，如果 libpq 编译时定义了 USE_SSL，PQconnectPoll 会阻塞。此限制将来可能被移除。

当前，在 Windows 下 PQconnectPoll 会阻塞，除非 libpq 编译时定义了 WIN32_NON_BLOCKING_CONNECTIONS。这段代码尚未在 Windows 下测试过，因此目前默认关闭。将来可能改变。

这些函数会把套接字置于非阻塞状态，就像调用过 PQsetnonblocking 一样。

PQconndefaults 返回默认的连接选项。

PQconninfoOption *PQconndefaults(void)

struct PQconninfoOption
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Character to display for this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
}

返回一个连接选项数组。它可用来确定 PQconnectdb 的所有可用选项及其当前默认值。返回值指向一个 PQconninfoOption struct 数组，该数组以一个 keyword 指针为 NULL 的条目结尾。注意，默认值（"val" 字段）依赖于环境变量和其他上下文。调用者必须将连接选项数据视为只读。

处理完选项数组后，将它传递给 PQconninfoFree() 释放。如果不这样做，每次调用 PQconndefaults() 都会泄漏少量内存。

在 Postgres 7.0 之前的版本中，PQconndefaults() 返回指向静态数组的指针，而不是动态分配的数组。那样不是线程安全的，因此行为已被改变。

PQfinish 关闭与后端的连接，同时释放 PGconn 对象使用的内存。

void PQfinish(PGconn *conn)

注意，即使与后端的连接尝试失败（由 PQstatus 指示），应用也应调用 PQfinish 释放 PGconn 对象使用的内存。调用过 PQfinish 之后，不应再使用该 PGconn 指针。

PQreset 重置与后端的通信端口。

void PQreset(PGconn *conn)

此函数将关闭与后端的连接，并尝试使用先前使用的全部相同参数与同一个 postmaster 重新建立新连接。如果工作中的连接丢失，这可用于错误恢复。

PQresetStart PQresetPoll 以非阻塞方式重置与后端的通信端口。

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

这些函数将关闭与后端的连接，并尝试使用先前使用的全部相同参数与同一个 postmaster 重新建立新连接。如果工作中的连接丢失，这可用于错误恢复。它们与上面的 PQreset 的不同之处在于以非阻塞方式运作。这些函数受到与 PQconnectStart 和 PQconnectPoll 相同的限制。

调用 PQresetStart。如果返回 0，重置失败。如果返回 1，用与使用 PQconnectPoll 建立连接完全相同的方式，使用 PQresetPoll 对重置进行轮询。

PQdb 返回连接的数据库名。

char *PQdb(const PGconn *conn)

PQdb 及其后面几个函数返回在建立连接时确定的值。这些值在 PGconn 对象的整个生命周期内保持不变。

PQuser 返回连接的用户名。

char *PQuser(const PGconn *conn)

PQpass 返回连接的密码。

char *PQpass(const PGconn *conn)

PQhost 返回连接的服务器主机名。

char *PQhost(const PGconn *conn)

PQport 返回连接的端口。

char *PQport(const PGconn *conn)

PQtty 返回连接的调试 tty。

char *PQtty(const PGconn *conn)

PQoptions 返回连接中使用的后端选项。

char *PQoptions(const PGconn *conn)

PQstatus 返回连接的状态。

ConnStatusType PQstatus(const PGconn *conn)

状态可以是若干值之一。但在异步连接过程之外只能见到其中两个—— CONNECTION_OK 或 CONNECTION_BAD。正常的数据库连接状态为 CONNECTION_OK。失败的连接尝试由状态 CONNECTION_BAD 表示。通常，OK 状态会一直保持到调用 PQfinish 为止，但通信故障可能导致状态提前变为 CONNECTION_BAD。此时应用可以尝试调用 PQreset 来恢复。

关于可能见到的其他状态码，参见 PQconnectStart 和 PQconnectPoll 的条目。

PQerrorMessage 返回连接上最近一次操作所产生的错误消息。

char *PQerrorMessage(const PGconn* conn);
       

几乎所有 libpq 函数在失败时都会设置 PQerrorMessage。注意，按照 libpq 的惯例，非空的 PQerrorMessage 会包含一个末尾换行符。

PQbackendPID 返回处理此连接的后端服务器的进程 ID。

int PQbackendPID(const PGconn *conn);
       

后端 PID 可用于调试，也可用于与 NOTIFY 消息（其中包含发出通知的后端的 PID）进行比较。注意，该 PID 属于数据库服务器主机上执行的进程，而不是本地主机上的进程！

PQgetssl 返回连接中使用的 SSL 结构；若未使用 SSL 则返回 NULL。

SSL *PQgetssl(const PGconn *conn);
       

此结构可用于核实加密级别、检查服务器证书等。有关此结构的信息，请参阅 OpenSSL 文档。

必须定义 USE_SSL 才能获得此函数的原型。这样做还会自动包含来自 OpenSSL 的 ssl.h。

PQgetssl 返回连接中使用的 SSL 结构；若未使用 SSL 则返回 NULL。

SSL *PQgetssl(const PGconn *conn);
       

此结构可用于核实加密级别、检查服务器证书等。有关此结构的信息，请参阅 OpenSSL 文档。

必须定义 USE_SSL 才能获得此函数的原型。这样做还会自动包含来自 OpenSSL 的 ssl.h。