9.26. Системные информационные функции и операторы

В Таблице 9.66 перечислен ряд функций, предназначенных для получения информации о текущем сеансе и системе.

В дополнение к перечисленным здесь функциям существуют также функции, связанные с подсистемой статистики, которые тоже предоставляют системную информацию. Подробнее они рассматриваются в Подразделе 28.2.2.

Таблица 9.66. Функции получения информации о сеансе

Функция

Описание

current_catalogname

current_database () → name

Выдаёт имя текущей базы данных. (В стандарте SQL базы данных называются «каталогами», поэтому стандарту соответствует написание current_catalog.)

current_query () → text

Выдаёт текст запроса, выполняемого в данный момент, в том виде, в каком его передал клиент (может состоять из нескольких операторов).

current_rolename

Аналог current_user.

current_schemaname

current_schema () → name

Выдаёт имя первой схемы в пути поиска (или значение NULL, если путь поиска пустой). В эту схему будут добавляться таблицы и другие объекты, при создании которых схема не указывается явно.

current_schemas ( include_implicit boolean ) → name[]

Выдаёт массив имён всех схем, в настоящее время представленных в действующем пути поиска, по порядку их приоритета. (Элементы текущего значения search_path, которым не соответствуют существующие схемы, опускаются). Если логический аргумент равен true, в результат включаются системные схемы, неявно просматриваемые при поиске, как например, pg_catalog.

current_username

Выдаёт имя пользователя в текущем контексте выполнения.

inet_client_addr () → inet

Выдаёт IP-адрес текущего клиента либо NULL, если текущее соединение установлено через Unix-сокет.

inet_client_port () → integer

Выдаёт номер TCP-порта текущего клиента либо NULL, если текущее подключение установлено через Unix-сокет.

inet_server_addr () → inet

Выдаёт IP-адрес, через который сервер принял текущее подключение, либо NULL, если текущее подключение установлено через Unix-сокет.

inet_server_port () → integer

Выдаёт номер TCP-порта, через который сервер принял текущее подключение, либо NULL, если текущее подключение установлено через Unix-сокет.

pg_backend_pid () → integer

Выдаёт идентификатор серверного процесса, обслуживающего текущий сеанс.

pg_blocking_pids ( integer ) → integer[]

Выдаёт массив с идентификаторами процессов сеансов, которые блокируют серверный процесс с указанным идентификатором, либо пустой массив, если указанный серверный процесс не найден или не заблокирован.

Один серверный процесс блокирует другой, если он либо удерживает блокировку, конфликтующую с блокировкой, запрашиваемой вторым (жёсткая блокировка), либо ожидает блокировку, которая вызвала бы конфликт с запросом блокировки заблокированного процесса и находится перед ней в очереди ожидания (мягкая блокировка). При распараллеливании запросов эта функция всегда выдаёт видимые клиентом идентификаторы процессов (то есть, результаты pg_backend_pid), даже если фактическая блокировка удерживается или ожидается дочерним рабочим процессом. Вследствие этого в результатах могут оказаться дублирующиеся PID. Также заметьте, что когда конфликтующую блокировку удерживает подготовленная транзакция, в выводе этой функции она будет представлена нулевым ID процесса.

Частые вызовы этой функции могут отразиться на производительности базы данных, так как ей нужен монопольный доступ к общему состоянию менеджера блокировок, пусть и на короткое время.

pg_conf_load_time () → timestamp with time zone

Выдаёт время, когда в последний раз сервер загружал файлы конфигурации. (Если текущий сеанс начался раньше, она возвращает время, когда эти файлы были перезагружены для данного сеанса, так что в разных сеансах это значение может немного различаться. В противном случае это будет время, когда файлы конфигурации считал главный процесс.)

pg_current_logfile ( [text] ) → text

Выдаёт путь к файлу журнала, в настоящее время используемому сборщиком сообщений. Этот путь состоит из пути каталога log_directory и имени конкретного файла. Если сборщик сообщений отключён, выдаётся значение NULL. Если ведутся несколько журналов в разных форматах, при вызове функции pg_current_logfile без аргументов возвращается путь первого существующего файла следующего формата (в порядке приоритета): stderr, csvlog, jsonlog. Если файл журнала в этих форматах отсутствует, выдаётся NULL. Чтобы запросить информацию о файле в определённом формате, передайте csvlog, jsonlog или stderr в качестве значения необязательного параметра типа text. Если запрошенный формат не включён в log_destination, результатом будет NULL. Результат функции отражает содержимое файла current_logfiles.

pg_my_temp_schema () → oid

Выдаёт OID временной схемы текущего сеанса или 0, если такой схемы нет (в рамках сеанса не создавались временные таблицы).

pg_is_other_temp_schema ( oid ) → boolean

Выдаёт true, если заданный OID относится к временной схеме другого сеанса. (Это может быть полезно, например для исключения временных таблиц других сеансов из общего списка при просмотре таблиц базы данных.)

pg_jit_available () → boolean

Выдаёт true, если в данном сеансе доступна JIT-компиляция (см. Главу 32) и параметр конфигурации jit включён.

pg_listening_channels () → setof text

Выдаёт список имён каналов асинхронных уведомлений, по которым текущий сеанс принимает сигналы.

pg_notification_queue_usage () → double precision

Выдаёт долю (0–1) максимального размера очереди асинхронных уведомлений, в настоящее время занятую уведомлениями, ожидающими обработки. За дополнительными сведениями обратитесь к LISTEN и NOTIFY.

pg_postmaster_start_time () → timestamp with time zone

Выдаёт время, когда был запущен сервер.

pg_safe_snapshot_blocking_pids ( integer ) → integer[]

