9.26. Функции для системного администрирования

Функции, описанные в этом разделе, предназначены для контроля и управления сервером Postgres Pro.

9.26.1. Функции для управления конфигурацией

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

Таблица 9.77. Функции для управления конфигурацией

ИмяТип результатаОписание
current_setting(setting_name [, missing_ok ])textполучает текущее значение параметра
set_config(setting_name, new_value, is_local)textустанавливает новое значение параметра и возвращает его

Функция current_setting выдаёт текущее значение параметра setting_name. Она соответствует стандартной SQL-команде SHOW. Пример использования:

SELECT current_setting('datestyle');

 current_setting
-----------------
 ISO, MDY
(1 row)

Если параметра с именем setting_name нет, функция current_setting выдаёт ошибку, если только дополнительно не передан параметр missing_ok со значением true.

set_config устанавливает для параметра setting_name значение new_value. Если параметр is_local равен true, новое значение будет действовать только в рамках текущей транзакции. Чтобы это значение действовало на протяжении текущего сеанса, ему нужно присвоить false. Эта функция соответствует SQL-команде SET. Пример использования:

SELECT set_config('log_statement_stats', 'off', false);

 set_config
------------
 off
(1 row)

9.26.2. Функции для передачи сигналов серверу

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

Таблица 9.78. Функции для передачи сигналов серверу

ИмяТип результатаОписание
pg_cancel_backend(pid int)booleanОтменяет текущий запрос в обслуживающем процессе. Это действие разрешается и ролям, являющимся членами роли, обслуживающий процесс которой затрагивается, и ролям, которым дано право pg_signal_backend; однако только суперпользователям разрешено воздействовать на обслуживающие процессы других суперпользователей.
pg_reload_conf()booleanДаёт команду серверным процессам перегрузить конфигурацию
pg_rotate_logfile()booleanПрокручивает журнал сообщений сервера
pg_terminate_backend(pid int)booleanЗавершает обслуживающий процесс. Это действие разрешается и ролям, являющимся членами роли, обслуживающий процесс которой прерывается, и ролям, которым дано право pg_signal_backend; однако только суперпользователям разрешено прерывать обслуживающие процессы других суперпользователей.

Каждая из этих функций возвращает true при успешном завершении и false в противном случае.

pg_cancel_backend и pg_terminate_backend передают сигналы (SIGINT и SIGTERM, соответственно) серверному процессу с заданным кодом PID. Код активного процесса можно получить из столбца pid представления pg_stat_activity или просмотрев на сервере процессы с именем postgres (используя ps в Unix или Диспетчер задач в Windows). Роль пользователя активного процесса можно узнать в столбце usename представления pg_stat_activity.

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

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

9.26.3. Функции управления резервным копированием

Функции, перечисленные в Таблице 9.79, предназначены для выполнения резервного копирования «на ходу». Эти функции нельзя выполнять во время восстановления (за исключением немонопольных вариантов pg_start_backup и pg_stop_backup, а также функций pg_is_in_backup, pg_backup_start_time и pg_wal_lsn_diff).

Таблица 9.79. Функции управления резервным копированием

ИмяТип результатаОписание
pg_create_restore_point(name text)pg_lsnСоздаёт именованную точку для восстановления (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям)
pg_current_wal_flush_lsn()pg_lsnПолучает текущую позицию сброса данных в журнале предзаписи
pg_current_wal_insert_lsn()pg_lsnПолучает текущую позицию добавления в журнале предзаписи
pg_current_wal_lsn()pg_lsnПолучает текущую позицию записи в журнале предзаписи
pg_start_backup(label text [, fast boolean [, exclusive boolean]])pg_lsnПодготавливает сервер к резервному копированию (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям)
pg_stop_backup()pg_lsnЗавершает монопольное резервное копирование (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям)
pg_stop_backup(exclusive boolean [, wait_for_archive boolean])setof recordЗавершает монопольное или немонопольное резервное копирование (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям)
pg_is_in_backup()boolВозвращает true в процессе исключительного резервного копирования
pg_backup_start_time()timestamp with time zoneПолучает время запуска выполняющегося исключительного резервного копирования
pg_switch_wal()pg_lsnИнициирует переключение на новый файл журнала предзаписи (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям)
pg_walfile_name(lsn pg_lsn)textПолучает из позиции в журнале предзаписи имя соответствующего файла
pg_walfile_name_offset(lsn pg_lsn)text, integerПолучает из позиции в журнале предзаписи имя соответствующего файла и десятичное смещение в нём
pg_wal_lsn_diff(lsn pg_lsn, lsn pg_lsn)numericВычисляет разницу между двумя позициями в журнале предзаписи

