Skip to main content

pg_ctl

note

Эта страница переведена при помощи нейросети GigaChat.

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

Синтаксис​

pg_ctl init[db] [-D datadir] [-s] [-o initdb-options]

pg_ctl start [-D datadir] [-l filename] [-W] [-t seconds] [-s] [-o options] [-p path] [-c]

pg_ctl stop [-D datadir] [-m s[mart] | f[ast] | i[mmediate]] [-W] [-t seconds] [-s]

pg_ctl restart [-D datadir] [-m s[mart] | f[ast] | i[mmediate]] [-W] [-t seconds] [-s] [-o options] [-c]

pg_ctl reload [-D datadir] [-s]

pg_ctl status [-D datadir]

pg_ctl promote [-D datadir] [-W] [-t seconds] [-s]

pg_ctl logrotate [-D datadir] [-s]

pg_ctl kill signal_name process_id

В Microsoft Windows также:

pg_ctl register [-D datadir] [-N servicename] [-U username] [-P password] [-S a[uto] | d[emand]] [-e source] [-W] [-t seconds] [-s] [-o options]

pg_ctl unregister [-N servicename]

Описание​

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

Утилита pg_ctl предоставляет различные команды для управления сервером баз данных:

  • init или initdb — создает новый кластер баз данных (набор баз, управляемых одним сервером). Используется команда initdb.

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

  • stop — останавливает сервер, работающий с заданным каталогом данных. С помощью параметра -m можно задать один из трех режимов остановки:

    • smart — сервер больше не принимает новые подключения и ждет завершения работы всех клиентов. При наличии репликации и восстановления — они останавливаются после отключения клиентов;
    • fast (по умолчанию) — все активные транзакции откатываются, клиенты отключаются, сервер завершает работу;
    • immediate — серверные процессы немедленно завершаются без нормального завершения работы. При следующем запуске потребуется восстановление после сбоя;

  • restart — сочетание остановки и последующего запуска сервера. Полезно при изменении параметров, которые требуют перезапуска. При использовании относительных путей важно запускать pg_ctl из того же каталога, что и при старте сервера.

  • reload — заставляет сервер перечитать конфигурационные файлы (postgresql.conf, pg_hba.conf и другие), отправляя ему сигнал SIGHUP. Используется для изменения параметров конфигурационных файлов, не требующих полного перезапуска.

  • status — проверяет, работает ли сервер, и, если да, выводит его PID и параметры запуска. Если сервер не запущен, pg_ctl возвращает код завершения 3. Если не указан доступный каталог данных, pg_ctl возвращает код завершения 4.

  • promote— переводит сервер из режима резерва в режим основной базы с возможностью записи.

  • logrotate— инициирует ротацию журнала сервера. Подробнее описано в разделе «Обслуживание файла журнала».

  • kill — отправляет сигнал выбранному серверному процессу. Особенно полезно в Windows, где отсутствует команда kill. Используйте --help, чтобы увидеть список поддерживаемых имен сигналов.

  • register — регистрирует сервер как системную службу Windows. Параметр -S задает тип запуска службы: auto (запускать службу автоматически при загрузке системы) или demand (запускать службу по требованию).

  • unregister — отменяет действие register.

Параметры​

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

-c
--core-files
Разрешает серверу создавать дампы памяти при сбоях на платформах, где это поддерживается, за счет снятия мягких ограничений ресурсов, наложенных на такие файлы. Это полезно для отладки и диагностики, поскольку позволяет получить трассировку стека из аварийно завершившегося серверного процесса.
-D datadir
--pgdata=datadir
Определяет путь к каталогу с файлами конфигурации базы данных. При отсутствии этого параметра используется переменная окружения PGDATA.
-l filename
--log=filename
Указывает файл журнала filename для вывода сообщений сервера. Если файл отсутствует, он создается. Права доступа по умолчанию (umask 077) ограничивают доступ к файлу другими пользователями.
-m mode
--mode=mode
Устанавливает режим завершения работы: smart, fast или immediate (можно использовать первые буквы). Значение по умолчанию — fast.
-o options
--options=options
Передает дополнительные параметры непосредственно postgres. Может указываться несколько раз. Рекомендуется заключать параметры в одинарные или двойные кавычки для корректной передачи.
-o initdb-options
--options=initdb-options
Передает параметры команде initdb. Может указываться несколько раз. Рекомендуется заключать параметры в одинарные или двойные кавычки для корректной передачи.
-p path
Определяет путь к исполняемому файлу postgres. По умолчанию исполняемый файл postgres берется из того же каталога, что и pg_ctl, а при отсутствии — из заданного каталога установки. Обычно не требуется, если используется стандартная установка.

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