Выдаёт массив с идентификаторами процессов сеансов, которые блокируют серверный процесс с указанным идентификатором, не давая ему получить безопасный снимок, либо выдаёт пустой массив, если такой серверный процесс не найден или он не заблокирован.

Сеанс, выполняющий транзакцию уровня SERIALIZABLE, блокирует транзакцию SERIALIZABLE READ ONLY DEFERRABLE, не давая ей получить снимок, пока она не определит, что можно безопасно избежать установления предикатных блокировок. За дополнительными сведениями о сериализуемых и откладываемых транзакциях обратитесь к Подразделу 13.2.3.

Частые вызовы этой функции могут отразиться на производительности сервера, так как ей нужен доступ к общему состоянию менеджера предикатных блокировок, пусть и на короткое время.

pg_trigger_depth () → integer

Выдаёт текущий уровень вложенности в триггерах PostgreSQL (0, если эта функция вызывается не из тела триггера, непосредственно или косвенно).

session_username

Выдаёт имя пользователя сеанса.

username

Аналог current_user.

version () → text

Выдаёт текстовую строку, описывающую версию сервера PostgreSQL. Эту информацию также можно получить из переменной server_version или, в более машинно-ориентированном формате, из переменной server_version_num. При разработке программ следует использовать функцию server_version_num (появившуюся в версии 8.2) или PQserverVersion, а не разбирать текстовую версию.


Примечание

Функции current_catalog, current_role, current_schema, current_user, session_user и user имеют особый синтаксический статус в SQL: они должны вызываться без скобок после имени. PostgreSQL позволяет добавить скобки в вызове current_schema, но не других функций.

Функция session_user обычно возвращает имя пользователя, установившего текущее соединение с базой данных, но суперпользователи могут изменить это имя, выполнив команду SET SESSION AUTHORIZATION. Функция current_user возвращает идентификатор пользователя, по которому будут проверяться его права. Обычно это тот же пользователь, что и пользователь сеанса, но его можно сменить с помощью SET ROLE. Этот идентификатор также меняется при выполнении функций с атрибутом SECURITY DEFINER. На языке Unix пользователь сеанса называется «реальным», а текущий — «эффективным». Имена current_role и user являются синонимами current_user. (В стандарте SQL current_role и current_user имеют разное значение, но в PostgreSQL они не различаются, так как пользователи и роли объединены в единую сущность.)

В Таблице 9.67 показаны функции, позволяющие программно проверить права доступа к объектам. (Подробнее о правах рассказывается в Разделе 5.7.) Этим функциям в качестве идентификатора пользователя, для которого запрашиваются права, можно передать его имя или OID (pg_authid.oid), а также можно передать public (это будет указывать на псевдороль PUBLIC). Кроме того, аргумент user можно полностью опустить, тогда будет подразумеваться current_user. Объект, права для доступа к которому запрашиваются, также можно задать по имени или по OID. Когда указывается имя объекта, его можно дополнить именем схемы, если это уместно. Запрашиваемое право записывается текстовой строкой, которая должна задавать одно из прав доступа, соответствующих типу объекта (например, SELECT). Дополнительно к названию права можно добавить WITH GRANT OPTION и проверить, разрешено ли пользователю передавать это право другим. Кроме того, в одном параметре можно перечислить несколько прав через запятую, и тогда функция возвратит true, если пользователь имеет какие-либо из них. (Регистр в названии прав не имеет значения, а между ними (но не внутри) разрешены пробельные символы.) Пара примеров:

SELECT has_table_privilege('myschema.mytable', 'select');
SELECT has_table_privilege('joe', 'mytable',
  'INSERT, SELECT WITH GRANT OPTION');

Таблица 9.67. Функции для проверки прав доступа

Функция

Описание

has_any_column_privilege ( [user name или oid, ] table text или oid, privilege text ) → boolean

Имеет ли пользователь указанное право для какого-либо столбца таблицы? Ответ положительный, когда он имеет это право для всей таблицы или ему дано соответствующее право на уровне столбцов хотя бы для одного столбца. Возможные права: SELECT, INSERT, UPDATE и REFERENCES.

has_column_privilege ( [user name или oid, ] table text или oid, column text или smallint, privilege text ) → boolean

Имеет ли пользователь указанное право для заданного столбца таблицы? Ответ положительный, когда он имеет это право для всей таблицы или ему дано соответствующее право на уровне столбца. Столбец можно задать по имени или номеру атрибута (pg_attribute.attnum). Возможные права: SELECT, INSERT, UPDATE и REFERENCES.

has_database_privilege ( [user name или oid, ] database text или oid, privilege text ) → boolean

Имеет ли пользователь указанное право в базе данных? Возможные права: CREATE, CONNECT, TEMPORARY и TEMP (синоним TEMPORARY).

has_foreign_data_wrapper_privilege ( [user name или oid, ] fdw text или oid, privilege text ) → boolean

Имеет ли пользователь право для обёртки сторонних данных? На данный момент возможно только одно право: USAGE.

has_function_privilege ( [user name или oid, ] function text или oid, privilege text ) → boolean

Имеет ли пользователь право для функции? Возможно единственное право: EXECUTE.

При указании функции по имени, а не по OID, допускаются те же входные значения, что и для типа regprocedure (см. Раздел 8.19). Например:

SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');

has_language_privilege ( [user name или oid, ] language text или oid, privilege text ) → boolean

Имеет ли пользователь право для языка? Возможно единственное право: USAGE.

has_parameter_privilege ( [user name или oid, ] parameter text, privilege text ) → boolean

Имеет ли пользователь право для параметра конфигурации? Регистр в имени параметра игнорируется. Возможные права: SET и ALTER SYSTEM.

has_schema_privilege ( [user name или oid, ] schema text или oid, privilege text ) → boolean