pg_start_backup принимает произвольную заданную пользователем метку резервной копии. (Обычно это имя файла, в котором будет сохранена резервная копия.) При копировании в монопольном режиме эта функция записывает файл метки (backup_label) и, если есть ссылки в каталоге pg_tblspc/, файл карты табличных пространств (tablespace_map) в каталог данных кластера БД, выполняет процедуру контрольной точки, а затем возвращает в текстовом виде начальную позицию в журнале предзаписи для данной резервной копии. Результат этой функции может быть полезен, но если он не нужен, его можно просто игнорировать. При копировании в немонопольном режиме содержимое этих файлов выдаётся функцией pg_stop_backup и должно быть записано в архивную копию вызывающим субъектом.

postgres=# select pg_start_backup('label_goes_here');
 pg_start_backup
-----------------
 0/D4445B8
(1 row)

У этой функции есть также второй, необязательный параметр типа boolean. Если он равен true, pg_start_backup начнёт работу максимально быстро. При этом будет немедленно выполнена процедура контрольной точки, что может повлечь массу операций ввода/вывода и затормозить параллельные запросы.

При монопольном копировании функция pg_stop_backup удаляет файл метки (и, если существует, файл tablespace_map), созданный функцией pg_start_backup. При немонопольном копировании содержимое backup_label и tablespace_map возвращается в результате функции и должно быть записано в файлы в архиве (а не в каталоге данных). Также есть необязательный второй параметр типа boolean. Если он равен false, pg_stop_backup завершится сразу после окончания резервного копирования, не дожидаясь архивации WAL. Это поведение полезно только для программ резервного копирования, которые независимо осуществляют архивацию WAL. Если же WAL не заархивируется, резервная копия может оказаться неполной, а значит, бесполезной. Когда он равен true, pg_stop_backup будет ждать выполнения архивации WAL, если архивирование включено; для резервного сервера это означает, что ожидание возможно только при условии archive_mode = always. Если активность записи на ведущем сервере невысока, может иметь смысл выполнить на нём pg_switch_wal для немедленного переключения сегмента.

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

pg_switch_wal производит переключение на следующий файл журнала предзаписи, что позволяет архивировать текущий (в предположении, что архивация выполняется непрерывно). Эта функция возвращает конечную позицию в журнале предзаписи (в только что законченном файле журнала) + 1. Если с момента последнего переключения файлов не было активности, отражающейся в журнале предзаписи, pg_switch_wal не делает ничего и возвращает начальную позицию в файле журнала предзаписи, используемом в данный момент.

pg_create_restore_point создаёт именованную запись в журнале предзаписи, которую можно использовать как цель при восстановлении, и возвращает соответствующую позицию в журнале предзаписи. Затем полученное имя можно присвоить параметру recovery_target_name, указав тем самым точку, до которой будет выполняться восстановление. Учтите, что если вы создадите несколько точек восстановления с одним именем, восстановление будет остановлено на первой точке с этим именем.

pg_current_wal_lsn выводит текущую позицию записи в журнале предзаписи в том же формате, что и вышеописанные функции. pg_current_wal_insert_lsn подобным образом выводит текущую позицию добавления, а pg_current_wal_flush_lsn — позицию сброса данных журнала. Позицией добавления называется «логический» конец журнала предзаписи в любой момент времени, тогда как позиция записи указывает на конец данных, фактически вынесённых из внутренних буферов сервера, а позиция сброса показывает, до какого места данные гарантированно сохранены в надёжном хранилище. Позиция записи отмечает конец данных, которые может видеть снаружи внешний процесс, и именно она представляет интерес при копировании частично заполненных файлов журнала. Позиция добавления и позиция сброса выводятся в основном для отладки серверной части. Все эти операции выполняются в режиме «только чтение» и не требуют прав суперпользователя.

Из результатов всех описанных выше функций можно получить имя файла журнала предзаписи и смещение в нём, используя функцию pg_walfile_name_offset. Например:

postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
        file_name         | file_offset 
--------------------------+-------------
 00000001000000000000000D |     4039624
(1 row)

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

pg_wal_lsn_diff вычисляет разницу в байтах между двумя позициями в журнале предзаписи. Полученный результат можно использовать с pg_stat_replication или другими функциями, перечисленными в Таблице 9.79, для определения задержки репликации.

Подробнее практическое применение этих функций описывается в Разделе 24.3.

9.26.4. Функции управления восстановлением

Функции, приведённые в Таблице 9.80, предоставляют сведения о текущем состоянии ведомого сервера. Эти функции могут выполняться, как во время восстановления, так и в обычном режиме работы.

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

