将命令提交到服务器并等待结果。

PGresult *PQexec(PGconn *conn, const char *command);

返回一个 PGresult 指针或可能是空指针。通常会返回非空指针，除非在内存不足的情况下或出现严重错误（例如无法将命令发送到服务器）。应调用 PQresultStatus 函数来检查返回值是否存在任何错误（包括空指针的值，在这种情况下它将返回 PGRES_FATAL_ERROR）。使用 PQerrorMessage 获取有关此类错误的更多信息。

将命令提交到服务器并等待结果，并能够单独传递与SQL命令文本不同的参数。

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

PQexecParams 类似于 PQexec，但提供了其他功能：参数值可以与命令字符串本身分开指定，并且可以以文本或二进制格式请求查询结果。

函数参数为

提交创建具有给定参数的准备语句的请求，并等待完成。

PGresult *PQprepare(PGconn *conn,
                    const char *stmtName,
                    const char *query,
                    int nParams,
                    const Oid *paramTypes);

PQprepare 创建一个准备语句，以便稍后使用 PQexecPrepared 执行。此功能允许重复执行命令，而无需每次都进行解析和计划；有关详细信息，请参阅 PREPARE。

该函数根据查询字符串 query 创建一个名为 stmtName 的预处理语句，该字符串必须包含单个 SQL 命令。stmtName 可以是 "" 以创建未命名的语句，在这种情况下，任何现有的未命名语句都会被自动替换；否则，如果在当前会话中已定义了语句名称，则会发生错误。如果使用了任何参数，则在查询中将其引用为 $1、$2 等。nParams 是参数的数量，其类型在数组 paramTypes[] 中预先指定。（当 nParams 为零时，数组指针可以是 NULL。）paramTypes[] 通过 OID 指定要分配给参数符号的数据类型。如果 paramTypes 为 NULL，或数组中的任何特定元素为零，则服务器会以与处理未类型化字面字符串相同的方式为参数符号分配数据类型。此外，查询可以使用编号高于 nParams 的参数符号；也会为这些符号推断数据类型。（有关如何找出推断出的数据类型的方法，请参阅 PQdescribePrepared。）

与 PQexec 一样，结果通常是 PGresult 对象，其内容指示服务器端成功或失败。空结果表示内存不足或根本无法发送命令。使用 PQerrorMessage 获取有关此类错误的更多信息。

发送请求以使用给定参数执行预处理语句，并等待结果。

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPrepared 类似于 PQexecParams，但要执行的命令是通过命名先前准备好的语句来指定的，而不是提供查询字符串。此功能允许重复使用的命令仅解析和计划一次，而不是每次执行时都解析和计划。该语句必须在当前会话中预先准备。

参数与 PQexecParams 相同，只是给出了预处理语句的名称而不是查询字符串，并且 paramTypes[] 参数不存在（因为它不需要，因为预处理语句的参数类型在创建时已确定）。

提交请求以获取有关指定预处理语句的信息，并等待完成。

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

PQdescribePrepared 允许应用程序获取有关先前准备好的语句的信息。

stmtName 可以是 "" 或 NULL 以引用未命名语句，否则它必须是现有预处理语句的名称。成功时，将返回状态为 PGRES_COMMAND_OK 的 PGresult。函数 PQnparams 和 PQparamtype 可以应用于此 PGresult 以获取有关预处理语句参数的信息，并且函数 PQnfields、PQfname、PQftype 等提供有关语句的结果列（如果有）的信息。

提交请求以获取有关指定门户的信息，并等待完成。

PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

PQdescribePortal 允许应用程序获取有关先前创建的门户的信息。（libpq 不提供对门户的任何直接访问，但您可以使用此函数检查使用 DECLARE CURSOR SQL 命令创建的光标的属性。）

portalName 可以是 "" 或 NULL 以引用未命名门户，否则它必须是现有门户的名称。成功时，将返回状态为 PGRES_COMMAND_OK 的 PGresult。函数 PQnfields、PQfname、PQftype 等可以应用于 PGresult 以获取有关门户的结果列（如果有）的信息。

提交请求以关闭指定的预处理语句，并等待完成。

PGresult *PQclosePrepared(PGconn *conn, const char *stmtName);

PQclosePrepared 允许应用程序关闭先前准备好的语句。关闭语句会释放服务器上与其关联的所有资源，并允许重用其名称。