Имеет ли пользователь право для схемы? Возможные права: CREATE и USAGE.

has_sequence_privilege ( [user name или oid, ] sequence text или oid, privilege text ) → boolean

Имеет ли пользователь право для последовательности? Возможные права: USAGE, SELECT и UPDATE.

has_server_privilege ( [user name или oid, ] server text или oid, privilege text ) → boolean

Имеет ли пользователь право для стороннего сервера? На данный момент возможно только одно право: USAGE.

has_table_privilege ( [user name или oid, ] table text или oid, privilege text ) → boolean

Имеет ли пользователь право для таблицы? Возможные права: SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES и TRIGGER.

has_tablespace_privilege ( [user name или oid, ] tablespace text или oid, privilege text ) → boolean

Имеет ли пользователь право для табличного пространства? Возможно единственное право: CREATE.

has_type_privilege ( [user name или oid, ] type text или oid, privilege text ) → boolean

Имеет ли пользователь право для типа данных? Возможно единственное право: USAGE. При указании типа по имени, а не по OID, допускаются те же входные значения, что и для типа данных regtype (см. Раздел 8.19).

pg_has_role ( [user name или oid, ] role text или oid, privilege text ) → boolean

Имеет ли пользователь право для роли? Возможные права: MEMBER и USAGE. Под MEMBER подразумевается непосредственное или косвенное членство в роли (то есть право выполнить SET ROLE), а USAGE означает, что пользователь получает права этой роли автоматически, не выполняя SET ROLE. Эта функция не поддерживает значение public в качестве user, так как псевдороль PUBLIC не может быть членом обычных ролей.

row_security_active ( table text или oid ) → boolean

Действует ли защита на уровне строк для заданной таблицы в контексте текущего пользователя в текущем окружении?


В Таблице 9.68 показаны операторы, предназначенные для работы с типом aclitem, который представляет в системном каталоге права доступа. О содержании значений этого типа рассказывается в Разделе 5.7.

Таблица 9.68. Операторы для типа aclitem

Оператор

Описание

Пример(ы)

aclitem = aclitemboolean

Значения aclitem равны? (Заметьте, что для типа aclitem не определён обычный набор операторов сравнения, поддерживается только проверка равенства. Массивы aclitem, в свою очередь, также могут сравниваться только на равенство.)

'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitemf

aclitem[] @> aclitemboolean

Содержит ли массив заданное право? (Ответ положительный, если в массиве есть запись, соответствующая правообладателю и праводателю из aclitem и содержащая как минимум указанный набор прав.)

'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitemt

aclitem[] ~ aclitemboolean

Это устаревший синоним для @>.

'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitemt


В Таблице 9.69 приведены дополнительные функции, предназначенные для работы с типом aclitem.

Таблица 9.69. Функции для типа aclitem

Функция

Описание

acldefault ( type "char", ownerId oid ) → aclitem[]

Выдаёт массив с элементами aclitem, содержащий действующий по умолчанию набор прав доступа для объектов типа type, принадлежащих роли ownerId. Результат показывает, какие права доступа подразумеваются, когда список ACL определённого объекта пуст. (Права доступа, действующие по умолчанию, описываются в Разделе 5.7.) Параметр type может принимать одно из следующих значений: 'c' —столбец (COLUMN), 'r' — таблица или подобный таблице объект (TABLE), 's' — последовательность (SEQUENCE), 'd' — база данных (DATABASE), 'f' — функция (FUNCTION) или процедура (PROCEDURE), 'l' — язык (LANGUAGE), 'L' — большой объект (LARGE OBJECT), 'n' — схема (SCHEMA), 'p' — параметр (PARAMETER), 't' — табличное пространство (TABLESPACE), 'F' — обёртка сторонних данных (FOREIGN DATA WRAPPER), 'S' — сторонний сервер (FOREIGN SERVER) и 'T' — тип (TYPE) или домен (DOMAIN).

aclexplode ( aclitem[] ) → setof record ( grantor oid, grantee oid, privilege_type text, is_grantable boolean )

Возвращает массив aclitem в виде набора табличных строк. Если праводателем является псевдороль PUBLIC, она представляется нулём в столбце grantee. Назначенные права представляются ключевыми словами SELECT, INSERT и т. д. Заметьте, что каждое право выводится в отдельной строке, так что в столбце privilege_type содержится только одно ключевое слово.

makeaclitem ( grantee oid, grantor oid, privileges text, is_grantable boolean ) → aclitem

Конструирует значение aclitem с заданными свойствами.


В Таблице 9.70 показаны функции, определяющие видимость объекта с текущим путём поиска схем. К примеру, таблица считается видимой, если содержащая её схема включена в путь поиска и нет другой таблицы с тем же именем, которая была бы найдена в этом пути раньше. Другими словами, к этой таблице можно будет обратиться просто по её имени, без явного указания схемы. Просмотреть список всех видимых таблиц можно так:

SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);

Объект, представляющий функцию и оператор, считаются видимым в пути поиска, если при просмотре пути не находится предшествующий ему другой объект с тем же именем и типами аргументов. Для семейств и классов операторов помимо имени объекта во внимание принимается также связанный метод доступа к индексу.

Таблица 9.70. Функции для определения видимости

Функция

Описание

pg_collation_is_visible ( collation oid ) → boolean

Видимо ли правило сортировки в пути поиска?

pg_conversion_is_visible ( conversion oid ) → boolean

Видимо ли преобразование в пути поиска?

pg_function_is_visible ( function oid ) → boolean

Видима ли функция в пути поиска? (Также работает для процедур и агрегатных функций.)

pg_opclass_is_visible ( opclass oid ) → boolean