ИмяТип результатаОписание
pg_is_in_recovery()boolВозвращает true в процессе восстановления.
pg_last_wal_receive_lsn()pg_lsnПолучает позицию последней записи журнала предзаписи, полученной и записанной на диск в процессе потоковой репликации. Пока выполняется потоковая репликация, эта позиция постоянно увеличивается. По окончании восстановления она останавливается на записи WAL, полученной и записанной на диск последней. Если потоковая репликация отключена или ещё не запускалась, функция возвращает NULL.
pg_last_wal_replay_lsn()pg_lsnПолучает позицию последней записи журнала предзаписи, воспроизведённой при восстановлении. В процессе восстановления эта позиция постоянно увеличивается. По окончании восстановления она останавливается на записи WAL, которая была восстановлена последней. Если сервер был запущен не в режиме восстановления, эта функция возвращает NULL.
pg_last_xact_replay_timestamp()timestamp with time zoneПолучает отметку времени последней транзакции, воспроизведённой при восстановлении. Это время, когда на главном сервере произошла фиксация или откат записи WAL для этой транзакции. Если в процессе восстановления не была воспроизведена ни одна транзакция, эта функция возвращает NULL. В противном случае это значение постоянно увеличивается в процессе восстановления. По окончании восстановления оно останавливается на транзакции, которая была восстановлена последней. Если сервер был запущен не в режиме восстановления, эта функция возвращает NULL.

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

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

ИмяТип результатаОписание
pg_is_wal_replay_paused()boolВозвращает true, если восстановление приостановлено.
pg_wal_replay_pause()voidНемедленно приостанавливает восстановление (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям).
pg_wal_replay_resume()voidПерезапускает восстановление, если оно было приостановлено (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям).

Когда восстановление приостановлено, запись изменений в базу не производится. Если она находится в «горячем резерве», все последующие запросы будут видеть один согласованный снимок базы данных и до продолжения восстановления конфликты запросов исключаются.

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

9.26.5. Функции синхронизации снимков

Postgres Pro позволяет синхронизировать снимки состояния между сеансами баз данных. Снимок состояния определяет, какие данные видны транзакции, работающей с этим снимком. Синхронизация снимков необходима, когда в двух или более сеансах нужно видеть одно и то же содержимое базы данных. Если в двух сеансах транзакции запускаются независимо, всегда есть вероятность, что некая третья транзакция будет зафиксирована между командами START TRANSACTION для первых двух, и в результате в одном сеансе будет виден результат третьей, а в другом — нет.

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

Снимки состояния экспортируются с помощью функции pg_export_snapshot, показанной в Таблице 9.82, и импортируются командой SET TRANSACTION.

Таблица 9.82. Функции синхронизации снимков

ИмяТип результатаОписание
pg_export_snapshot()textСохраняет снимок текущего состояния и возвращает его идентификатор

Функция pg_export_snapshot создаёт снимок текущего состояния и возвращает его идентификатор в строке типа text. Данная строка должна передаваться (за рамками базы данных) клиентам, которые будут импортировать этот снимок. При этом импортировать его нужно раньше, чем завершится транзакция, которая его экспортировала. Если необходимо, транзакция может экспортировать несколько снимков. Заметьте, что это имеет смысл только для транзакций уровня READ COMMITTED, так как транзакции REPEATABLE READ и более высоких уровней изоляции работают с одним снимком состояния. После того как транзакция экспортировала снимок, её нельзя подготовить с помощью PREPARE TRANSACTION.

Подробнее использование экспортированных снимков рассматривается в описании SET TRANSACTION.

9.26.6. Функции репликации

В Таблице 9.83 перечислены функции, предназначенные для управления механизмом репликации и взаимодействия с ним. Чтобы изучить этот механизм детальнее, обратитесь к Подразделу 25.2.5, Подразделу 25.2.6 и Главе 48. Использовать эти функции для источников репликации разрешено только суперпользователям, а для слотов репликации — только суперпользователям и пользователям, имеющим право REPLICATION.

Многие из этих функций соответствуют командам в протоколе репликации; см. Раздел 51.4.

Функции, описанные в Подразделе 9.26.3, Подразделе 9.26.4 и Подразделе 9.26.5, также имеют отношение к репликации.

Таблица 9.83. Функции репликации SQL

