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

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 通过计算如果指定的详细级别设置在生成给定 PGresult 时对连接有效，则 PQresultErrorMessage 将生成的错误消息来解决此需求。如果 PGresult 不是错误结果，则会报告“PGresult 不是错误结果”。返回的字符串包含尾随换行符。

与大多数其他用于从 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内置数据类型的 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 将返回空字符串，而不是空指针。）

返回字段值的实际长度（以字节为单位）。行号和列号从 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语句影响的行数，该语句生成了 PGresult。此函数只能在执行 SELECT、CREATE TABLE AS、INSERT、UPDATE、DELETE、MERGE、MOVE、FETCH 或 COPY 语句，或者包含 INSERT、UPDATE、DELETE 或 MERGE 语句的预备查询的 EXECUTE 之后使用。如果生成 PGresult 的命令是其他任何内容，PQcmdTuples 将返回一个空字符串。调用者不应直接释放返回值。当关联的 PGresult 句柄传递给 PQclear 时，它将被释放。

如果命令是 INSERT，并且该命令恰好将一行插入到具有 OID 的表中，或者如果命令是包含适合的 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 返回使用 malloc() 分配的内存中 str 参数的转义版本。当不再需要结果时，应使用 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 返回使用 malloc() 分配的内存中转义为 SQL 标识符的 str 参数的版本。当不再需要结果时，必须使用 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 设置为零，失败时设置为非零。目前，唯一可能的错误情况涉及源字符串中的无效多字节编码。错误时仍会生成输出字符串，但可以预期服务器会将其拒绝为格式错误。发生错误时，会在 conn 对象中存储一条合适的消息，无论 error 是否为 NULL。

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

PQescapeString 是 PQescapeStringConn 的较旧的、已弃用的版本。

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

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

PQescapeString 可以安全地用于一次只使用一个 PostgreSQL 连接的客户端程序中（在这种情况下，它可以“在幕后”找到它需要知道的内容）。在其他情况下，它是一种安全隐患，应避免使用，而应使用 PQescapeStringConn。

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

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

某些字节值在用作SQL语句中 bytea 文字的一部分时必须转义。PQescapeByteaConn 使用十六进制编码或反斜杠转义来转义字节。有关更多信息，请参见 第 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 参数。