Виден ли класс операторов в пути поиска?

pg_operator_is_visible ( operator oid ) → boolean

Видим ли оператор в пути поиска?

pg_opfamily_is_visible ( opclass oid ) → boolean

Видимо ли семейство операторов в пути поиска?

pg_statistics_obj_is_visible ( stat oid ) → boolean

Видим ли объект статистики в пути поиска?

pg_table_is_visible ( table oid ) → boolean

Видима ли таблица в пути поиска? (Эта проверка работает со всеми типами отношений, включая представления, матпредставления, индексы, последовательности и сторонние таблицы.)

pg_ts_config_is_visible ( config oid ) → boolean

Видима ли конфигурация текстового поиска?

pg_ts_dict_is_visible ( dict oid ) → boolean

Видим ли словарь текстового поиска?

pg_ts_parser_is_visible ( parser oid ) → boolean

Видим ли анализатор текстового поиска?

pg_ts_template_is_visible ( template oid ) → boolean

Видим ли шаблон текстового поиска?

pg_type_is_visible ( type oid ) → boolean

Видим ли тип (или домен) в пути поиска?


Всем этим функциям должен передаваться OID проверяемого объекта. Если вы хотите проверить объект по имени, удобнее использовать типы-псевдонимы OID (regclass, regtype, regprocedure, regoperator, regconfig или regdictionary), например:

SELECT pg_type_is_visible('myschema.widget'::regtype);

Заметьте, что проверять таким способом имена без указания схемы не имеет большого смысла — если имя удастся распознать, значит и объект будет видимым.

В Таблице 9.71 перечислены функции, извлекающие информацию из системных каталогов.

Таблица 9.71. Функции для обращения к системным каталогам

Функция

Описание

format_type ( type oid, typemod integer ) → text

Выдаёт в формате SQL имя типа данных, определяемого по OID и, возможно, модификатору типа. Если модификатор неизвестен, вместо него можно передать NULL.

pg_char_to_encoding ( encoding name ) → integer

Преобразует предоставленное имя кодировки в целое число, представляющее внутренний идентификатор, используемый в некоторых таблицах системного каталога. Возвращает -1, если указано неизвестное имя кодировки.

pg_encoding_to_char ( encoding integer ) → name

Преобразует целое число, используемое в качестве внутреннего идентификатора кодировки в некоторых таблицах системного каталога, в понятное имя. Возвращает пустую строку, если указан неправильный номер кодировки.

pg_get_catalog_foreign_keys () → setof record ( fktable regclass, fkcols text[], pktable regclass, pkcols text[], is_array boolean, is_opt boolean )

Возвращает набор записей, описывающих отношения внешних ключей, существующие в системных каталогах PostgreSQL. Столбец fktable содержит имя ссылающегося каталога, а столбец fkcols содержит имена ссылающихся столбцов. Точно так же столбец pktable содержит имя целевого каталога, а столбец pkcols содержит имена целевых столбцов. Если столбец is_array содержит значение true, последний ссылающийся столбец является массивом, каждый из элементов которого должен соответствовать некоторой записи в целевом каталоге. Если столбец is_opt содержит значение true, ссылающиеся столбцы могут содержать нули вместо действительной ссылки.

pg_get_constraintdef ( constraint oid [, pretty boolean] ) → text

Восстанавливает команду, создающую ограничение. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.)

pg_get_expr ( expr pg_node_tree, relation oid [, pretty boolean] ) → text

Декомпилирует внутреннюю форму выражений, находящихся в системных каталогах, например, выражений, задающих значения по умолчанию. Если выражение может содержать Vars (переменные), передайте во втором параметре OID отношения, к которому обращается данное выражение; в противном случае достаточно передать 0.

pg_get_functiondef ( func oid ) → text

Восстанавливает команду, создающую функцию или процедуру. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.) В результате выдаётся полноценный оператор CREATE OR REPLACE FUNCTION или CREATE OR REPLACE PROCEDURE.

pg_get_function_arguments ( func oid ) → text

Восстанавливает список аргументов для функции или процедуры в том виде, в каком он должен задаваться в команде CREATE FUNCTION (включая значения по умолчанию).

pg_get_function_identity_arguments ( func oid ) → text

Восстанавливает список аргументов, необходимый для однозначной идентификации функции или процедуры, в том виде, в каком он должен задаваться, например в ALTER FUNCTION. В этом виде значения по умолчанию не указываются.

pg_get_function_result ( func oid ) → text

Восстанавливает для функции предложение RETURNS в том виде, в котором оно должно указываться в команде CREATE FUNCTION. Для процедуры возвращается NULL.

pg_get_indexdef ( index oid [, column integer, pretty boolean] ) → text

Восстанавливает команду, создающую индекс. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.) Если передаётся значение column и оно отлично от нуля, восстанавливается только определение этого столбца.

pg_get_keywords () → setof record ( word text, catcode "char", barelabel boolean, catdesc text, baredesc text )

Выдаёт набор записей, описывающих ключевые слова, которые воспринимает сервер. Столбец word содержит слово, а столбец catcode — код категории: U — не зарезервировано, C — слово, которое может быть именем столбца, T — слово, которое может быть именем типа или функции, R — полностью зарезервированное слово. Столбец barelabel содержит true, если ключевое слово можно использовать в качестве «открытой» метки столбца в списках SELECT, или false, если его можно использовать только после AS. Столбец catdesc содержит описание категории слова, возможно локализованное. Столбец baredesc содержит возможно локализованную строку, описывающую статус метки столбца, содержащего слово.

pg_get_ruledef ( rule oid [, pretty boolean] ) → text

Восстанавливает команду, создающую правило. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.)

pg_get_serial_sequence ( table text, column text ) → text

