pg_ctl

pg_ctl — инициализировать, запустить, остановить или управлять сервером PostgreSQL

Синтаксис

pg_ctl init[db] [-s] [-D каталог_данных] [-o параметры-initdb]

pg_ctl start [-w] [-t секунды] [-s] [-D каталог_данных] [-l имя_файла] [-o параметры] [-p путь] [-c]

pg_ctl stop [-W] [-t секунды] [-s] [-D каталог_данных] [-m s[mart] | f[ast] | i[mmediate] ]

pg_ctl restart [-w] [-t секунды] [-s] [-D каталог_данных] [-c] [-m s[mart] | f[ast] | i[mmediate] ] [-o параметры]

pg_ctl reload [-s] [-D каталог_данных]

pg_ctl status [-D каталог_данных]

pg_ctl promote [-s] [-D каталог_данных]

pg_ctl kill имя_сигнала ид_процесса

pg_ctl register [-N имя_службы] [-U имя_пользователя] [-P пароль] [-D каталог_данных] [-S a[uto] | d[emand] ] [-w] [-t секунды] [-s] [-o параметры]

pg_ctl unregister [-N имя_службы]

Описание

pg_ctl — это утилита для начальной инициализации, запуска, остановки, повторного запуска и управления кластером баз данных PostgreSQL (postgres). Сервер можно стартовать в ручном режиме, но pg_ctl реализует задачи направления вывода в журнал и отсоединения от терминала и группы процессов, а также предоставляет удобный интерфейс остановки кластера.

Для инициализации нового кластера PostgreSQL используются режимы init или initdb. Кластер — это коллекция баз данных под управлением единого сервера. По факту вызывается команда initdb. За подробностями обратитесь к initdb.

Сервер запускается в режиме start. Процесс работает в фоновом режиме, а стандартный ввод связывается с /dev/null (или nul под управлением Windows). По умолчанию в Unix-подобных системах вывод и ошибки сервера пишутся в устройство стандартного вывода (не ошибок) pg_ctl. Вывод pg_ctl следует перенаправить в файл или процесс, например, приложение ротации журналов rotatelogs; в ином случае postgres будет писать вывод в управляющий терминал (в фоновом режиме) и останется в группе процессов оболочки. В Windows сообщения и ошибки сервера по умолчанию перенаправляются в терминал. Это поведение можно изменить и направить вывод сервера в файл, добавив ключ -l. Мы рекомендуем использовать ключ -l или перенаправлять вывод.

В режиме stop сервер, работающий в указанном каталоге данных, останавливается. Параметр -m позволяет выбрать три различных режима остановки. Режим «Smart» ожидает отключения всех активных клиентов и завершения всех текущих процессов резервного копирования. Если сервер работает в режиме горячего резерва, восстановление и потоковая репликация будут прерваны, как только отключатся все клиенты. Режим «Fast» (выбираемый по умолчанию) не ожидает отключения клиентов и завершает все текущие процессы резервного копирования. Все активные транзакции откатываются, а клиенты принудительно отключаются, после чего сервер останавливается. Режим «Immediate» незамедлительно прерывает все серверные процессы, не выполняя процедуру штатной остановки. В результате при следующем запуске будет запущено восстановление после сбоя.

В режиме restart по сути выполняется остановка и последующий запуск сервера. Это позволяет изменить параметры командной строки postgres. Режим restart может не отработать, если при запуске сервера в командной строке задавались относительные пути.

Чтобы перечитать конфигурацию (postgresql.conf, pg_hba.conf и т. д.), используется reload, при этом процесс postgres получает системный сигнал SIGHUP. Это позволяет применить изменения без полного рестарта сервера.

Чтобы проверить статус кластера, используется status. Если кластер запущен, то будет выведен PID процесса, а также команда с использованными при запуске аргументами. Если кластер остановлен, то процесс вернёт статус завершения 3. Если не указан каталог хранения данных, то процесс вернёт статус завершения 4.

Чтобы перевести резервный сервер в режим главного, используется promote. При этом сервер прекращает работу в режиме восстановления и начинает работать в режиме чтения-записи.

Чтобы послать сигнал процессу, используется kill. Это особенно применимо в среде Microsoft Windows, которая не имеет в оснастке команды kill. Чтобы посмотреть список доступных сигналов, обратитесь к справке --help.

Режим register предназначен для регистрации системной службы в Microsoft Windows. Параметр -S позволяет выбрать тип запуска службы, «auto» (запускать службу автоматически при загрузке системы) или «demand» (запускать службу по требованию).

Чтобы удалить зарегистрированную службу в Microsoft Windows, используется unregister. Эта операция отменяет действие команды register.

Параметры

-c
--core-file

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

-D каталог_данных
--pgdata каталог_данных

Указывает размещение конфигурационных файлов кластера. Если не указано, используется значение переменной окружения PGDATA.

-l имя_файла
--log имя_файла