ФункцияТип результатаОписание
pg_create_physical_replication_slot(slot_name name [, immediately_reserve boolean, temporary boolean])(slot_name name, lsn pg_lsn)Создаёт новый физический слот репликации с именем slot_name. Необязательный второй параметр, когда он равен true, указывает, что LSN для этого слота репликации должен быть зарезервирован немедленно; в противном случае LSN резервируется при первом подключении клиента потоковой репликации. Передача изменений из физического слота возможна только по протоколу потоковой репликации — см. Раздел 51.4. Необязательный третий параметр, temporary, когда он равен true, указывает, что этот слот не должен постоянно храниться на диске, так как он предназначен только для текущего сеанса. Временные слоты также освобождаются при любой ошибке. Эта функция соответствует команде протокола репликации CREATE_REPLICATION_SLOT ... PHYSICAL.
pg_drop_replication_slot(slot_name name)voidУдаляет физический или логический слот репликации с именем slot_name. Соответствует команде протокола репликации DROP_REPLICATION_SLOT. Для логических слотов эта функция должна вызываться через подключение к той же базе данных, в которой был создан слот.
pg_create_logical_replication_slot(slot_name name, plugin name [, temporary boolean])(slot_name name, lsn pg_lsn)Создаёт новый логический (декодирующий) слот репликации с именем slot_name, используя модуль вывода plugin. Необязательный третий параметр, temporary, когда равен true, указывает, что этот слот не должен постоянно храниться на диске, так как он предназначен только для текущего сеанса. Временные слоты также освобождаются при любой ошибке. Вызов этой функции равнозначен выполнению команды протокола репликации CREATE_REPLICATION_SLOT ... LOGICAL.
pg_logical_slot_get_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[])(lsn pg_lsn, xid xid, data text)Возвращает изменения в слоте slot_name с позиции, до которой ранее были получены изменения. Если параметры upto_lsn и upto_nchanges равны NULL, логическое декодирование продолжится до конца журнала транзакций. Если upto_lsn не NULL, декодироваться будут только транзакции, зафиксированные до заданного LSN. Если upto_nchanges не NULL, декодирование остановится, когда число строк, полученных при декодировании, превысит заданное значение. Заметьте однако, что фактическое число возвращённых строк может быть больше, так как это ограничение проверяется только после добавления строк, декодированных для очередной транзакции.
pg_logical_slot_peek_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[])(lsn pg_lsn, xid xid, data text)Работает так же, как функция pg_logical_slot_get_changes(), но не забирает изменения; то есть, они будут получены снова при следующих вызовах.
pg_logical_slot_get_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[])(lsn pg_lsn, xid xid, data bytea)Работает так же, как функция pg_logical_slot_get_changes(), но выдаёт изменения в типе bytea.
pg_logical_slot_peek_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[])(lsn pg_lsn, xid xid, data bytea)Работает так же, как функция pg_logical_slot_get_changes(), но выдаёт изменения в типе bytea и не забирает их; то есть, они будут получены снова при следующих вызовах.
pg_replication_slot_advance(slot_name name, upto_lsn pg_lsn)(slot_name name, end_lsn pg_lsn) boolПродвигает текущую подтверждённую позицию слота репликации с именем slot_name. Слот нельзя переместить назад, а также вперёд за текущую позицию добавления. Возвращает имя слота и позицию, до которой он продвинулся. Если слот был продвинут, информация об этом будет записана при ближайшей контрольной точке. В случае прерывания работы слот может оказаться в предыдущем положении.
pg_replication_origin_create(node_name text)oidСоздаёт источник репликации с заданным внешним именем и возвращает назначенный ему внутренний идентификатор.
pg_replication_origin_drop(node_name text)voidУдаляет ранее созданный источник репликации, в том числе связанную информацию о воспроизведении.
pg_replication_origin_oid(node_name text)oidИщет источник репликации по имени и возвращает внутренний идентификатор. Если такой источник не находится, возвращает NULL.
pg_replication_origin_session_setup(node_name text)voidПомечает текущий сеанс, как воспроизводящий журнал из указанного источника, что позволяет отслеживать положение воспроизведения. Чтобы отменить это действие, вызовите pg_replication_origin_session_reset. Может использоваться, только если не был настроен предыдущий источник.
pg_replication_origin_session_reset()voidОтменяет действие pg_replication_origin_session_setup().
pg_replication_origin_session_is_setup()boolВ текущем сеансе настроен источник репликации?
pg_replication_origin_session_progress(flush bool)pg_lsnВозвращает позицию воспроизведения для источника репликации, настроенного в текущем сеансе. Параметр flush определяет, будет ли гарантироваться сохранение локальной транзакции на диске.
pg_replication_origin_xact_setup(origin_lsn pg_lsn, origin_timestamp timestamptz)voidПомечает текущую транзакцию как воспроизводящую транзакцию, зафиксированную с указанным LSN и временем. Может вызываться только после того, как был настроен источник репликации в результате вызова pg_replication_origin_session_setup().
pg_replication_origin_xact_reset()voidОтменяет действие pg_replication_origin_xact_setup().
pg_replication_origin_advance(node_name text, lsn pg_lsn)voidУстанавливает положение репликации для заданного узла в указанную позицию. Это в основном полезно для установки начальной позиции или новой позиции после изменения конфигурации и подобных действий. Но учтите, что неосторожное использование этой функции может привести к несогласованности реплицированных данных.
pg_replication_origin_progress(node_name text, flush bool)pg_lsnВозвращает позицию воспроизведения для заданного источника репликации. Параметр flush определяет, будет ли гарантироваться сохранение локальной транзакции на диске.
pg_logical_emit_message(transactional bool, prefix text, content text)pg_lsnВыдаёт текстовое сообщение логического декодирования. Её можно использовать для передачи произвольных сообщений через WAL модулям логического декодирования. Параметр transactional устанавливает, должно ли сообщение быть частью текущей транзакции или оно должно записываться немедленно и декодироваться сразу, как только эта запись будет прочитана при логическом декодировании. Параметр prefix задаёт текстовый префикс, по которому модули логического декодирования могут легко распознать интересующие их сообщения. В параметре content передаётся текст сообщения.
pg_logical_emit_message(transactional bool, prefix text, content bytea)pg_lsnВыдаёт двоичное сообщение логического декодирования. Её можно использовать для передачи произвольных сообщений через WAL модулям логического декодирования. Параметр transactional устанавливает, должно ли сообщение быть частью текущей транзакции или оно должно записываться немедленно и декодироваться сразу, как только эта запись будет прочитана при логическом декодировании. Параметр prefix задаёт текстовый префикс, по которому модули логического декодирования могут легко распознать интересующие их сообщения. В параметре content передаётся двоичное содержимое сообщения.