stmtName 可以是 "" 或 NULL 以引用未命名语句。如果不存在具有此名称的语句，则没有问题，在这种情况下，操作将是无操作。成功时，将返回状态为 PGRES_COMMAND_OK 的 PGresult。

提交请求以关闭指定的门户，并等待完成。

PGresult *PQclosePortal(PGconn *conn, const char *portalName);

PQclosePortal 允许应用程序触发先前创建的门户的关闭。关闭门户会释放服务器上与其关联的所有资源，并允许重用其名称。（libpq 不提供对门户的任何直接访问，但您可以使用此函数关闭使用 DECLARE CURSOR SQL 命令创建的光标。）

portalName 可以是 "" 或 NULL 以引用未命名门户。如果不存在具有此名称的门户，则没有问题，在这种情况下，操作将是无操作。成功时，将返回状态为 PGRES_COMMAND_OK 的 PGresult。

返回命令的结果状态。

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatus 可以返回以下值之一

如果结果状态为 PGRES_TUPLES_OK、PGRES_SINGLE_TUPLE 或 PGRES_TUPLES_CHUNK，则可以使用下面描述的函数检索查询返回的行。请注意，恰好检索零行的 SELECT 命令仍显示 PGRES_TUPLES_OK。PGRES_COMMAND_OK 用于永远不会返回行的命令（INSERT 或不带 RETURNING 子句的 UPDATE 等）。PGRES_EMPTY_QUERY 响应可能表示客户端软件中的错误。

状态为 PGRES_NONFATAL_ERROR 的结果永远不会被 PQexec 或其他查询执行函数直接返回；此类结果将传递给通知处理器（参见 第 32.13 节）。

将 PQresultStatus 返回的枚举类型转换为描述状态代码的字符串常量。调用者不应释放结果。

char *PQresStatus(ExecStatusType status);

返回与命令关联的错误消息，如果未发生错误则返回空字符串。

char *PQresultErrorMessage(const PGresult *res);

如果发生错误，则返回的字符串将包含尾随换行符。调用者不应直接释放结果。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

在 PQexec 或 PQgetResult 调用之后，PQerrorMessage（在连接上）将返回与 PQresultErrorMessage（在结果上）相同的字符串。但是，PGresult 将保留其错误消息直到销毁，而连接的错误消息将在执行后续操作时更改。当您想知道与特定 PGresult 关联的状态时，请使用 PQresultErrorMessage；当您想知道连接上最新操作的状态时，请使用 PQerrorMessage。

返回与 PGresult 对象关联的错误消息的重新格式化版本。

char *PQresultVerboseErrorMessage(const PGresult *res,
                                  PGVerbosity verbosity,
                                  PGContextVisibility show_context);

在某些情况下，客户端可能希望获取先前报告错误的更详细版本。PQresultVerboseErrorMessage 通过计算 PQresultErrorMessage 在生成给定 PGresult 时如果连接的指定详细程度设置生效将产生的消息来满足此需求。如果 PGresult 不是错误结果，则改为报告 “PGresult is not an error result”。返回的字符串包含尾随换行符。

与大多数用于从 PGresult 中提取数据的其他函数不同，此函数的结果是新分配的字符串。当不再需要字符串时，调用者必须使用 PQfreemem() 释放它。

如果内存不足，则可能返回 NULL。

返回错误报告的单个字段。

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcode 是错误字段标识符；请参见下面列出的符号。如果 PGresult 不是错误或警告结果，或者不包含指定的字段，则返回 NULL。字段值通常不包含尾随换行符。调用者不应直接释放结果。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

以下字段代码可用

客户端负责格式化显示的信息以满足其需求；特别是它应该根据需要换行。错误消息字段中出现的换行符应被视为段落分隔符，而不是换行符。

libpq 内部生成的错误将具有严重性和主要消息，但通常没有其他字段。

请注意，错误字段仅可从 PGresult 对象获取，而不是 PGconn 对象；没有 PQerrorField 函数。

释放与 PGresult 关联的存储。每个命令结果都应在不再需要时通过 PQclear 释放。

void PQclear(PGresult *res);

如果参数是 NULL 指针，则不执行任何操作。

您可以根据需要保留 PGresult 对象；当您发出新命令时，它不会消失，即使您关闭连接也不会消失。要删除它，您必须调用 PQclear。如果不这样做，会导致应用程序出现内存泄漏。

返回查询结果中的行数（元组）。（请注意，PGresult 对象最多只能包含 INT_MAX 行，因此 int 结果就足够了。）

