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

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

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

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

SELECT current_setting('datestyle');

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

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-64, позволяют передавать управляющие сигналы другим серверным процессам. Вызывать эти функции обычно могут только суперпользователи, кроме явно отмеченных исключений.

Каждая из этих функций возвращает 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-65, предназначены для выполнения резервного копирования «на ходу». Эти функции нельзя выполнять во время восстановления (за исключением pg_is_in_backup, pg_backup_start_time и pg_xlog_location_diff).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В Таблице 9-69 перечислены функции, предназначенные для управления и взаимодействия с механизмом репликации. Чтобы узнать об этом механизме подробнее, обратитесь к Подразделу 25.2.5 и Подраздел 25.2.6. Использовать эти функции разрешено только суперпользователям.

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

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

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

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

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_tablespace_size необходимо иметь право CREATE в указанном табличном пространстве, если только это не табличное пространство по умолчанию для текущей базы данных.

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

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

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

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

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

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

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

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

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

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

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

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

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

Функции, перечисленные в Таблице 9-72, предоставляют прямой доступ к файлам, находящимся на сервере. Они позволяют обращаться только к файлам в каталоге кластера баз данных (по относительному пути) или в каталоге log_directory (по пути, заданному в параметре конфигурации log_directory). Использовать эти функции могут только суперпользователи.

pg_ls_dir возвращает имена всех файлов и подкаталогов в заданном каталоге, за исключением специальных элементов "." и "..".

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.9. Функции управления рекомендательными блокировками

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

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, но её блокировка (если она была получена) автоматически освобождается в конце текущей транзакции и не может быть освобождена явным образом.