9.26.7. Функции управления объектами баз данных

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

Таблица 9.84. Функции получения размера объектов БД

ИмяТип результатаОписание
pg_column_size(any)intЧисло байт, необходимых для хранения заданного значения (возможно, в сжатом виде)
pg_database_size(oid)bigintОбъём, который занимает на диске база данных с заданным OID
pg_database_size(name)bigintОбъём, который занимает на диске база данных с заданным именем
pg_indexes_size(regclass)bigintОбщий объём индексов, связанных с указанной таблицей
pg_relation_size(relation regclass, fork text)bigintОбъём, который занимает на диске указанный слой ('main', 'fsm', 'vm' или 'init') заданной таблицы или индекса
pg_relation_size(relation regclass)bigintКраткая форма pg_relation_size(..., 'main')
pg_size_bytes(text)bigintПреобразует размер в понятном человеку формате с единицами измерения в число байт
pg_size_pretty(bigint)textПреобразует размер в байтах, представленный в 64-битном целом, в понятный человеку формат с единицами измерения
pg_size_pretty(numeric)textПреобразует размер в байтах, представленный в значении числового типа, в понятный человеку формат с единицами измерения
pg_table_size(regclass)bigintОбъём, который занимает на диске данная таблица, за исключением индексов (но включая TOAST, карту свободного места и карту видимости)
pg_tablespace_size(oid)bigintОбъём, который занимает на диске табличное пространство с указанным OID
pg_tablespace_size(name)bigintОбъём, который занимает на диске табличное пространство с заданным именем
pg_total_relation_size(regclass)bigintОбщий объём, который занимает на диске заданная таблица, включая все индексы и данные TOAST

pg_column_size показывает, какой объём требуется для хранения данного значения.

pg_total_relation_size принимает OID или имя таблицы или данных TOAST и возвращает общий объём, который занимает на диске эта таблица, включая все связанные с ней индексы. Результат этой функции равняется pg_table_size + pg_indexes_size.

pg_table_size принимает OID или имя таблицы и возвращает объём, который занимает на диске эта таблица без индексов. (При этом учитывается размер TOAST, карты свободного места и карты видимости.)

pg_indexes_size принимает OID или имя таблицы и возвращает общий объём, который занимают все индексы таблицы.

pg_database_size и pg_tablespace_size принимают OID или имя базы данных либо табличного пространства и возвращают общий объём, который они занимают на диске. Для использования pg_database_size требуется иметь право CONNECT для указанной базы данных (оно предоставляется по умолчанию) или быть членом роли pg_read_all_stats. Для использования pg_tablespace_size необходимо иметь право CREATE для указанного табличного пространства или быть членом роли pg_read_all_stats, если только это не табличное пространство по умолчанию для текущей базы данных.

pg_relation_size принимает OID или имя таблицы, индекса или TOAST-таблицы и возвращает размер одного слоя этого отношения (в байтах). (Заметьте, что в большинстве случаев удобнее использовать более высокоуровневые функции pg_total_relation_size и pg_table_size, которые суммируют размер всех слоёв.) С одним аргументом она возвращает размер основного слоя для данных заданного отношения. Название другого интересующего слоя можно передать во втором аргументе:

  • 'main' возвращает размер основного слоя данных заданного отношения.

  • 'fsm' возвращает размер карты свободного места (см. Раздел 65.3), связанной с заданным отношением.

  • 'vm' возвращает размер карты видимости (см. Раздел 65.4), связанной с заданным отношением.

  • 'init' возвращает размер слоя инициализации для заданного отношения, если он имеется.