int PQntuples(const PGresult *res);

返回查询结果每一行中的列数（字段）。

int PQnfields(const PGresult *res);

返回与给定列号关联的列名。列号从 0 开始。调用者不应直接释放结果。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

char *PQfname(const PGresult *res,
              int column_number);

如果列号超出范围，则返回 NULL。

返回与给定列名关联的列号。

int PQfnumber(const PGresult *res,
              const char *column_name);

如果给定名称与任何列都不匹配，则返回 -1。

给定名称被视为 SQL 命令中的标识符，即除非加双引号，否则会被转换为小写。例如，给定从以下 SQL 命令生成的查询结果：

SELECT 1 AS FOO, 2 AS "BAR";

我们将得到以下结果：

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

返回从其中获取给定列的表的 OID。列号从 0 开始。

Oid PQftable(const PGresult *res,
             int column_number);

如果列号超出范围，或者指定的列不是对表列的简单引用，则返回 InvalidOid。您可以查询系统表 pg_class 以准确确定引用了哪个表。

当您包含 libpq 头文件时，将定义类型 Oid 和常量 InvalidOid。它们都将是某种整数类型。

返回构成指定查询结果列的列（在其表中）的列号。查询结果列号从 0 开始，但表列具有非零编号。

int PQftablecol(const PGresult *res,
                int column_number);

如果列号超出范围，或者指定的列不是对表列的简单引用，则返回零。

返回指示给定列格式的格式代码。列号从 0 开始。

int PQfformat(const PGresult *res,
              int column_number);

格式代码零表示文本数据表示，而格式代码一表示二进制表示。（其他代码保留供将来定义。）

返回与给定列号关联的数据类型。返回的整数是类型的内部 OID 编号。列号从 0 开始。

Oid PQftype(const PGresult *res,
            int column_number);

您可以查询系统表 pg_type 以获取各种数据类型的名称和属性。该OID内置数据类型的定义在 PostgreSQL 安装的 include 目录中的 catalog/pg_type_d.h 文件中。

返回与给定列号关联的列的类型修饰符。列号从 0 开始。

int PQfmod(const PGresult *res,
           int column_number);

修饰符值的解释是特定于类型的；它们通常表示精度或大小限制。值 -1 用于表示““无可用信息””。大多数数据类型不使用修饰符，在这种情况下，值始终为 -1。

返回与给定列号关联的列的大小（以字节为单位）。列号从 0 开始。

int PQfsize(const PGresult *res,
            int column_number);

PQfsize 返回数据库行中为此列分配的空间，换句话说，是数据类型服务器内部表示的大小。（因此，它对客户端来说并不是很有用。）负值表示数据类型是可变长度的。

如果 PGresult 包含二进制数据，则返回 1；如果包含文本数据，则返回 0。

int PQbinaryTuples(const PGresult *res);

此函数已弃用（除了与 COPY 结合使用的情况），因为单个 PGresult 可以包含某些列中的文本数据和其他列中的二进制数据。 PQfformat 更为推荐。 PQbinaryTuples 仅当结果的所有列都是二进制的（格式 1）时才返回 1。

返回 PGresult 的一行的一个字段值。行号和列号从 0 开始。调用者不应直接释放结果。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

char *PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

对于文本格式的数据，PQgetvalue 返回的值是字段值的以 null 结尾的字符字符串表示形式。对于二进制格式的数据，该值采用由数据类型的 typsend 和 typreceive 函数确定的二进制表示形式。（在这种情况下，该值实际上也后跟一个零字节，但这通常没有用，因为该值可能包含嵌入的 null。）

如果字段值为 null，则返回空字符串。请参阅 PQgetisnull 以区分 null 值和空字符串值。

PQgetvalue 返回的指针指向属于 PGresult 结构的存储。不应修改它指向的数据，并且如果要在 PGresult 结构本身的生命周期之外使用它，则必须将其显式复制到其他存储中。

测试字段是否为 null 值。行号和列号从 0 开始。

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

如果字段为 null，此函数返回 1；如果字段包含非 null 值，则返回 0。（请注意，对于 null 字段，PQgetvalue 将返回空字符串，而不是 null 指针。）

返回字段值的大小（以字节为单位）。行号和列号从 0 开始。

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

这是特定数据值的实际数据长度，即 PQgetvalue 指向的对象的大小。对于文本数据格式，这与 strlen() 相同。对于二进制格式，这是基本信息。请注意，不应依赖 PQfsize 来获取实际数据长度。

