34.12. Функции разного назначения
Как всегда, находятся функции, которые не попадают ни в одну из категорий.
PQfreemem
Освобождает память, которую выделила libpq.
void PQfreemem(void *ptr);
Освобождает память, выделенную библиотекой libpq, а именно функциями
PQescapeByteaConn
,PQescapeBytea
,PQunescapeBytea
иPQnotifies
. Особенно важно использовать именно эту функцию, а неfree()
, в Microsoft Windows. Это связано с тем, что выделение памяти в DLL и освобождение её в приложении будет работать, только если флаги многопоточной/однопоточной, выпускаемой/отладочной или статической/динамической сборки для DLL и приложения полностью совпадают. На других платформах эта функция действует так же, как стандартная библиотечная функцияfree()
.PQconninfoFree
Освобождает структуры данных, выделенные функциями
PQconndefaults
иPQconninfoParse
.void PQconninfoFree(PQconninfoOption *connOptions);
Простая функция
PQfreemem
не подойдёт для этого, так как эти структуры содержат ссылки на подчинённые строки.PQencryptPasswordConn
Подготавливает зашифрованную форму пароля PostgreSQL.
char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm);
Эта функция предназначена для клиентских приложений, желающих передавать команды вида
ALTER USER joe PASSWORD 'pwd'
. В такой команде лучше не передавать исходный пароль открытым текстом, так как он может появиться в журналах команд, мониторе активности и т. д. Вместо этого воспользуйтесь данной функцией и переведите пароль в зашифрованную форму.В аргументах
passwd
иuser
задаётся пароль в открытом виде и SQL-имя пользователя, для которого он задаётся. В аргументеalgorithm
задаётся алгоритм для шифрования пароля. В настоящее время поддерживаются алгоритмыmd5
иscram-sha-256
(в качестве альтернативных обозначенийmd5
для совместимости со старыми версиями сервера поддерживаются значенияon
иoff
). Заметьте, что поддержкаscram-sha-256
появилась в PostgreSQL версии 10 и со старыми версиями серверов этот вариант работать не будет. Еслиalgorithm
равенNULL
, эта функция запросит у сервера текущее значение параметра password_encryption. При этом возможна блокировка и отказ при выполнении функции, если текущая транзакция прерывается или если в текущем соединении выполняется другой запрос. Если вы хотите использовать алгоритм по умолчанию для данного сервера, но при этом избежать блокировки, получите значениеpassword_encryption
самостоятельно до вызоваPQencryptPasswordConn
и передайте его в параметреalgorithm
.Эта функция возвращает строку, выделенную функцией
malloc
. Вызывающий код может рассчитывать на то, что эта строка не содержит никаких спецсимволов, требующих экранирования. Закончив работу с ней, освободите память, вызвавPQfreemem
. В случае ошибки эта функция возвращаетNULL
, а соответствующее сообщение помещается в объект соединения.PQencryptPassword
Подготавливает зашифрованную md5 форму пароля PostgreSQL.
char *PQencryptPassword(const char *passwd, const char *user);
PQencryptPassword
— старая, подлежащая ликвидации версияPQencryptPasswordConn
. Отличие состоит в том, что дляPQencryptPassword
не требуется объект соединения, а в качестве алгоритма шифрования всегда используетсяmd5
.PQmakeEmptyPGresult
Конструирует пустой объект
PGresult
с указанным состоянием.PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
Это внутренняя функция libpq, выделяющая память и инициализирующая пустой объект
PGresult
. Эта функция возвращаетNULL
, если не может выделить память. Она сделана экспортируемой, так как некоторые приложения находят полезным создавать объекты результатов (в частности, объекты с состоянием ошибки) самостоятельно. Если вconn
передаётся не null иstatus
указывает на ошибку, вPGresult
копируется текущее сообщение об ошибке для заданного соединения. Также, если вconn
передаётся не null, вPGresult
копируются все процедуры событий, зарегистрированные для этого соединения. (При этом вызовыPGEVT_RESULTCREATE
не выполняются; см. описаниеPQfireResultCreateEvents
.) Заметьте, что в конце для этого объекта следует вызватьPQclear
, как и для объектаPGresult
, возвращённого самой библиотекой libpq.PQfireResultCreateEvents
Вызывает событие
PGEVT_RESULTCREATE
(см. Раздел 34.14) для каждой процедуры событий, зарегистрированной в объектеPGresult
. Возвращает ненулевое значение в случае успеха или ноль в случае ошибки в одной из процедур.int PQfireResultCreateEvents(PGconn *conn, PGresult *res);
Аргумент
conn
передаётся процедурам событий, но непосредственно не используется. Он может быть равенNULL
, если он не нужен процедурам событий.Процедуры событий, уже получившие событие
PGEVT_RESULTCREATE
илиPGEVT_RESULTCOPY
для этого объекта, больше не вызываются.Основная причина отделения этой функции от
PQmakeEmptyPGresult
в том, что часто требуется создать объектPGresult
и наполнить его данными, прежде чем вызывать процедуры событий.PQcopyResult
Создаёт копию объекта
PGresult
. Эта копия никак не связана с исходным результатом и поэтому, когда она становится не нужна, необходимо вызватьPQclear
. Если функция завершается ошибкой, она возвращаетNULL
.PGresult *PQcopyResult(const PGresult *src, int flags);
Создаваемая копия не будет точной. В возвращаемый результат всегда помещается состояние
PGRES_TUPLES_OK
и в него не копируются никакие сообщения об ошибках из исходного объекта. (Однако в него копируется строка состояния команды.) Что ещё в него будет копироваться, определяет аргументflags
, в котором складываются несколько флагов. ФлагPG_COPYRES_ATTRS
включает копирование атрибутов исходного объекта (определений столбцов), а флагPG_COPYRES_TUPLES
включает копирование кортежей из исходного объекта (при этом также копируются и атрибуты.) ФлагPG_COPYRES_NOTICEHOOKS
включает копирование обработчиков замечаний, а флагPG_COPYRES_EVENTS
— событий из исходного объекта результата. (Но любые данные, связанные с экземпляром исходного объекта, не копируются.) Процедуры событий получают событияPGEVT_RESULTCOPY
.PQsetResultAttrs
Устанавливает атрибуты объекта
PGresult
.int PQsetResultAttrs(PGresult *res, int numAttributes, PGresAttDesc *attDescs);
Предоставленная структура
attDescs
копируется в результат. Если указательattDescs
равенNULL
илиnumAttributes
меньше одного, запрос игнорируется и функция выполняется без ошибки. Еслиres
уже содержит атрибуты, функция завершается ошибкой. В случае ошибки функция возвращает ноль, а в обратном случае — ненулевое значение.PQsetvalue
Устанавливает значение поля кортежа в объекте
PGresult
.int PQsetvalue(PGresult *res, int tup_num, int field_num, char *value, int len);
Эта функция автоматически увеличивает внутренний массив кортежей при необходимости. Однако значение
tup_num
должно быть меньше или равноPQntuples
, что означает, что эта функция может увеличивать массив кортежей только на один кортеж. Но в существующем кортеже любые поля могут изменяться в любом порядке. Если значение в поле с номеромfield_num
уже существует, оно будет перезаписано. Еслиlen
равно -1 илиvalue
равноNULL
, в поле будет записано значение SQL NULL. Устанавливаемое значение (value
) копируется в закрытую область объекта результата, так что от него можно избавиться после завершения функции. Если функция завершается ошибкой, она возвращает ноль, а в обратном случае — ненулевое значение.PQresultAlloc
Выделяет подчинённую область памяти для объекта
PGresult
.void *PQresultAlloc(PGresult *res, size_t nBytes);
Любая память, выделенная этой функцией, будет освобождена при очистке объекта
res
. В случае ошибки эта функция возвращаетNULL
. Результат гарантированно выравнивается должным образом для любого типа данных, как и приmalloc
.PQresultMemorySize
Выдаёт объём памяти (в байтах), выделенной для объекта
PGresult
.size_t PQresultMemorySize(const PGresult *res);
Этот объём равен сумме размеров всех запросов
malloc
, связанных с данным объектомPGresult
, то есть это общий объём памяти, который будет освобождён функциейPQclear
. Данная информация может быть полезна для управления потреблением памяти.PQlibVersion
Возвращает версию используемой библиотеки libpq.
int PQlibVersion(void);
По результату этой функции можно во время выполнения определить, предоставляется ли определённая функциональность загруженной в данный момент версией libpq. Эта функция может использоваться, например, чтобы понять, какие параметры соединения может принять
PQconnectdb
.Это число формируется в результате умножения номера основной версии библиотеки на 10000 и добавления номера дополнительной версии. Например, для версии 10.1 будет выдано 100001, а для версии 11.0 — 110000.
До версии 10, в PostgreSQL номера версий образовывались из трёх чисел, первые два из которых представляли основную версию. Для таких версий
PQlibVersion
отводит на каждое число по две цифры; например, для версии 9.1.5 будет выдано 90105, а для версии 9.2.0 — 90200.Таким образом, чтобы получить логический номер версии для определения доступности функциональности, приложения должны разделить результат
PQlibVersion
на 100, а не на 10000. Во всех сериях номера дополнительных (корректирующих) выпусков различаются только в двух последних цифрах.Примечание
Эта функция появилась в PostgreSQL версии 9.1, поэтому с её помощью нельзя проверить функциональность предыдущих версий, так как при вызове её будет создана зависимость от версии 9.1 или новее.
F.45. pg_visibility
The pg_visibility
module provides a means for examining the visibility map (VM) and page-level visibility information of a table. It also provides functions to check the integrity of a visibility map and to force it to be rebuilt.
Three different bits are used to store information about page-level visibility. The all-visible bit in the visibility map indicates that every tuple in the corresponding page of the relation is visible to every current and future transaction. The all-frozen bit in the visibility map indicates that every tuple in the page is frozen; that is, no future vacuum will need to modify the page until such time as a tuple is inserted, updated, deleted, or locked on that page. The page header's PD_ALL_VISIBLE
bit has the same meaning as the all-visible bit in the visibility map, but is stored within the data page itself rather than in a separate data structure. These two bits will normally agree, but the page's all-visible bit can sometimes be set while the visibility map bit is clear after a crash recovery. The reported values can also disagree because of a change that occurs after pg_visibility
examines the visibility map and before it examines the data page. Any event that causes data corruption can also cause these bits to disagree.
Functions that display information about PD_ALL_VISIBLE
bits are much more costly than those that only consult the visibility map, because they must read the relation's data blocks rather than only the (much smaller) visibility map. Functions that check the relation's data blocks are similarly expensive.
F.45.1. Functions
pg_visibility_map(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record
Returns the all-visible and all-frozen bits in the visibility map for the given block of the given relation.
pg_visibility(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record
Returns the all-visible and all-frozen bits in the visibility map for the given block of the given relation, plus the
PD_ALL_VISIBLE
bit of that block.pg_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record
Returns the all-visible and all-frozen bits in the visibility map for each block of the given relation.
pg_visibility(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record
Returns the all-visible and all-frozen bits in the visibility map for each block of the given relation, plus the
PD_ALL_VISIBLE
bit of each block.pg_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record
Returns the number of all-visible pages and the number of all-frozen pages in the relation according to the visibility map.
pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid
Returns the TIDs of non-frozen tuples stored in pages marked all-frozen in the visibility map. If this function returns a non-empty set of TIDs, the visibility map is corrupt.
pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid
Returns the TIDs of non-all-visible tuples stored in pages marked all-visible in the visibility map. If this function returns a non-empty set of TIDs, the visibility map is corrupt.
pg_truncate_visibility_map(relation regclass) returns void
Truncates the visibility map for the given relation. This function is useful if you believe that the visibility map for the relation is corrupt and wish to force rebuilding it. The first
VACUUM
executed on the given relation after this function is executed will scan every page in the relation and rebuild the visibility map. (Until that is done, queries will treat the visibility map as containing all zeroes.)
By default, these functions are executable only by superusers and members of the pg_stat_scan_tables
role, with the exception of pg_truncate_visibility_map(relation regclass)
which can only be executed by superusers.
F.45.2. Author
Robert Haas <rhaas@postgresql.org>