Выдаёт имя последовательности, связанной со столбцом, либо NULL, если такой последовательности нет. Для столбца идентификации это будет последовательность, созданная для него неявно внутри. Для столбцов, имеющих один из последовательных типов (serial, smallserial, bigserial), это последовательность, созданная объявлением данного столбца. В последнем случае эту связь можно изменить или разорвать, воспользовавшись командой ALTER SEQUENCE OWNED BY. (Возможно, эту функцию стоило назвать pg_get_owned_sequence; её существующее имя отражает тот факт, что изначально она использовалась со столбцами последовательных типов.) В первом параметре функции указывается имя таблицы (возможно, дополненное схемой), а во втором — имя столбца. Так как первый параметр может содержать имя схемы и таблицы, он воспринимается не как идентификатор в кавычках и поэтому по умолчанию приводится к нижнему регистру, тогда как имя столбца во втором параметре воспринимается как заключённое в кавычки и в нём регистр символов сохраняется. Эта функция возвращает имя в виде, пригодном для передачи функциям, работающим с последовательностями (см. Раздел 9.17).

Обычно эта функция применяется для получения текущего значения последовательности для столбца идентификации или последовательного столбца, например так:

SELECT currval(pg_get_serial_sequence('sometable', 'id'));

pg_get_statisticsobjdef ( statobj oid ) → text

Восстанавливает команду, создающую объект расширенной статистики. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.)

pg_get_triggerdef ( trigger oid [, pretty boolean] ) → text

Восстанавливает команду, создающую триггер. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.)

pg_get_userbyid ( role oid ) → name

Выдаёт имя роли по заданному OID.

pg_get_viewdef ( view oid [, pretty boolean] ) → text

Восстанавливает команду SELECT, определяющую представление или матпредставление. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.)

pg_get_viewdef ( view oid, wrap_column integer ) → text

Восстанавливает команду SELECT, определяющую представление или матпредставление. (Текст команды не является изначальным, он восстанавливается путём декомпиляции.) В этой вариации функции всегда применяется визуальное улучшение и длинные строки переносятся, чтобы текст умещался по ширине в заданное число столбцов.

pg_get_viewdef ( view text [, pretty boolean] ) → text

Восстанавливает команду SELECT, определяющую представление или матпредставление, заданное по имени, а не по OID. (Это устаревшая вариация, используйте вместо неё вариацию с OID).

pg_index_column_has_property ( index regclass, column integer, property text ) → boolean

Проверяет, имеет ли столбец индекса заданное свойство. Типичные свойства столбцов описаны в Таблице 9.72. (Заметьте, что расширенные методы доступа могут определять для своих индексов дополнительные свойства.) Если заданное имя свойства не известно или не применимо к конкретному объекту, либо если OID или номер столбца не указывают на существующий объект, эта функция возвращает NULL.

pg_index_has_property ( index regclass, property text ) → boolean

Проверяет, имеет ли индекс заданное свойство. Типичные свойства индексов описаны в Таблице 9.72. (Заметьте, что расширенные методы доступа могут определять для своих индексов дополнительные свойства.) Если заданное имя свойства не известно или не применимо к конкретному объекту, либо если OID не указывает на существующий объект, эта функция возвращает NULL.

pg_indexam_has_property ( am oid, property text ) → boolean

Проверяет, имеет ли метод доступа индекса заданное свойство. Свойства методов доступа описаны в Таблице 9.74. Если заданное имя свойства неизвестно или не применимо к конкретному объекту, либо если OID не указывает на существующий объект, эта функция возвращает NULL.

pg_options_to_table ( options_array text[] ) → setof record ( option_name text, option_value text )

Выдаёт набор параметров хранилища, представленных значением из pg_class.reloptions или pg_attribute.attoptions.

pg_settings_get_flags ( guc text ) → text[]

Возвращает массив флагов, связанных с данным параметром GUC, или NULL, если указанный параметр не существует. Если же он существует, но у него нет флагов для отображения, возвращается пустой массив. Показываются только самые полезные флаги, перечисленные в Таблице 9.75.

pg_tablespace_databases ( tablespace oid ) → setof oid

Выдаёт набор OID баз данных, объекты которых размещены в заданном табличном пространстве. Если эта функция возвращает строки, это означает, что табличное пространство не пустое и удалить его нельзя. Какие именно объекты находятся в табличном пространстве, можно определить, подключаясь к базам данных, OID которых сообщила pg_tablespace_databases, и анализируя их каталоги pg_class.

pg_tablespace_location ( tablespace oid ) → text

Выдаёт путь в файловой системе к местоположению заданного табличного пространства.

pg_typeof ( "any" ) → regtype

Выдаёт OID типа данных для переданного значения. Это может быть полезно для разрешения проблем или динамического создания SQL-запросов. Эта функция объявлена как возвращающая тип regtype, который является псевдонимом типа OID (см. Раздел 8.19); это означает, что значение этого типа можно сравнивать как OID, но выводится оно как название типа.

Пример:

SELECT pg_typeof(33);
 pg_typeof
-----------
 integer

SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
 typlen
--------
      4

COLLATION FOR ( "any" ) → text

Выдаёт имя правила сортировки для переданного значения. Это значение может быть заключено в кавычки и дополнено схемой. Если с выражением аргумента не связано правило сортировки, возвращается NULL. Если же правила сортировки не применимы для типа аргумента, происходит ошибка.

Пример:

SELECT collation for (description) FROM pg_description LIMIT 1;
 pg_collation_for
------------------
 "default"

SELECT collation for ('foo' COLLATE "de_DE");
 pg_collation_for
------------------
 "de_DE"

to_regclass ( text ) → regclass