返回已准备语句的参数数量。

int PQnparams(const PGresult *res);

此函数仅在检查 PQdescribePrepared 的结果时有用。对于其他类型的结果，它将返回零。

返回指示的语句参数的数据类型。参数号从 0 开始。

Oid PQparamtype(const PGresult *res, int param_number);

此函数仅在检查 PQdescribePrepared 的结果时有用。对于其他类型的结果，它将返回零。

将所有行以及（可选）列名打印到指定的输出流。

void PQprint(FILE *fout,      /* output stream */
             const PGresult *res,
             const PQprintOpt *po);
typedef struct
{
    pqbool  header;      /* print output field headings and row count */
    pqbool  align;       /* fill align the fields */
    pqbool  standard;    /* old brain dead format */
    pqbool  html3;       /* output HTML tables */
    pqbool  expanded;    /* expand tables */
    pqbool  pager;       /* use pager for output if needed */
    char    *fieldSep;   /* field separator */
    char    *tableOpt;   /* attributes for HTML table element */
    char    *caption;    /* HTML table caption */
    char    **fieldName; /* null-terminated array of replacement field names */
} PQprintOpt;

此函数以前由 psql 用于打印查询结果，但现在已不再使用。请注意，它假定所有数据都采用文本格式。

返回生成 PGresult 的 SQL 命令的命令状态标记。

char *PQcmdStatus(PGresult *res);

通常这只是命令的名称，但它可能包含其他数据，例如处理的行数。调用者不应直接释放结果。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

返回 SQL 命令影响的行数。

char *PQcmdTuples(PGresult *res);

此函数返回一个字符串，其中包含生成SQL语句影响的行数。此函数只能在执行 SELECT、CREATE TABLE AS、INSERT、UPDATE、DELETE、MERGE、MOVE、FETCH 或 COPY 语句，或包含 INSERT、UPDATE、DELETE 或 MERGE 语句的已准备查询的 EXECUTE 之后使用。如果生成 PGresult 的命令是其他任何内容，则 PQcmdTuples 返回空字符串。调用者不应直接释放返回值。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

如果命令是将恰好一行插入到具有OID的表中的INSERT命令，或者是对包含合适INSERT语句的已准备查询的EXECUTE命令，则返回插入行的OID。SQL否则，此函数返回InvalidOid。如果受INSERT语句影响的表不包含OID，则此函数也将返回InvalidOid。

Oid PQoidValue(const PGresult *res);

此函数已弃用，建议使用PQoidValue，并且它不是线程安全的。它返回一个包含插入行OID的字符串，而PQoidValue返回OID值。

char *PQoidStatus(const PGresult *res);

char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);

PQescapeLiteral 转义字符串以在SQL命令中使用。这在将数据值作为SQL命令中的文字常量插入时非常有用。某些字符（如引号和反斜杠）必须转义，以防止SQL解析器对其进行特殊解释。PQescapeLiteral 执行此操作。

PQescapeLiteral 返回str参数的转义版本，该版本存储在使用malloc()分配的内存中。当不再需要结果时，应使用PQfreemem()释放此内存。不需要终止零字节，也不应将其计入length中。（如果在处理length字节之前找到终止零字节，则PQescapeLiteral在零处停止；因此，其行为类似于strncpy。）返回字符串将所有特殊字符替换，以便它们可以被PostgreSQL字符串文字解析器正确处理。还会添加一个终止零字节。结果字符串中包含必须围绕PostgreSQL字符串文字的单引号。

发生错误时，PQescapeLiteral返回NULL，并在conn对象中存储适当的消息。

请注意，当数据值作为PQexecParams或其同级例程中的单独参数传递时，无需也不正确地进行转义。

char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);

PQescapeIdentifier 转义字符串以用作SQL标识符，例如表、列或函数名称。当用户提供的标识符可能包含特殊字符时，这很有用，否则SQL解析器不会将其解释为标识符的一部分，或者当标识符可能包含应保留其大小写的大写字符时。

PQescapeIdentifier 返回str参数作为SQL标识符转义的版本，该版本存储在使用malloc()分配的内存中。当不再需要结果时，必须使用PQfreemem()释放此内存。不需要终止零字节，也不应将其计入length中。（如果在处理length字节之前找到终止零字节，则PQescapeIdentifier在零处停止；因此，其行为类似于strncpy。）返回字符串将所有特殊字符替换，以便它将被正确处理为SQL标识符。还会添加一个终止零字节。返回字符串也将用双引号括起来。