pg_size_pretty можно использовать для форматирования результатов других функций в виде, более понятном человеку, с единицами измерения bytes, kB, MB, GB и TB.

pg_size_bytes можно использовать для получения размера в байтах из строки в формате, понятном человеку. Входная строка может содержать единицы bytes, kB, MB, GB и TB, и разбирается без учёта регистра. Если единицы не указываются, подразумеваются байты.

Примечание

Единицы kB, MB, GB и TB, фигурирующие в функциях pg_size_pretty и pg_size_bytes, определяются как степени 2, а не 10, так что 1kB равен 1024 байтам, 1MB равен 10242 = 1048576 байт и т. д.

Вышеописанные функции, работающие с таблицами или индексами, принимают аргумент типа regclass, который представляет собой просто OID таблицы или индекса в системном каталоге pg_class. Однако вам не нужно вручную вычислять OID, так как процедура ввода значения regclass может сделать это за вас. Для этого достаточно записать имя таблицы в апострофах, как обычную текстовую константу. В соответствии с правилами обработки обычных имён SQL, если имя таблицы не заключено в кавычки, эта строка будет переведена в нижний регистр.

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

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

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

ИмяТип результатаОписание
pg_relation_filenode(relation regclass)oidНомер файлового узла для указанного отношения
pg_relation_filepath(relation regclass)textПуть к файлу, в котором хранится указанное отношение
pg_filenode_relation(tablespace oid, filenode oid)regclassНаходит отношение, связанное с данным табличным пространством и файловым узлом

pg_relation_filenode принимает OID или имя таблицы, индекса, последовательности или таблицы TOAST и возвращает номер «файлового узла», связанным с этим объектом. Файловым узлом называется основной компонент имени файла, используемого для хранения данных (подробнее это описано в Разделе 65.1). Для большинства таблиц этот номер совпадает со значением pg_class.relfilenode, но для некоторых системных каталогов relfilenode равен 0, и нужно использовать эту функцию, чтобы узнать действительное значение. Если указанное отношение не хранится на диске, как например представление, данная функция возвращает NULL.

pg_relation_filepath подобна pg_relation_filenode, но возвращает полный путь к файлу (относительно каталога данных PGDATA) отношения.

Функция pg_filenode_relation является обратной к pg_relation_filenode. Она возвращает OID отношения по заданному OID «табличного пространства» и «файловому узлу». Для таблицы в табличном пространстве по умолчанию в первом параметре можно передать 0.

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

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

ИмяТип результатаОписание
pg_collation_actual_version(oid)textвыдаёт действующую версию правила сортировки из операционной системы
pg_import_system_collations(schema regnamespace)integerимпортирует правила сортировки из операционной системы

Функция pg_collation_actual_version возвращает действующую версию объекта правила сортировки, которая в настоящее время установлена в операционной системе. Если она отличается от значения в pg_collation.collversion, может потребоваться перестроить объекты, зависящие от данного правила сортировки. См. также ALTER COLLATION.

Функция pg_import_system_collations добавляет правила сортировки в системный каталог pg_collation, анализируя все локали, которые она находит в операционной системе. Эту информацию использует initdb; за подробностями обратитесь к Подразделу 22.2.2. Если позднее в систему устанавливаются дополнительные локали, эту функцию можно запустить снова, чтобы добавились правила сортировки для новых локалей. Локали, для которых обнаруживаются существующие записи в pg_collation, будут пропущены. (Объекты правил сортировки для локалей, которые перестают существовать в операционной системе, никогда не удаляются этой функцией.) В параметре schema обычно передаётся pg_catalog, но это не обязательно; правила сортировки могут быть установлены и в другую схему. Эта функция возвращает число созданных ей объектов правил сортировки; вызывать её разрешено только суперпользователям.

9.26.8. Функции обслуживания индексов

В Таблице 9.87 перечислены функции, предназначенные для обслуживания индексов. Эти функции нельзя вызывать в процессе восстановления. Использовать эти функции разрешено только суперпользователям и владельцу определённого индекса.

Таблица 9.87. Функции обслуживания индексов

ИмяТип результатаОписание
brin_summarize_new_values(index regclass)integerобобщает ещё не обобщённые зоны страниц
brin_summarize_range(index regclass, blockNumber bigint)integerобобщает зону страниц, охватывающую данный блок (если она ещё не обобщена)
brin_desummarize_range(index regclass, blockNumber bigint)integerсброс обобщения зоны страниц, охватывающей данный блок (если она была обобщена)
gin_clean_pending_list(index regclass)bigintперемещает элементы из списка записей GIN, ожидающих обработки, в основную структуру индекса

