★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

pg_ctl

pg_ctlPostgreSQLサーバを初期化、起動、停止、制御する

概要

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_ctlPostgreSQLデータベースクラスタの初期化、PostgreSQLのデータベースサーバ(postgres)を起動、停止、再起動する、あるいは稼働中のサーバの状態を表示するためのユーティリティです。 サーバは手動で起動することも可能ですが、pg_ctlは、ログ出力のリダイレクトや、端末とプロセスグループの適切な分離などの作業を隠蔽してくれます。 さらにシャットダウン制御のための便利なオプションも提供します。

initまたはinitdbモードはPostgreSQLの新しいデータベースクラスタ、つまり、単一のサーバインスタンスで管理されるデータベースの集合を作成します。 このモードはinitdbコマンドを呼び出します。 詳しくはinitdbを参照して下さい。

startモードは、新しいサーバを起動します。 サーバはバックグラウンドで起動され、その標準入力は/dev/null(Windowsの場合はnul)に接続されます。 Unix系のシステムではデフォルトで、サーバの標準出力と標準エラーはpg_ctlの標準出力に転送されます(標準エラー出力には転送されません)。 pg_ctlの標準出力はファイルにリダイレクトするか、例えばrotatelogsなどのログローテーションプログラムのような別プロセスにパイプで渡すべきです。 こうしないと、postgresはその出力を(バックグラウンドから)制御端末に書き出しますので、シェルのプロセスグループから切り離すことができません。 Windowsではデフォルトで、サーバの標準出力と標準エラーは端末に送信されます。 こうしたデフォルトの動作は-lを用いてサーバの出力をログファイルに追加するように変更することができます。 -lまたは出力のリダイレクトのどちらかを使用することを勧めます。

stopモードは、指定されたデータディレクトリで稼働しているサーバを停止(シャットダウン)します。 -mオプションでは、3つの異なる停止方式を選択できます。 smartモードは、新しい接続を禁止してから、全ての接続しているクライアントが切断し、オンラインバックアップがあればそれが終了するまで待ちます。 サーバがホットスタンバイ状態の場合、すべてのクライアント接続が切断された後にリカバリとストリーミングレプリケーションは終了します。 fastモード(デフォルト)はクライアントが切断するまで待たず、かつ、実行中のオンラインバックアップを終了させます。 全ての実行中のトランザクションをロールバックし、クライアントとの接続を強制的に切断した後、サーバを停止します。 immediateモードは、クリーンアップ処理なしで、全てのサーバプロセスを即座に中断します。 これを選択すると、次回のサーバ起動時にクラッシュリカバリサイクルが始まります。

restartモードは、実質的にはstopを実行して、その後、startを実行します。 この時、postgresのコマンドラインオプションを変更、またはサーバの再起動なしには変更できない設定ファイルオプションを変更することができます。 サーバ起動時に相対パスがコマンドラインから使用されていた場合、サーバ起動時と同じカレントディレクトリでpg_ctlを実行しなければ、restartが失敗する可能性があります。

reloadモードは、単にpostgresサーバプロセスにSIGHUPシグナルを送り、(postgresql.confpg_hba.confなどの)設定ファイルの再読み込みを実行させます。 これにより、設定ファイルのオプションで完全なサーバ再起動を必要としないものについて、変更を反映させることができます。

statusモードは指定したデータディレクトリでサーバが稼働しているかどうかを確認します。 稼働している場合はサーバのPIDと、サーバを起動する時に使われたコマンドラインオプションを表示します。 サーバが稼働していない場合、pg_ctlは終了ステータス3を返します。 アクセス可能なデータディレクトリが指定されていない場合、pg_ctlは終了ステータス4を返します。

promoteモードは、指定したデータディレクトリで実行中のスタンバイサーバに、スタンバイモードを終了し、読み書きの操作を開始するように指示します。

logrotateモードはサーバログファイルを回転します。 外部のログ回転ツールでこのモードを使う方法の詳細については、25.3を参照してください。

killモードは指定したプロセスにシグナルを送信します。 これは主に、組み込みのkillコマンドがないMicrosoft Windowsで有用です。 サポートされているシグナル名の一覧を見るには--helpを使ってください。

registerモードはPostgreSQLサーバをMicrosoft Windows上のシステムサービスとして登録します。 -Sオプションにより、auto(システムの起動時に自動的にサービスを開始する)とdemand(要求に応じてサービスを開始する)のいずれかのサービス開始種別を選択できます。

unregisterモードによりMicrosoft Windows上のシステムサービスを登録解除することができます。 これは過去にregisterコマンドによりなされた変更を元に戻します。

オプション

-c
--core-files

実現可能なプラットフォームにおいて、サーバクラッシュ時にcoreファイルを生成できるように関連するソフトリソース制限を上げます。 障害が起きたサーバプロセスからスタックトレースを取得できますので、問題のデバッグや診断の際に有用です。

-D datadir
--pgdata=datadir

データベース設定ファイルのファイルシステム上の場所を指定します。 このオプションが省略された場合、環境変数PGDATAが使われます。

-l filename
--log=filename

サーバログ出力をfilenameに追記します。 そのファイルが存在しない場合は作成されます。 umaskは077に設定されますので、他のユーザからのログファイルへのアクセスはデフォルトでは許可されません。