发生错误时，PQescapeIdentifier返回NULL，并在conn对象中存储适当的消息。

size_t PQescapeStringConn(PGconn *conn,
                          char *to, const char *from, size_t length,
                          int *error);

PQescapeStringConn 转义字符串文字，类似于PQescapeLiteral。与PQescapeLiteral不同，调用者负责提供大小合适的缓冲区。此外，PQescapeStringConn不会生成必须围绕PostgreSQL字符串文字的单引号；它们应该在结果插入到的SQL命令中提供。from参数指向要转义的字符串的第一个字符，length参数给出此字符串中的字节数。不需要终止零字节，也不应将其计入length中。（如果在处理length字节之前找到终止零字节，则PQescapeStringConn在零处停止；因此，其行为类似于strncpy。）to应指向一个缓冲区，该缓冲区能够容纳至少比length值的两倍多一个字节，否则行为未定义。如果to和from字符串重叠，行为也未定义。

如果error参数不是NULL，则成功时*error设置为零，错误时设置为非零。目前，唯一可能的错误条件涉及源字符串中的无效多字节编码。输出字符串在错误时仍然会生成，但可以预期服务器会将其拒绝为格式错误。发生错误时，无论error是否为NULL，都会在conn对象中存储适当的消息。

PQescapeStringConn返回写入to的字节数，不包括终止零字节。

PQescapeString是PQescapeStringConn的旧版本，已弃用。

size_t PQescapeString (char *to, const char *from, size_t length);

与PQescapeStringConn唯一的区别是PQescapeString不接受PGconn或error参数。因此，它无法根据连接属性（如字符编码）调整其行为，因此它可能会给出错误的结果。此外，它无法报告错误条件。

PQescapeString可以安全地用于一次仅使用一个PostgreSQL连接的客户端程序（在这种情况下，它可以找出它需要“幕后”了解的信息）。在其他情况下，它是一种安全隐患，应避免使用，而应使用PQescapeStringConn。

转义二进制数据以在SQL命令中与类型bytea一起使用。与PQescapeStringConn一样，这仅在将数据直接插入SQL命令字符串时使用。

unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);

某些字节值在用作语句中的bytea文字的一部分时必须转义。SQLPQescapeByteaConn使用十六进制编码或反斜杠转义来转义字节。有关更多信息，请参见第 8.4 节。

from参数指向要转义的字符串的第一个字节，from_length参数给出此二进制字符串中的字节数。（不需要终止零字节，也不计入。）to_length参数指向一个变量，该变量将保存结果转义字符串的长度。此结果字符串长度包括结果的终止零字节。

PQescapeByteaConn返回from参数二进制字符串的转义版本，该版本存储在使用malloc()分配的内存中。当不再需要结果时，应使用PQfreemem()释放此内存。返回字符串将所有特殊字符替换，以便它们可以被PostgreSQL字符串文字解析器和bytea输入函数正确处理。还会添加一个终止零字节。必须围绕PostgreSQL字符串文字的单引号不是结果字符串的一部分。

发生错误时，将返回空指针，并在conn对象中存储适当的错误消息。当前，唯一可能的错误是结果字符串的内存不足。

PQescapeBytea是PQescapeByteaConn的旧版本，已弃用。

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

与PQescapeByteaConn唯一的区别是PQescapeBytea不接受PGconn参数。因此，PQescapeBytea只能安全地用于一次仅使用一个PostgreSQL连接的客户端程序（在这种情况下，它可以找出它需要“幕后”了解的信息）。如果在使用多个数据库连接的程序中使用它，则它可能会给出错误的结果（在这种情况下，请使用PQescapeByteaConn）。

将二进制数据的字符串表示形式转换为二进制数据——这是PQescapeBytea的反向操作。当以文本格式检索bytea数据时需要此操作，但以二进制格式检索时则不需要。

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

from参数指向一个字符串，例如当应用于bytea列时，PQgetvalue可能返回的字符串。PQunescapeBytea将此字符串表示形式转换为其二进制表示形式。它返回一个指向使用malloc()分配的缓冲区的指针，或者在出错时返回NULL，并将缓冲区的大小放入to_length中。当不再需要结果时，必须使用PQfreemem释放它。

此转换并非PQescapeBytea的完全反向操作，因为从PQgetvalue接收到的字符串不应被“转义”。特别是这意味着无需考虑字符串引用，因此无需PGconn参数。