Направляет вывод сообщений сервера в файл имя_файла. Файл создаётся, если он ещё не существует. При этом устанавливается umask 077, что предотвращает доступ других пользователей к этому файлу.

-m режим
--mode режим

Задаёт режим остановки кластера. Значением режим может быть smart, fast или immediate, либо первая буква этих вариантов. По умолчанию выбирается режим fast.

-o параметры

Указывает флаги, которые будут переданы непосредственно программе postgres; несколько параметров складываются вместе.

Эти параметры обычно следует обрамлять одинарными или двойными кавычками, чтобы они передавались вместе как одна группа.

-o параметры-initdb

Указывает флаги, которые будут переданы в initdb.

Эти параметры обычно следует обрамлять одинарными или двойными кавычками, чтобы они передавались вместе как одна группа.

-p путь

Указывает размещение исполняемого файла postgres. По умолчанию задействуется исполняемый файл postgres из того же каталога, из которого запускался pg_ctl, а если это невозможно, из жёстко заданного каталога инсталляции. Применять этот параметр может понадобиться, только если вы делаете что-то необычное или получаете сообщения, что найти исполняемый файл postgres не удаётся.

В режиме init этот параметр аналогичным образом задаёт размещение исполняемого файла initdb.

-s
--silent

Выводить лишь ошибки, без сообщений информационного характера.

-t
--timeout

Максимальное время (в секундах) ожидания запуска или остановки сервера. По умолчанию принимается значение переменной среды PGCTLTIMEOUT или, если оно не задано, 60 секунд.

-V
--version

Выводит версию pg_ctl и прерывает выполнение.

-w

Ждать завершения запуска или остановки. Это вариант по умолчанию при остановке, но не при запуске. Ожидая запуска, pg_ctl постоянно пытается подключиться к серверу. Ожидая остановки, pg_ctl ждёт, пока сервер не удалит свой файл PID. Этот параметр позволяет ввести парольную фразу SSL при запуске. pg_ctl возвращает код завершения, сообщающий об успехе запуска или остановки.

-W

Не ждать завершения запуска или остановки. Это вариант по умолчанию для режимов запуска и перезапуска.

-?
--help

Вывести справку по команде pg_ctl и прервать выполнение.

Параметры, специфичные для Windows

-e source

Имя источника событий, с которым pg_ctl будет записывать в системный журнал события при запуске в виде службы Windows. Имя по умолчанию — PostgreSQL. Заметьте, что это влияет только на сообщения, которые выдаёт сам pg_ctl; как только сервер запустится, он будет использовать источник событий, заданный в event_source. Если произойдёт ошибка при запуске сервера на ранней стадии, он также выдаст сообщение с источником по умолчанию PostgreSQL.

-N имя_службы

Имя регистрируемой системной службы. Оно станет и собственно именем службы, и отображаемым именем.

-P пароль

Пароль для пользователя, запускающего службу.

-S тип-запуска

Тип запуска системной службы. Может принимать значения: auto, или demand, либо быть представлен первой буквой названия каждого приведённого значения. По умолчанию используется auto.

-U имя_пользователя

Имя пользователя, от имени которого будут запущена служба. Для доменных пользователей необходимо использовать нотацию DOMAIN\username.

Переменные окружения

PGCTLTIMEOUT

Значение по умолчанию для максимального времени ожидания запуска или остановки сервера (в секундах). По умолчанию это время составляет 60 секунд.

PGDATA

Размещение каталога хранения данных по умолчанию.

pg_ctl, как и большинство других утилит PostgreSQL, также использует переменные окружения, поддерживаемые libpq (см. Раздел 32.14). Другие переменные сервера описаны в postgres.

Файлы

postmaster.pid

Наличие файла в каталоге хранения данных помогает pg_ctl определить, работает ли сервер в настоящий момент.

postmaster.opts

Если файл существует в каталоге хранения данных, то pg_ctl (при restart) передаст его содержимое в качестве аргументов postgres, если не указаны иные значения в -o. Содержимое файла также отображается при вызове в режиме status.

Примеры

Запуск сервера

Для запуска сервера:

$ pg_ctl start

Для запуска сервера с ожиданием готовности к приёму подключений:

$ pg_ctl -w start

Чтобы запустить сервер с использованием порта 5433 и без fsync, выполните:

$ pg_ctl -o "-F -p 5433" start

Остановка сервера

Для остановки сервера:

$ pg_ctl stop

Параметр -m указывает режим остановки:

$ pg_ctl stop -m fast

Повторный запуск сервера

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

$ pg_ctl restart

Для повторного запуска сервера с ожиданием полной остановки и последующего запуска:

$ pg_ctl -w restart

Для повторного запуска на порту 5433 с выключенным fsync после старта:

$ pg_ctl -o "-F -p 5433" restart

Вывод состояния сервера

Ниже представлен примерный вывод pg_ctl:

$ pg_ctl status

pg_ctl: server is running (PID: 13718)
/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"

Показанная командная строка будет использоваться в режиме перезапуска.

См. также

initdb, postgres