名前
pg_batch -- SQLジョブを並列実行します。
概要
pg_batch [OPTIONS] FILENAME [args...]
- FILENAME [args...]
- ジョブ一覧取得スクリプトのファイル名を指定します。 ジョブ一覧取得スクリプトがパラメータを持つ場合は、渡したいパラメータを args に指定します。 また、FILENAMEに「-」を指定することで標準入力からスクリプトを読み込むことができます。
オプション OPTIONS には以下を指定できます。 詳細はオプションを参照してください。
- 固有オプション
- -a, --all : 全てのデータベースに対して実行します
- -j, --jobs=CONNECTIONS : ジョブの並列実行数
- -t, --timeout=TIMEOUT : タイムアウト時間(秒)
- 接続オプション
- -d, --dbname=DBNAME : 接続するデータベース
- -h, --host=HOSTNAME : データベースサーバホスト、またはソケットディレクトリ
- -p, --port=PORT : データベースサーバのポート
- -U, --username=USERNAME : このユーザとして接続します
- -W, --password : パスワード入力を強制します
- 一般オプション
- -e, --echo : サーバに送信するSQLを表示します
- -E, --elevel=LEVEL : ログ出力レベルを設定します
- --help : ヘルプを表示し、終了します
- --version : バージョン情報を出力し、終了します
説明
pg_batch は PostgreSQL のためのSQLジョブ実行プログラムです。 ジョブ一覧生成するスクリプトを SQL として外部から与え、その出力 SQL をジョブとしてシリアルまたはパラレルに実行します。
pg_batch は以下の処理を行います。
- 与えられたジョブ一覧取得スクリプトを実行し、ジョブの一覧を取得します。
- 取得したジョブ一覧の各ジョブを、それぞれ異なるトランザクションを用いて実行します。
- ジョブの実行は、指定された数のセッションを使って並行して行います。
- ジョブの内容、開始時間、終了時間、成否をログとしてコンソールに出力します。
- タイムアウトが指定された場合は、指定した時間を経過すると、実行中のジョブをキャンセルし、未実行のジョブをスキップします。
実用的なサンプルとして、vacuumdb の代わりに利用できる「VACUUMジョブ生成スクリプト」が添付されています。
使用例
test というデータベースに VACUUM ジョブを行うには、下記のコマンドを実行します。
$ pg_batch -d test $PGHOME/share/contrib/pg_batch_vacuum.sql
すべてのデータベースに user-jobs.sql というジョブを行うには、下記のコマンドを実行します。
$ pg_batch --all user-jobs.sql
オプション
pg_batch では、下記のコマンドライン引数を指定できます。
固有オプション
- -a
--all - 全てのデータベースを対象にジョブを行います。 ジョブはそれぞれのデータベースで順番に実行されます。 -j オプションを指定しても、異なるデータベースのジョブを並行して実行することはできません。 また、ジョブ一覧取得スクリプトは全てのデータベースで共通のものを使用します。
- -j CONNECTIONS
--jobs=CONNECTIONS - ジョブの並列実行数を指定します。指定可能な範囲は「1～32」です。(デフォルト:1)
- -t TIMEOUT
--timeout=TIMEOUT - タイムアウト時間を秒単位で指定します。「0」を指定した場合はタイムアウトは発生しません。(デフォルト:0)
接続オプション
PostgreSQLに接続するためのパラメータです。
-
-d DBNAME
--dbname=DBNAME - ジョブを行うデータベース名を指定します。 データベース名が指定されておらず、--all も指定されていない場合、データベース名はPGDATABASE環境変数から読み取られます。 この変数も設定されていない場合は、接続時に指定したユーザ名が使用されます。
- -h HOSTNAME
--host=HOSTNAME - サーバが稼働しているマシンのホスト名を指定します。ホスト名がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。
- -p PORT
--port=PORT - サーバが接続を監視するTCPポートもしくはUnixドメインソケットファイルの拡張子を指定します。
- -U USERNAME
--username=USERNAME - 接続するユーザ名を指定します。
- -W
--password - データベースに接続する前に、pg_batch は強制的にパスワード入力を促します。 サーバがパスワード認証を要求する場合 pg_batch は自動的にパスワード入力を促しますので、これが重要になることはありません。 しかし、pg_batch は、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 こうした余計な接続試行を防ぐために -W の入力が有意となる場合もあります。
一般オプション
- -e
--echo - サーバに送信するSQLを表示します。
- -E
--elevel - ログ出力レベルを設定します。 DEBUG, INFO, NOTICE, WARNING, ERROR, LOG, FATAL, PANIC から選択します。 デフォルトは INFO です。
- --help
- pg_batch の使用方法について表示します。
- --version
- pg_batch のバージョン情報を表示します。
環境変数
-
PGDATABASE
PGHOST
PGPORT
PGUSER - デフォルトの接続パラメータです。
また、このユーティリティは、他のほとんどの PostgreSQL ユーティリティと同様、 libpq でサポートされる環境変数を使用します。詳細については、環境変数の項目を参照してください。
使用上の注意と制約
pg_batch を使用する際には、以下の使用上の注意と制約があります。
- SQLが結果の値を返す場合でも、値は無視されます。
- 正否の判定は、SQL がコミットできたか否かだけを基準に判断します。
- ジョブはSQL 1コマンドでなければいけません。ジョブのフロー制御はできません。
- 代わりに、ジョブをストアド関数として登録し、その関数を pg_batch で実行してください。
- リソースや負荷の制限はできません。
- 接続数 (-j オプション) や vacuum_cost_delay (VACUUM の場合) で別途制御してください。
- 異なるデータベースのジョブを並行して実行できません。
- -j オプションにより並列化されるのは、同一のデータベース内のジョブだけです。 複数のデータベースのジョブを並列化する場合には、pg_batch を複数回実行してください。
- データベース毎に異なるジョブ一覧取得スクリプトは指定できません。
- -a オプションで全てのデータベースを対象とする場合は、ジョブ一覧取得スクリプトは共通のものを使用します。 データベース毎にジョブ一覧取得スクリプトを変えたい場合には、各データベースに対して pg_batch を実行してください。
詳細
全体構成
pg_batch はシングルスレッドで動作しますが、複数のセッション (-j で数を指定) を使って非同期クエリでジョブSQLを実行するため、データベース・サーバで複数のジョブを並行して実行することができます。
ジョブ一覧取得スクリプト
ジョブ一覧取得スクリプトは、(query AS text, priority AS float8) の2列を含む複数の行を返却する SQL です。 "query" にはジョブとして実行する SQL を格納し、"priority" にはジョブの優先度が格納されるようスクリプトを設計します。 一般的には、ジョブ一覧取得スクリプトは以下のような形式になります。
SELECT query, priority FROM ジョブ一覧 WHERE 今日行うべき;
なお、"priority" のカラムは省略することもできます。省略された場合は全てのジョブの "priority" を「0」として扱います。
pg_batch は "priority" の大きい順にジョブを実行します。また、タイムアウトや Ctrl+C によりジョブがキャンセルされた場合に、 "priority" が「0」より大きい未実行のジョブが存在すると警告します。 これらの事を考慮し、ジョブを実行する時の条件に応じて適切な "priority" を設定してください。 例えば、1日1回ジョブを実行する場合には、以下のようなルールで "priority" を設定します。
- "priority" が正のジョブ : 今日中に必ず実行するジョブ
- "priority" が負のジョブ : 時間に余裕があれば実行するジョブ
タイムアウト
タイムアウトを設定した場合、タイムアウト時間を経過すると実行中のジョブをキャンセルし、未実行のジョブをスキップします。 この時、priority" が「0」より大きい未実行のジョブが存在する場合は警告ログとして該当のジョブを表示します。それ以外のジョブは通常のログとして表示します。 また、"priority" が「0」より大きい未実行のジョブが存在した場合は pg_batch の終了値が「1」となります。
また、pg_batch が割り込み終了(Ctrl+C) された場合もタイムアウトと同様に、実行中のジョブをキャンセルし、 未実行のジョブをログに表示します。ただし、割り込み終了(Ctrl+C) の場合は pg_batch の終了値が不定となります。
ログメッセージ仕様
pg_batch が出力するログのメッセージについて説明します。
- データベース単位のジョブの件数表示
INFO: DATABASE 'データベース名' (ジョブ数 jobs)
- ジョブ開始時のメッセージ
INFO: [ジョブ番号/全体ジョブ数] START: ジョブの開始日時(YYYY-MM-DD HH:MI:SS) INFO: [ジョブ番号/全体ジョブ数] QUERY: SQL
- ジョブ終了時のメッセージ
/* ジョブが成功した場合 */ INFO: [ジョブ番号/全体ジョブ数] SUCCESS: ジョブの終了日時(YYYY-MM-DD HH:MI:SS) (経過時間(HH:MM:SS)) /* ジョブが失敗した場合 */ WARNING: [ジョブ番号/全体ジョブ数] FAILED: ジョブの終了日時(YYYY-MM-DD HH:MI:SS) (経過時間(HH:MM:SS))
- タイムアウト発生時のメッセージ
/* タイムアウト発生までに実行したジョブの内、失敗したジョブが存在しない場合 */ INFO: TIMEOUT タイムアウト発生日時(YYYY-MM-DD HH:MI:SS) /* タイムアウト発生までに実行したジョブの内、失敗したジョブが存在する場合 */ WARNING: TIMEOUT タイムアウト発生日時(YYYY-MM-DD HH:MI:SS)
- ジョブのスキップ時のメッセージ
/* 優先度の低いジョブの場合 (priority < 0) */ INFO: [ジョブ番号/全体ジョブ数] SKIP: SQL /* 優先度の高いジョブの場合 (priority >= 0) */ WARNING: [ジョブ番号/全体ジョブ数] SKIP: SQL
- エラー発生時のメッセージ
ERROR: エラーメッセージ
VACUUM ジョブ
VACUUM ジョブは、autovacuum と同様の VACUUM の必要性判定を行い、デッドタプル数が多い または トランザクションID周回が間近に迫ったテーブルのみを VACUUM します。vacuumdb コマンドと比較すると、VACUUM が不要なテーブルには VACUUM を行わないことと、VACUUM を複数セッションから並行して実施できる利点があります。
autovacuum が VACUUM を行う閾値を 100% とすると、規定の設定では以下の図に示す判定を行います。 autovacuum の閾値については、PostgreSQL 文書「自動バキュームデーモン」を参照してください。
インストール方法
pg_batch のインストールは、標準のcontribモジュールと同様です。
ビルド
pgxs を使ってビルドできます。
$ cd pg_batch $ make USE_PGXS=1 $ make USE_PGXS=1 install
データベースへの登録
pg_batch プログラム単体では、特にデータベースへの登録作業は必要ありません。 添付の「VACUUMジョブ生成スクリプト」を利用する場合には、対象のデータベースに対して $PGHOME/share/contrib/pg_batch.sql を実行してください。
$ psql -d dbname -f $PGHOME/share/contrib/pg_batch.sql
動作環境
- PostgreSQLバージョン
- PostgreSQL 8.4, 9.0
- OS
- RHEL 5.2, Windows XP SP3