Функция brin_summarize_new_values принимает OID или имя индекса BRIN и просматривает индекс в поисках зон страниц в базовой таблице, ещё не обобщённых в индексе; для каждой такой зоны в результате сканирования страниц таблицы создаётся новый обобщающий кортеж в индексе. Возвращает эта функция число вставленных в индекс обобщающих записей о зонах страниц. Функция brin_summarize_range делает то же самое, но затрагивает только зону, охватывающую блок с заданным номером.

Функция gin_clean_pending_list принимает OID или имя индекса GIN и очищает очередь указанного индекса, массово перемещая элементы из неё в основную структуру данных GIN. Возвращает она число страниц, убранных из очереди. Заметьте, что если для обработки ей передаётся индекс GIN, построенный с отключённым параметром fastupdate, очистка не производится и возвращается значение 0, так как у такого индекса нет очереди записей. Подробнее об очереди записей и параметре fastupdate рассказывается в Подразделе 62.4.1 и Разделе 62.5.

9.26.9. Функции для работы с обычными файлами

Функции, перечисленные в Таблице 9.88, предоставляют прямой доступ к файлам, находящимся на сервере. Обычным пользователям, не включённым в роль pg_read_server_files, они позволяют обращаться только к файлам в каталоге кластера баз данных и в каталоге log_directory. Для файлов в каталоге кластера этим функциям передаётся относительный путь, а для файлов журнала — путь, соответствующий значению параметра log_directory.

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

Таблица 9.88. Функции для работы с обычными файлами

ИмяТип результатаОписание
pg_ls_dir(dirname text [, missing_ok boolean, include_dot_dirs boolean])setof textВыводит содержимое каталога (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям).
pg_ls_logdir()setof recordВыводит имя, размер и время последнего изменения файлов в каталоге журнала сообщений. Доступ к этой функции имеют члены роли pg_monitor, также его можно разрешить и другим ролям обычных пользователей.
pg_ls_waldir()setof recordВыводит имя, размер и время последнего изменения файлов в каталоге WAL. Доступ к этой функции имеют члены роли pg_monitor, также его можно разрешить и другим ролям обычных пользователей.
pg_read_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ])textВозвращает содержимое текстового файла (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям).
pg_read_binary_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ])byteaВозвращает содержимое файла (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям).
pg_stat_file(filename text[, missing_ok boolean])recordВозвращает информацию о файле (по умолчанию разрешено только суперпользователям, но право на её выполнение (EXECUTE) можно дать и другим пользователям).

Некоторые из этих функций принимают необязательный параметр missing_ok, который определяет их поведение в случае отсутствия файла или каталога. Если он равен true, функция возвращает NULL (за исключением pg_ls_dir, которая возвращает пустое множество). Если он равен false, возникает ошибка. Значение по умолчанию — false.

pg_ls_dir возвращает имена всех файлов (а также каталогов и других специальных файлов) в заданном каталоге. Параметр include_dot_dirs определяет, будут ли в результирующий набор включаться каталоги «.» и «..». По умолчанию они не включаются (false), но их можно включить, чтобы с параметром missing_ok равным true, пустой каталог можно было отличить от несуществующего.

pg_ls_logdir возвращает имя, размер и время последнего изменения (mtime) всех файлов в каталоге журналов сообщений. По умолчанию использовать её разрешено только суперпользователям и членам роли pg_monitor. Другим пользователям доступ к ней можно дать, используя GRANT. Эта функция не показывает файлы с именами, начинающимися с точки, каталоги и другие специальные файлы.

pg_ls_waldir возвращает имя, размер и время последнего изменения (mtime) всех файлов в каталоге журнала предзаписи (WAL). По умолчанию использовать её разрешено только суперпользователям и членам роли pg_monitor. Другим пользователям доступ к ней можно дать, используя GRANT. Эта функция не показывает файлы с именами, начинающимися с точки, каталоги и другие специальные файлы.

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

pg_read_binary_file подобна pg_read_file, но её результат имеет тип bytea; как следствие, никакие проверки кодировки не выполняются. В сочетании с convert_from эту функцию можно применять для чтения файлов в произвольной кодировке:

SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');

pg_stat_file возвращает запись, содержащую размер файла, время последнего обращения и последнего изменения, а также время последнего изменения состояния (только в Unix-системах), время создания (только в Windows) и признак типа boolean, показывающий, что это каталог. Примеры использования:

SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;

9.26.10. Функции управления рекомендательными блокировками