-m mode
--mode=mode

停止(シャットダウン)モードを指定します。 modesmartfastimmediate、もしくはこの3つのモード名の最初の1文字をとることができます。 このオプションが省略された時はfastがデフォルトとなります。

-o options
--options=options

postgresコマンドに直接渡されるオプションを指定します。 -oは複数回指定することができ、そこで指定されたすべてのオプションが渡されます。

optionsはそれが一つのグループとして渡されるようにするため、通常は単一引用符または二重引用符で括るべきです。

-o initdb-options
--options=initdb-options

initdbコマンドに直接渡されるオプションを指定します。 -oは複数回指定することができ、そこで指定されたすべてのオプションが渡されます。

initdb-optionsはそれが一つのグループとして渡されるようにするため、通常は単一引用符または二重引用符で括るべきです。

-p path

postgresの実行プログラムの位置を指定します。 デフォルトではpostgresの実行プログラムはpg_ctlと同じディレクトリにあるものとみなされます。また、このディレクトリに存在しなければ、構築時に指定したインストールディレクトリが使われます。 このオプションは、何か異例なことをしていてpostgresが見つからないというようなエラーが出ない限り、使う必要はありません。

initモードでは、このオプションは同様にinitdb実行プログラムの場所を指定します。

-s
--silent

エラーメッセージのみを表示し、その他の情報を表示しません。

-t seconds
--timeout=seconds

操作が完了するまで待機する最大の秒数を指定します(オプション-wを参照)。 デフォルトは環境変数PGCTLTIMEOUTの値で、それが設定されていなければ60秒です。

-V
--version

pg_ctlのバージョンを表示し、終了します。

-w
--wait

操作が完了するのを待ちます。 これはstartstoprestartpromoteregisterのモードについてサポートされており、これらのモードについてのデフォルトです。

待機している場合、pg_ctlは繰り返しサーバのPIDファイルを確認し、確認と確認の間は少しの時間スリープします。 起動は、サーバが接続を受け付ける準備ができたことをPIDファイルが示した時に、完了したとみなされます。 停止は、サーバがPIDファイルを削除した時に、完了したとみなされます。 pg_ctlは、起動もしくは停止が成功したかどうかに基づいて終了コードを返します。

操作がタイムアウト(オプション-t参照)までに完了しなかった場合、pg_ctlは非ゼロの終了コードで終了します。 しかし、その操作はバックグラウンドで実行し続け、最終的に成功するかもしれないことに注意してください。

-W
--no-wait

操作が完了するのを待ちません。 オプション-wの反対です。

待機が無効化されていると、要求された操作は実行されますが、それが成功したかどうかのフィードバックがなくなります。 その場合、サーバのログファイルや外部のモニタリングシステムを使って操作の進行状況や成功したかどうかを確認する必要があるでしょう。

PostgreSQLの以前のリリースでは、stopモードを除き、これがデフォルトでした。

-?
--help

pg_ctlコマンドライン引数の説明を表示し、終了します。

指定されたオプションが有効ではあるが、指定の操作モードと関係ないものである場合、pg_ctlはそれを無視します。

Windows用オプション

-e source

Windowsのサービスとして実行する際に、イベントログへの出力用にpg_ctlが使用するイベントソースの名前です。 デフォルトはPostgreSQLです。 これはpg_ctl自体からのメッセージのみを制御することに注意してください。 サーバが起動した後は、event_sourceで指定したイベントソースが使用されます。 サーバが起動の非常に早い段階のパラメータが設定されるより前に障害を起こした場合は、デフォルトのイベントソース名のPostgreSQLを使用するかもしれません。

-N servicename

登録するシステムサービスの名前です。 この名前は、システム名としても表示名としても使用されます。 デフォルトはPostgreSQLです。

-P password

サービスを開始するユーザ用のパスワードです。

-S start-type

システムサービスの起動種類です。 start-typeautodemand、またはこれら2単語の先頭の文字のいずれかです。 このオプションを省略した時はautoがデフォルトとなります。

-U username

サービスを起動するユーザのユーザ名です。 ドメインユーザの場合はDOMAIN\username書式を使用してください。

環境

PGCTLTIMEOUT

起動または終了が完了するまでに待機する秒数のデフォルトの最大値です。 設定されていない場合のデフォルトは60秒です。

PGDATA

デフォルトのデータディレクトリの場所です。

ほとんどのpg_ctlのモードはデータディレクトリの位置を知っている必要があるため、PGDATAが設定されていないときは-Dオプションが必須です。

また、pg_ctlは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(34.15を参照してください)。

サーバに影響を与える他の変数についてはpostgresを参照してください。

ファイル

postmaster.pid

pg_ctlは、データディレクトリのこのファイルを検査して、サーバが現在稼働中かどうかを決定します。

postmaster.opts

このファイルがデータディレクトリにあれば、pg_ctl(のrestartモード)は、-oで上書きされるものを除き、このファイルの内容をオプションとしてpostgresに渡します。 また、このファイルの内容が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"

2行目は再起動(restart)モードで呼び出されるコマンドラインです。

関連項目

initdb, postgres