pg_ctl
Пред. НаверхСерверные приложения PostgreSQLНачало След.

pg_ctl

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

Синтаксис

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

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

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

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

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

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

pg_ctl promote [-D каталог_данных] [-W] [-t секунды] [-s]

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

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

В системах Microsoft Windows также:

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

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

Описание

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

Команда init (initdb) создаёт кластер баз данных PostgreSQL, то есть коллекцию баз данных, которой будет управлять один экземпляр сервера. Эта команда вызывает программу 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 может не выполниться, если вызвать pg_ctl не в том каталоге, где производился предыдущий запуск.

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

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

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

Команда logrotate прокручивает файл журнала сервера. Подробнее о том, как использовать это с внешними средствами прокрутки журнала, рассказывается в Разделе 25.3.

Команда kill передаёт сигнал заданному процессу. Прежде все это полезно в Microsoft Windows, где отсутствует встроенная команда kill. Для получения списка имён поддерживаемых сигналов воспользуйтесь ключом --help.

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

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

Параметры

-c
--core-files

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

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

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

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

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

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

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

-o параметры
--options=параметры

Указывает параметры, которые будут передаваться непосредственно программе postgres. Ключ -o можно указывать несколько раз, при этом ей будут переданы параметры из всех ключей.

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

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

Указывает параметры, которые будут передаваться непосредственно программе initdb. Ключ -o можно указывать несколько раз, при этом ей будут переданы параметры из всех ключей.

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

-p путь

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

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

-s
--silent

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

-t секунды
--timeout=секунды

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

-V
--version

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

-w
--wait

Ждать завершения операции. Этот режим поддерживается (и действует по умолчанию) для команд start, stop, restart, promote и register.

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

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

-W
--no-wait

Не ждать завершения операции. Этот режим противоположен режиму -w.

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

В предыдущих выпусках PostgreSQL этот режим действовал по умолчанию (кроме команды stop).

-?
--help

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

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

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

-e источник

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

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

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

-P пароль

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

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

Тип запуска системной службы. В качестве значения тип-запуска можно задать auto, demand или первую букву этих слов. По умолчанию выбирается тип auto.

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

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

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

PGCTLTIMEOUT

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

PGDATA

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

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

Список дополнительных переменных, влияющих на работу сервера, можно найти в postgres.

Файлы

postmaster.pid

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

postmaster.opts

Если файл существует в каталоге хранения данных, то pg_ctl (при restart) передаст его содержимое в качестве аргументов postgres, если не указаны иные значения в -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
Пред. Наверх След.
pg_controldata Начало pg_resetwal