-s
--silent
Выводит только ошибки, без информационных сообщений.
-t seconds
--timeout=seconds
Устанавливает максимальное время ожидания операции в секундах (смотрите параметр -w). Если переменная PGCTLTIMEOUT не задана, используется 60 секунд по умолчанию.
-V
--version
Выводит версию pg_ctl и завершается.
-w
--wait
Включает режим ожидания завершения операции. Применяется для команд start, stop, restart, promote и register, являясь значением по умолчанию. Утилита проверяет файл PID, чтобы определить готовность сервера.

Во время ожидания pg_ctl периодически проверяет файл PID сервера, делая короткие паузы между проверками. Считается, что сервер запущен, когда в файле PID указано, что он готов принимать подключения. Завершение работы считается полным, когда сервер удаляет файл PID. Код выхода pg_ctl отражает успешность запуска или завершения.

Если операция не завершится в течение заданного времени ожидания (смотрите параметр -t), pg_ctl завершит работу с ненулевым кодом. Однако сама операция может продолжиться в фоновом режиме и впоследствии успешно завершиться.

-W
--no-wait
Отключает ожидание завершения операции — противоположно параметру -w.

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

В предыдущих версиях PostgreSQL такое поведение было установлено по умолчанию, кроме режима stop.

Результат выполнения не проверяется — требуется использовать журналы или внешние средства мониторинга. Ранее это поведение было стандартным (кроме stop).

-?
--help
Показывает справку о параметрах командной строки утилиты pg_ctl и завершается.

Если указан параметр, который действителен, но не актуален для выбранного режима работы, pg_ctl игнорирует его.

Параметры для Windows​

-e source
Определяет имя источника событий для регистрации сообщений pg_ctl в журнале событий Windows. По умолчанию используется PostgreSQL. Учтите, что этот параметр влияет только на сообщения, отправляемые самой утилитой pg_ctl. После запуска сервера будет использоваться источник событий, заданный параметром event_source. Если сбой произойдет до того, как сервер успеет применить этот параметр, события будут записаны с использованием источника по умолчанию — PostgreSQL.
-N servicename
Устанавливает имя системной службы Windows, которое также используется как отображаемое имя. По умолчанию — PostgreSQL.
-P password
Пароль для пользователя, от имени которого запускается служба.
-S start-type
Определяет тип запуска службы: auto (автоматически) или demand (вручную). Можно использовать первую букву. По умолчанию: auto.
-U username
Указывает имя пользователя для запуска службы. Для пользователей домена используется формат DOMAIN\username.

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

Утилита поддерживает переменные окружения:

PGCTLTIMEOUT
Задает максимальное время ожидания (в секундах) при запуске или остановке сервера. Если переменная не установлена, используется значение по умолчанию — 60 секунд.
PGDATA
Указывает путь к каталогу данных по умолчанию.

Большинство команд pg_ctl требуют указания расположения каталога с данными. Если переменная окружения PGDATA не задана, необходимо явно указать путь с помощью параметра -D.

Утилита pg_ctl использует переменные окружения, поддерживаемые libpq.

С дополнительными переменными, которые влияют на сервер, можно ознакомиться в postgres.

Файлы​

postmaster.pid
Используется для определения текущего состояния сервера.
postmaster.opts
Если файл присутствует в каталоге данных, его содержимое используется как параметры запуска при выполнении команды restart, если не переопределено с помощью -o. Также содержимое отображается в режиме status.

Примеры​

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

Запуск сервера и ожидание его готовности к приему соединений:

$ pg_ctl start

Запуск сервера на порту 5433 с отключенным fsync:

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

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

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

$ pg_ctl stop

Параметр -m позволяет контролировать каким образом сервер завершает работу:

$ pg_ctl stop -m smart

Перезапуск сервера​

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

Перезапуск сервера с сохранением предыдущих параметров запуска:

$ pg_ctl restart

Но если указан -o, то он заменяет любые предыдущие параметры. Перезапуск сервера с использованием порта 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