Postgresql 中文操作指南

PQfreemem #

释放 libpq 分配的内存，尤其是 PQescapeByteaConn 、 PQescapeBytea 、 PQunescapeBytea 和 PQnotifies 。特别重要的是在 Microsoft Windows 上使用这个函数，而不是 free() 。这是因为在 DLL 中分配内存并在应用程序中释放内存仅适用于多线程/单线程、发布/调试和静态/动态标志对 DLL 和应用程序相同的情况。在非 Microsoft Windows 平台上，此函数与标准库函数 free() 相同。

释放 PQconndefaults 或 PQconninfoParse 分配的数据结构。

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

一个简单的 PQfreemem 不适用于此，因为数组包含对从属字符串的引用。

准备 PostgreSQL 密码的加密形式。

此函数面向希望发送 ALTER USER joe PASSWORD 'pwd' 等命令的客户端应用程序。良好的做法是不要在这样的命令中发送原始明文密码，因为它可能会显示在命令日志、活动显示屏等中。相反，在发送密码之前，使用此函数将其转换为加密形式。

passwd 和 user 参数是明文密码，以及它所针对的用户 SQL 名称。 algorithm 指定用于加密密码的加密算法。当前支持的算法是 md5 和 scram-sha-256 ( on 和 off 也被接受为 md5 的别名，以兼容较旧的服务器版本)。请注意，对 scram-sha-256 的支持是在 PostgreSQL 版本 10 中引入的，并且不会与较旧的服务器版本正确协作。如果 algorithm 是 NULL ，此函数将查询服务器以获取 password_encryption 设置的当前值。这可能会阻塞，并且当当前事务中止或连接忙于执行另一个查询时，会失败。如果你希望使用服务器的默认算法，但希望避免阻塞，请在调用 PQencryptPasswordConn 之前自己查询 password_encryption ，然后将该值作为 algorithm 传递。

返回值是 malloc 分配的字符串。调用者可以假设该字符串不包含任何需要转义的特殊字符。完成后使用 PQfreemem 释放结果。在错误的情况下，将返回 NULL ，并且会将一个合适的错误消息存储在连接对象中。

准备 PostgreSQL 密码的 md5 加密形式。

PQencryptPassword 是 PQencryptPasswordConn 的一个旧版本。不同之处在于 PQencryptPassword 不要求连接对象，并且总是把 md5 用作加密算法。

用给定的状态构造一个空的 PGresult 对象。

这是 libpq 的内部函数，用于分配和初始化一个空的 PGresult 对象。如果无法分配内存，此函数返回 NULL 。它被导出，因为某些应用程序会发现生成结果对象（尤其是错误状态对象）很有用。如果 conn 不为 null 并且 status 指示一个错误，指定连接的当前错误消息将被复制到 PGresult 。此外，如果 conn 不为 null，任何在连接中注册的事件过程将被复制到 PGresult 中。（它们不会获得 PGEVT_RESULTCREATE 调用，但请参见 PQfireResultCreateEvents 。）请注意，最终应该在对象上调用 PQclear ，就像对 libpq 本身返回的 PGresult 一样。

针对在_PGresult_对象中注册的每个事件过程触发一个_PGEVT_RESULTCREATE_事件（见 Section 34.14）。如果任何事件过程失败，则返回非零；为零。

conn 参数传递给事件过程，但不会直接使用。如果事件过程不会使用，它可以是 NULL 。

对于已为此对象收到 PGEVT_RESULTCREATE 或 PGEVT_RESULTCOPY 事件的事件过程，不会再次触发。

此函数与 PQmakeEmptyPGresult 分开的主要原因是，在调用事件过程之前经常需要创建一个 PGresult 并用数据填充它。

对 PGresult 对象进行复制。复制的对象与源结果没有任何链接，并且在不需要该复制的内容时必须调用 PQclear 。如果函数失败，则返回 NULL 。

这并不是要进行精确的复制。返回的结果总会被置为 PGRES_TUPLES_OK 状态，且不会复制源中的任何错误信息。（但是，它确实会复制命令状态字符串。） flags 参数决定还会复制什么。它是一个多个标志的按位 OR。 PG_COPYRES_ATTRS 指定复制源结果的属性（列定义）。 PG_COPYRES_TUPLES 指定复制源结果的元组。（这意味着也会复制属性。） PG_COPYRES_NOTICEHOOKS 指定复制源结果的通知挂钩。 PG_COPYRES_EVENTS 指定复制源结果的事件。（但是，与源关联的任何实例数据不会被复制。）事件过程接收 PGEVT_RESULTCOPY 事件。

设置 PGresult 对象的属性。

提供的 attDescs 复制到结果中。如果 attDescs 指针是 NULL 或 numAttributes 小于 1，则忽略请求且函数执行成功。如果 res 已包含属性，则函数将失败。如果函数失败，则返回值为零。如果函数执行成功，则返回值非零。

设置 PGresult 对象的元组字段值。

根据需要，函数将自动扩展结果的内部元组数组。但是， tup_num 参数必须小于或等于 PQntuples ，这意味着此函数一次只能扩展元组数组的一个元组。但是，可以按任何顺序修改任何现有元组的任何字段。如果 field_num 的值已经存在，它将被覆盖。如果 len 为 -1 或 value 为 NULL ，字段值将被设置为 SQL null 值。 value 被复制到结果的私有存储区，因此在函数返回后不再需要它。如果函数失败，返回值为零。如果函数成功，返回值为非零。

为 PGresult 对象分配辅助存储。

使用此函数分配的任何内存都将在清除 res 时释放。如果函数失败，则返回值是 NULL。结果保证与任何类型的数据充分对齐，如同 malloc 所做的那样。

检索为 PGresult 对象分配的字节数。

此值是与 PGresult 对象关联的所有 malloc 请求的总和，即 PQclear 将释放的所有空间。此信息对于管理内存使用情况非常有用。

返回正在使用的 libpq 的版本。

可以在运行时使用此函数的结果来确定 libpq 的当前加载版本中是否提供了特定的功能。例如，此函数可用于确定 PQconnectdb 中提供了哪些连接选项。

结果是将库的主版本号乘以 10000 并加上次版本号。例如，版本 10.1 将返回为 100001，版本 11.0 将返回为 110000。

在主版本 10 之前，PostgreSQL 使用了三部分版本号，其中前两部分一起表示了主版本。对于这些版本， PQlibVersion 对每部分使用两位数；例如，版本 9.1.5 将返回为 90105，版本 9.2.0 将返回为 90200。

因此，为了确定功能兼容性，应用程序应该将 PQlibVersion 的结果除以 100 而不是除以 10000 来确定一个逻辑主版本号。在所有发行版中，只有最后两位数字差别于次要发行版（错误修复发行版）。