Функции, перечисленные в Таблице 9.89, предназначены для управления рекомендательными блокировками. Подробнее об их использовании можно узнать в Подразделе 13.3.5.

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

ИмяТип результатаОписание
pg_advisory_lock(key bigint)voidПолучает исключительную блокировку на уровне сеанса
pg_advisory_lock(key1 int, key2 int)voidПолучает исключительную блокировку на уровне сеанса
pg_advisory_lock_shared(key bigint)voidПолучает разделяемую блокировку на уровне сеанса
pg_advisory_lock_shared(key1 int, key2 int)voidПолучает разделяемую блокировку на уровне сеанса
pg_advisory_unlock(key bigint)booleanОсвобождает исключительную блокировку на уровне сеанса
pg_advisory_unlock(key1 int, key2 int)booleanОсвобождает исключительную блокировку на уровне сеанса
pg_advisory_unlock_all()voidОсвобождает все блокировки на уровне сеанса, удерживаемые в данном сеансе
pg_advisory_unlock_shared(key bigint)booleanОсвобождает разделяемую блокировку на уровне сеанса
pg_advisory_unlock_shared(key1 int, key2 int)booleanОсвобождает разделяемую блокировку на уровне сеанса
pg_advisory_xact_lock(key bigint)voidПолучает исключительную блокировку на уровне транзакции
pg_advisory_xact_lock(key1 int, key2 int)voidПолучает исключительную блокировку на уровне транзакции
pg_advisory_xact_lock_shared(key bigint)voidПолучает разделяемую блокировку на уровне транзакции
pg_advisory_xact_lock_shared(key1 int, key2 int)voidПолучает разделяемую блокировку на уровне транзакции
pg_try_advisory_lock(key bigint)booleanПолучает исключительную блокировку на уровне сеанса, если это возможно
pg_try_advisory_lock(key1 int, key2 int)booleanПолучает исключительную блокировку на уровне сеанса, если это возможно
pg_try_advisory_lock_shared(key bigint)booleanПолучает разделяемую блокировку на уровне сеанса, если это возможно
pg_try_advisory_lock_shared(key1 int, key2 int)booleanПолучает разделяемую блокировку на уровне сеанса, если это возможно
pg_try_advisory_xact_lock(key bigint)booleanПолучает исключительную блокировку на уровне транзакции, если это возможно
pg_try_advisory_xact_lock(key1 int, key2 int)booleanПолучает исключительную блокировку на уровне транзакции, если это возможно
pg_try_advisory_xact_lock_shared(key bigint)booleanПолучает разделяемую блокировку на уровне транзакции, если это возможно
pg_try_advisory_xact_lock_shared(key1 int, key2 int)booleanПолучает разделяемую блокировку на уровне транзакции, если это возможно

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

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

pg_try_advisory_lock работает подобно pg_advisory_lock, но не ждёт освобождения ресурса. Эта функция либо немедленно получает блокировку и возвращает true, либо сразу возвращает false, если получить её не удаётся.

pg_try_advisory_lock_shared работает как pg_try_advisory_lock, но пытается получить разделяемую, а не исключительную блокировку.

pg_advisory_unlock освобождает ранее полученную исключительную блокировку на уровне сеанса. Если блокировка освобождена успешно, эта функция возвращает true, а если она не была занята — false, при этом сервер выдаёт предупреждение SQL.

pg_advisory_unlock_shared работает подобно pg_advisory_unlock, но освобождает разделяемую блокировку на уровне сеанса.

pg_advisory_unlock_all освобождает все блокировки на уровне сеанса, закреплённые за текущим сеансом. (Эта функция неявно вызывается в конце любого сеанса, даже при нештатном отключении клиента.)

pg_advisory_xact_lock работает подобно pg_advisory_lock, но её блокировка автоматически освобождается в конце текущей транзакции и не может быть освобождена явным образом.

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

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

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

9.26.11. Отладочные функции

Функция, показанная в Таблице 9.90, может быть полезна для низкоуровневых операций, например в целях отладки или исследования испорченных баз данных Postgres Pro.

Таблица 9.90. Функции синхронизации снимков

ИмяТип результатаОписание
pg_snapshot_any()voidОтключает действие правил MVCC в рамках текущей транзакции, что позволяет видеть в ней все версии данных.

Применяйте pg_snapshot_any крайне осторожно. Выполнять её следует в транзакции с уровнем изоляции REPEATABLE READ или выше, в противном случае следующий же запрос заменит выбранный снимок новым. Выполнять её могут только суперпользователи.

Примечание

Если ваш кластер БД создавался сервером версии, в которой этой функции ещё не было, определите её следующей командой:

CREATE FUNCTION pg_snapshot_any() RETURNS void AS 'pg_snapshot_any' LANGUAGE internal;