Переводит в OID текстовое имя отношения. Подобный результат можно получить, приведя строку с именем к типу regclass (см. Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regcollation ( text ) → regcollation

Переводит в OID текстовое имя правила сортировки. Подобный результат можно получить, приведя строку с именем к типу regcollation (см. Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regnamespace ( text ) → regnamespace

Переводит в OID текстовое имя схемы. Подобный результат можно получить, приведя строку с именем к типу regnamespace (см. Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regoper ( text ) → regoper

Переводит в OID текстовое имя оператора. Подобный результат можно получить, приведя строку с именем к типу regoper (см. Раздел 8.19); однако если имя не будет распознано или окажется неоднозначным, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regoperator ( text ) → regoperator

Переводит в OID текстовое имя оператора с указанием типов параметров. Подобный результат можно получить, приведя строку с именем к типу regoperator (см Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regproc ( text ) → regproc

Переводит в OID текстовое имя функции или процедуры. Подобный результат можно получить, приведя строку с именем к типу regoperator (см. Раздел 8.19); однако если имя не будет распознано или окажется неоднозначным, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regprocedure ( text ) → regprocedure

Переводит в OID текстовое имя функции или процедуры с указанием типов аргументов. Подобный результат можно получить, приведя строку с именем к типу regprocedure (см. Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regrole ( text ) → regrole

Переводит в OID текстовое имя роли. Подобный результат можно получить, приведя строку с именем к типу regrole (см. Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.

to_regtype ( text ) → regtype

Переводит в OID текстовое имя типа. Подобный результат можно получить, приведя строку с именем к типу regtype (см. Раздел 8.19); однако если имя не будет распознано, эта функция возвратит NULL, а не выдаст ошибку. Также, в отличие от приведения, данная функция не принимает в качестве входных данных числовой OID.


Многие из функций, восстанавливающих (декомпилирующих) объекты БД, принимают дополнительный флаг pretty, в котором можно передать true для визуального улучшения вывода. При этом будут убраны лишние скобки и добавлены пробельные символы, чтобы текст был более разборчивым. Преобразованный вывод легче читается, но формат по умолчанию с большей вероятностью будет успешно восприниматься будущими версиями PostgreSQL, поэтому для выгрузки содержимого БД рекомендуется избегать использования визуально улучшенного формата. Если параметр pretty равен false, это равнозначно его отсутствию.

Таблица 9.72. Свойства столбца индекса

ИмяОписание
ascСортируется ли столбец по возрастанию при сканировании вперёд?
descСортируется ли столбец по убыванию при сканировании вперёд?
nulls_firstВыдаются ли NULL в начале при сканирования вперёд?
nulls_lastВыдаются ли NULL в конце при сканировании вперёд?
orderableСвязан ли со столбцом некоторый порядок сортировки?
distance_orderableМожет ли столбец сканироваться по порядку оператором «расстояния», например, ORDER BY столбец <-> константа ?
returnableМожет ли значение столбца быть получено при сканировании только индекса?
search_arrayПоддерживает ли столбец внутренними средствами поиск столбец = ANY(массив)?
search_nullsПоддерживает ли столбец поиск IS NULL и IS NOT NULL?

Таблица 9.73. Свойства индекса

ИмяОписание
clusterableМожет ли индекс использоваться в команде CLUSTER?
index_scanПоддерживает ли индекс простое сканирование (не по битовой карте)?
bitmap_scanПоддерживает ли индекс сканирование по битовой карте?
backward_scanМожет ли в процессе сканирования меняться направление (для поддержки перемещения курсора FETCH BACKWARD без необходимости материализации)?

Таблица 9.74. Свойства метода доступа индекса

ИмяОписание
can_orderПоддерживает ли метод доступа ASC, DESC и связанные ключевые слова в CREATE INDEX?
can_uniqueПоддерживает ли метод доступа уникальные индексы?
can_multi_colПоддерживает ли метод доступа индексы по нескольким столбцам?
can_excludeПоддерживает ли метод доступа ограничения-исключения?
can_includeПоддерживает ли метод доступа предложение INCLUDE команды CREATE INDEX?

Таблица 9.75. Флаги параметров GUC

ФлагОписание
EXPLAINПараметры с этим флагом включаются в команды EXPLAIN (SETTINGS).
NO_SHOW_ALLПараметры с этим флагом исключаются из команд SHOW ALL.
NO_RESET_ALLПараметры с этим флагом исключаются из команд RESET ALL.
NOT_IN_SAMPLEПараметры с этим флагом не включаются в postgresql.conf по умолчанию.
RUNTIME_COMPUTEDПараметры с этим флагом вычисляются во время выполнения.

В Таблице 9.76 перечислены функции, связанные с идентификацией и адресацией объектов баз данных.

Таблица 9.76. Функции получения информации и адресации объектов

Функция

Описание

pg_describe_object ( classid oid, objid oid, objsubid integer ) → text

Выдаёт текстовое описание объекта БД, идентифицируемого по OID каталога, OID объекта и ID подобъекта (например, номер столбца в таблице; ID подобъекта равен нулю для объекта в целом). Это описание предназначено для человека и может переводиться, в зависимости от конфигурации сервера. Данная функция в особенности полезна, когда требуется узнать, что за объект хранится в каталоге pg_depend. Эта функция возвращает значение NULL для неопределённых объектов.

pg_identify_object ( classid oid, objid oid, objsubid integer ) → record ( type text, schema text, name text, identity text )

Выдаёт запись, содержащую достаточно информации для однозначной идентификации объекта БД по OID каталога, OID объекта и ID подобъекта. Эта информация предназначена для машины и поэтому никогда не переводится. Столбец type содержит тип объекта БД; schema — имя схемы, к которой относится объект (либо NULL для объектов, не относящихся к схемам); name — имя объекта, при необходимости в кавычках, которое присутствует, только если оно (возможно, вместе со схемой) однозначно идентифицирует объект (в противном случае NULL); identity — полный идентификатор объекта, точный формат которого зависит от типа объекта, а каждая его часть дополняется схемой и заключается в кавычки, если требуется. Для неопределённых объектов эти столбцы содержат значение NULL.

pg_identify_object_as_address ( classid oid, objid oid, objsubid integer ) → record ( type text, object_names text[], object_args text[] )

Выдаёт запись, содержащую достаточно информации для однозначной идентификации объекта БД по OID каталога, OID объекта и ID подобъекта. Выдаваемая информация не зависит от текущего сервера, то есть по ней можно идентифицировать одноимённый объект на другом сервере. Поле type содержит тип объекта БД, а object_names и object_args — текстовые массивы, в совокупности формирующие ссылку на объект. Эти три значения можно передать функции pg_get_object_address, чтобы получить внутренний адрес объекта.

pg_get_object_address ( type text, object_names text[], object_args text[] ) → record ( classid oid, objid oid, objsubid integer )

Выдаёт запись, содержащую достаточно информации для уникальной идентификации объекта БД по коду типа и массивам имён и аргументов. В ней возвращаются значения, которые используются в системных каталогах, например pg_depend, и могут передаваться в другие системные функции, например pg_describe_object или pg_identify_object. Поле classid содержит OID системного каталога, к которому относится объект; objid — OID самого объекта, а objsubid — идентификатор подобъекта или 0 в случае его отсутствия. Эта функция является обратной к pg_identify_object_as_address. Для неопределённых объектов эти поля содержат значение NULL.


Функции, перечисленные в Таблице 9.77, извлекают комментарии, заданные для объектов с помощью команды COMMENT. Если найти комментарий для заданных параметров не удаётся, они возвращают NULL.

Таблица 9.77. Функции получения комментариев

Функция

Описание

col_description ( table oid, column integer ) → text

Выдаёт комментарий для столбца с заданным номером в таблице с указанным OID. (obj_description нельзя использовать для столбцов таблицы, так столбцы не имеют собственных OID.)

obj_description ( object oid, catalog name ) → text

Выдаёт комментарий для объекта, имеющего заданный OID и находящегося в указанном системном каталоге. Например, в результате вызова obj_description(123456,'pg_class') будет получен комментарий для таблицы с OID 123456.

obj_description ( object oid ) → text

Выдаёт комментарий для объекта, заданного только по OID. Эта вариация считается устаревшей, так как нет гарантии, что OID будет уникальным в разных системных каталогах, и поэтому может быть получен неправильный комментарий.

shobj_description ( object oid, catalog name ) → text

Выдаёт комментарий для общего объекта баз данных, имеющего заданный OID и находящегося в указанном системном каталоге. Эта функция аналогична obj_description, за исключением того, что она извлекает комментарий для общих объектов (то есть, баз данных, ролей и табличных пространств). Некоторые системные каталоги являются глобальными для всех баз данных в кластере и описания объектов в них также хранятся глобально.


Функции, показанные в Таблице 9.78, выдают информацию о транзакциях сервера в виде, подходящем для экспорта. В основном эти функции используются, чтобы определить, какие транзакции были зафиксированы между двумя снимками состояния.

Таблица 9.78. Функции получения информации об идентификаторах транзакций и снимках состояния

Функция

Описание

pg_current_xact_id () → xid8

Выдаёт идентификатор текущей транзакции. Если у текущей транзакции ещё нет идентификатора (она не успела выполнить какие-либо изменения в базе), он будет ей назначен.

pg_current_xact_id_if_assigned () → xid8

Выдаёт идентификатор текущей транзакции или NULL, если она ещё не имеет идентификатора. (Если транзакция может оставаться только читающей, лучше использовать эту вариацию, чтобы избежать излишнего потребления XID.)

pg_xact_status ( xid8 ) → text

Выдаёт состояние фиксации транзакции. Результатом будет одно из значений: in progress (выполняется), committed (зафиксирована) и aborted (прервана), если только транзакция не настолько давняя, чтобы система удалила информацию о её состоянии. Если же упоминаний о транзакции в системе не осталось и информация о её фиксации потеряна, эта функция возвращает NULL. Приложения могут использовать эту функцию, например, чтобы определить, была ли транзакция зафиксирована или прервана, после потери подключения к серверу в процессе выполнения COMMIT. Заметьте, что для подготовленных транзакций возвращается состояние in progress; приложения должны проверять pg_prepared_xacts, если им нужно определить, является ли транзакция с заданным ID подготовленной.

pg_current_snapshot () → pg_snapshot

Возвращает текущий снимок состояния — структуру данных, показывающую, какие транзакции выполняются в момент снимка.

pg_snapshot_xip ( pg_snapshot ) → setof xid8

Выдаёт набор идентификаторов выполняющихся транзакций, содержащихся в снимке.

pg_snapshot_xmax ( pg_snapshot ) → xid8

Выдаёт значение xmax для заданного снимка.

pg_snapshot_xmin ( pg_snapshot ) → xid8

Выдаёт xmin для заданного снимка.

pg_visible_in_snapshot ( xid8, pg_snapshot ) → boolean

Видна ли транзакция с указанным идентификатором в данном снимке (то есть, была ли она завершена до момента получения снимка)? Заметьте, что эта функция не выдаст правильный ответ, если ей передать идентификатор подтранзакции.


Внутренний тип идентификаторов транзакций, xid, имеет размер 32 бита и значения в нём повторяются через каждые 4 миллиарда транзакций. Однако функции, показанные в Таблице 9.78 используют 64-битный тип xid8, значения которого не повторяются на протяжении всей жизни сервера и могут быть приведены к типу xid, если требуется. Тип данных pg_snapshot содержит информацию о видимости транзакций в определённый момент времени. Его компоненты описаны в Таблице 9.79. В текстовом виде pg_snapshot представляется как xmin:xmax:список_xip. Например, запись 10:20:10,14,15 обозначает xmin=10, xmax=20, xip_list=10, 14, 15.

Таблица 9.79. Состав информации о снимке

ИмяОписание
xminМинимальный идентификатор транзакции среди всех активных. Все транзакции, идентификаторы которых меньше xmin, уже либо зафиксированы и видимы, либо отменены и «мертвы».
xmaxИдентификатор на один больше идентификатора последней завершённой транзакции. Все транзакции, идентификаторы которых больше или равны xmax, на момент получения снимка ещё не завершены и не являются видимыми.
xip_listТранзакции, выполняющиеся в момент получения снимка. Транзакции с такими идентификаторами, для которых xmin <= ид < xmax, не попавшие в этот список, были уже завершены на момент получения снимка, и поэтому либо видимы, либо «мертвы», в зависимости от варианта завершения. Идентификаторы подтранзакций в этот список не включаются.

До 13 версии в PostgreSQL отсутствовал тип xid8, поэтому предлагались вариации этих функций, в которых 64-битные XID представлялись в типе bigint, а для информации о снимке использовался отдельный тип txid_snapshot. В названиях этих старых функций фигурирует txid. Они по-прежнему поддерживаются для обратной совместимости, но могут быть удалены в будущем. См. Таблицу 9.80.

Таблица 9.80. Устаревшие функции получения информации об идентификаторах транзакций и снимках состояния

Функция

Описание

txid_current () → bigint

См. pg_current_xact_id().

txid_current_if_assigned () → bigint

См. pg_current_xact_id_if_assigned().

txid_current_snapshot () → txid_snapshot

См. pg_current_snapshot().

txid_snapshot_xip ( txid_snapshot ) → setof bigint

См. pg_snapshot_xip().

txid_snapshot_xmax ( txid_snapshot ) → bigint

См. pg_snapshot_xmax().

txid_snapshot_xmin ( txid_snapshot ) → bigint

См. pg_snapshot_xmin().

txid_visible_in_snapshot ( bigint, txid_snapshot ) → boolean

См. pg_visible_in_snapshot().

txid_status ( bigint ) → text

См. pg_xact_status().


Функции, показанные в Таблице 9.81, выдают информацию о времени фиксирования уже завершённых транзакций. Полезным результат этих функций будет, только когда включён параметр конфигурации track_commit_timestamp и только для транзакций, зафиксированных после его включения.

Таблица 9.81. Функции получения информации о фиксации транзакций

Функция

Описание

pg_xact_commit_timestamp ( xid ) → timestamp with time zone

Выдаёт время фиксации транзакции.

pg_xact_commit_timestamp_origin ( xid ) → record ( timestamp timestamp with time zone, roident oid)

Выдаёт время фиксации и источник репликации транзакции.

pg_last_committed_xact () → record ( xid xid, timestamp timestamp with time zone, roident oid )

Выдаёт идентификатор, время фиксации и источник репликации транзакции, зафиксированной последней.


Функции, показанные в Таблице 9.82, выдают информацию, записываемую во время initdb, например, версию каталога. Они также выводят сведения о журнале предзаписи и контрольных точках. Эта информация относится ко всему кластеру, а не к отдельной базе. Данные функции выдают практически ту же информацию, и из того же источника, что и pg_controldata.

Таблица 9.82. Функции управления данными

Функция

Описание

pg_control_checkpoint () → record

Выдаёт информацию о текущем состоянии контрольных точек, показанную в Таблице 9.83.

pg_control_system () → record

Выдаёт информацию о текущем состоянии управляющего файла, показанную в Таблице 9.84.

pg_control_init () → record

Выдаёт информацию о состоянии инициализации кластера, показанную в Таблице 9.85.

pg_control_recovery () → record

Выдаёт информацию о состоянии восстановления, как показано в Таблице 9.86.


Таблица 9.83. Столбцы результата pg_control_checkpoint

Имя столбцаТип данных
checkpoint_lsnpg_lsn
redo_lsnpg_lsn
redo_wal_filetext
timeline_idinteger
prev_timeline_idinteger
full_page_writesboolean
next_xidtext
next_oidoid
next_multixact_idxid
next_multi_offsetxid
oldest_xidxid
oldest_xid_dbidoid
oldest_active_xidxid
oldest_multi_xidxid
oldest_multi_dbidoid
oldest_commit_ts_xidxid
newest_commit_ts_xidxid
checkpoint_timetimestamp with time zone

Таблица 9.84. Столбцы результата pg_control_system

Имя столбцаТип данных
pg_control_versioninteger
catalog_version_nointeger
system_identifierbigint
pg_control_last_modifiedtimestamp with time zone

Таблица 9.85. Столбцы результата pg_control_init

Имя столбцаТип данных
max_data_alignmentinteger
database_block_sizeinteger
blocks_per_segmentinteger
wal_block_sizeinteger
bytes_per_wal_segmentinteger
max_identifier_lengthinteger
max_index_columnsinteger
max_toast_chunk_sizeinteger
large_object_chunk_sizeinteger
float8_pass_by_valueboolean
data_page_checksum_versioninteger

Таблица 9.86. Столбцы результата pg_control_recovery

Имя столбцаТип данных
min_recovery_end_lsnpg_lsn
min_recovery_end_timelineinteger
backup_start_lsnpg_lsn
backup_end_lsnpg_lsn
end_of_backup_record_requiredboolean