pg_ctl
pg_ctl — инициализировать, запустить, остановить или управлять сервером Postgres Pro
Синтаксис
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 — это утилита для начальной инициализации, запуска, остановки, повторного запуска и управления кластером баз данных Postgres Pro (postgres). Сервер можно стартовать в ручном режиме, но pg_ctl реализует задачи направления вывода в журнал и отсоединения от терминала и группы процессов, а также предоставляет удобный интерфейс остановки кластера.
Команда init
(initdb
) создаёт кластер баз данных Postgres Pro, то есть коллекцию баз данных, которой будет управлять один экземпляр сервера. Эта команда вызывает программу initdb
. За подробностями обратитесь к initdb.
Команда start
запускает сервер. Процесс запускается в фоне, а стандартный ввод связывается с /dev/null
(или nul
в Windows). По умолчанию в Unix-подобных системах вывод и ошибки сервера пишутся в устройство стандартного вывода (не ошибок) pg_ctl. Вывод pg_ctl следует перенаправить в файл или процесс, например, приложение ротации журналов rotatelogs; иначе postgres
будет писать вывод в управляющий терминал (в фоновом режиме) и останется в группе процессов оболочки. В Windows сообщения и ошибки сервера по умолчанию перенаправляются в терминал. Это поведение по умолчанию можно изменить и направить вывод сервера в файл, добавив ключ -l
. Предпочтительными вариантами является использование -l
или перенаправление вывода.
Команда stop
останавливает сервер, работающий с указанным каталогом данных. Параметр -m
позволяет выбрать один из трёх режимов остановки. Режим «Smart» запрещает новые подключения, а затем ожидает отключения всех существующих клиентов и завершения всех текущих процессов резервного копирования. Если сервер работает в режиме горячего резерва, восстановление и потоковая репликация будут прерваны, как только отключатся все клиенты. Режим «Fast» (выбираемый по умолчанию) не ожидает отключения клиентов и завершает все текущие процессы резервного копирования. Все активные транзакции откатываются, а клиенты принудительно отключаются, после чего сервер останавливается. Режим «Immediate» незамедлительно прерывает все серверные процессы, не выполняя процедуру штатной остановки. Этот вариант влечёт необходимость выполнить восстановление после сбоя при следующем запуске сервера.
Примечание
Когда встроенный пул соединений включён и обслуживает клиентские сеансы, отключение в режиме «Smart» осуществляется как «Fast».
Команда restart
по сути производит остановку и последующий запуск сервера. Это позволяет изменить параметры командной строки postgres
либо применить изменения в файле конфигурации, не вступающие в силу без перезапуска сервера. Если в командной строке при запуске сервера указывались относительные пути, команда restart
может не выполниться, если вызвать pg_ctl не в том каталоге, где производился предыдущий запуск.
Команда reload
просто посылает процессу сервера postgres
сигнал SIGHUP, получив который он перечитывает свои файлы конфигурации (postgresql.conf
, pg_hba.conf
и т. д.). Это позволяет применить изменения параметров в файле конфигурации, не требующие полного перезапуска сервера.
Команда status
проверяет, работает ли сервер в указанном каталоге данных. Если да, она выдаёт PID сервера и параметры командной строки, с которыми он был запущен. Если сервер не работает, pg_ctl возвращает код завершения 3. Если в параметрах не указан доступный каталог данных, pg_ctl возвращает код завершения 4.
Команда promote
указывает серверу, работающему в режиме резерва с указанным каталогом данных, выйти из этого режима и начать операции чтения/записи.
Команда logrotate
прокручивает файл журнала сервера. Подробнее о том, как использовать это с внешними средствами прокрутки журнала, рассказывается в Разделе 24.3.
Команда kill
передаёт сигнал заданному процессу. Прежде все это полезно в Microsoft Windows, где отсутствует встроенная команда kill. Для получения списка имён поддерживаемых сигналов воспользуйтесь ключом --help
.
Команда register
регистрирует сервер Postgres Pro в качестве системной службы в 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
.Если ожидание отключено, запрошенное действие вызывается, но о его результате ничего не известно. В этом случае для проверки текущего состояния и результата операции потребуется обратиться к файлу журнала сервера или воспользоваться внешней системой мониторинга.
В предыдущих выпусках Postgres Pro этот режим действовал по умолчанию (кроме команды
stop
).-?
--help
Вывести справку по команде pg_ctl и прервать выполнение.
Если некоторый параметр является допустимым, но не применим к выбранному режиму работы, pg_ctl игнорирует его.
Параметры, специфичные для Windows
-e
источник
Имя источника событий, с которым pg_ctl будет записывать в системный журнал события при запуске в виде службы Windows. Имя по умолчанию —
Postgres Pro
. Заметьте, что это влияет только на сообщения, которые выдаёт сам pg_ctl; как только сервер запустится, он будет использовать источник событий, заданный в event_source. Если произойдёт ошибка при запуске сервера на ранней стадии, прежде чем будет считан этот параметр, он может также выдавать сообщения с источником по умолчаниюPostgres Pro
.-N
имя_службы
Имя регистрируемой системной службы. Оно станет и собственно именем службы, и отображаемым именем. По умолчанию —
Postgres Pro
.-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"
Во второй строке показывается команда, которая будет выполнена в режиме перезапуска.