---

pg_bulkload ホームページへようこそ

---

pg_bulkload は PostgreSQL 向けの高速データロードユーティリティです。

pg_bulkload プロジェクトは NTT OSS センタから PostgreSQL のコミュニティへ貢献するものとして pgFoundry に登録されているプロジェクトの一つです。

pgFoundry のページはこちらです： http://pgfoundry.org/projects/pgbulkload
ここでダウンロード、 ドキュメントの入手、バグレポート、メーリングリストの閲覧・購読などが行えます。

詳細なドキュメントは こちらから入手可能です。 日本語ドキュメントは「ランゲージ」で"Japanese" を選択し、"Go"を押すと表示されます。

Here is an English page.

目次

• README
• Performance result

はじめに

pg_bulkloadは一定の制約条件の下で大量のデータを高速にロードするためのプログラムです。

大量のデータを投入するような状況では、細かなチェックは省いてでもいいからとにかく 高速にデータをロードしたいという場面があります。たとえば、あるデータベースに格納 されている情報を別のデータベースへ移送するような状況や、これから投入しようとする データの整合性がすでに別のツールで保証されているような状況がこれにあたります。 このような状況を想定して pg_bulkload は開発されました。 したがって、整合性を確認できていないデータのロードに対して、 pg_bulkload の使用 は適していません。この場合にはPostgreSQLがデータロードのためにもともと用意して いる COPY コマンドの利用をお勧めします。 注意点、使用方法を十分に理解した上で、pg_bulkload をご利用ください。

構成

pg_bulkloadを利用するユーザが直接扱うプログラムは以下の二つです。

pg_bulkload

データのロードを行うために呼び出すプログラムです。内部でpg_bulkload() ユーザ定義 関数を呼び出して、PostgreSQLサーバ内で実際のロード処理を行います。pg_bulkload() ユーザ定義関数は、pg_bulkloadのインストール時に作成されます。

postgresql スクリプト

pg_ctlコマンドのラッパコマンドで、PostgreSQLサーバを起動・停止するプログラムです。 postgresqlスクリプトの内部でpg_ctlコマンドを呼び出しています。 また、pg_bulkloadによるロード中にサーバがダウンした場合、pg_bulkloadコマンドを呼 び出して自動的に独自のリカバリを行う機能を持っています。 pg_bulkload利用環境下では、必ずこのpostgresqlスクリプトを使用してください。

下記の"注意点"を必ず読んでください。特に、

• pg_bulkload を DIRECT モードで使うとき (WAL 書き込みをスキップします: デフォルトの設定です)
もしくは
• Windows 環境で使うとき(今のところ postgresql.bat は用意していません。)

インストール

環境

pg_bulkload をインストールする前に以下を実行しているものとします。
• PostgreSQL がインストールされていること
• PostgreSQLのインストールで使用したソースツリーが存在していること
• initdbを実行し、データベースクラスタが作られていること

インストール手順

インストール手順は次の通りです。インストール先のディレクトリへのアクセス権限は正しく与えられているものとします。

$ cd [directory where postgresql-8.2or3.X.tar.gz is untared]/contrib/
$ tar zxvf pg_bulkload-2.3.X.tar.gz
$ cd pg_bulkload
$ make
$ make install
$ mkdir $PGDATA/pg_bulkload
$ postgresql start
$ psql -f $PGHOME/share/contrib/pg_bulkload.sql database_name

使い方

次の 3ステップにより、pg_bulkload でロードすることが可能です。

1. ロードに関する設定を記述する制御ファイル "sample_csv.ctl" もしくは "sample_bin.ctl" を編集します。ロード対象のテーブル名、入力ファイルの絶対パスなどを指定します。
2. $PGDATA/pg_bulkload ディレクトリが存在することを確認してください。そのディレクトリにはロードステータスファイルが作成されます。
3. 制御ファイルを引数としてコマンドを実行します。引数の制御ファイルは相対パスで指定可能です。

   
   $ pg_bulkload sample_csv.ctl 
   

制御ファイル

次のオプションを指定可能です。pg_bulkload パッケージに含まれる sample_csv.ctl や sample_bin.ctl もあわせて参照してください。

CSV/固定長 フォーマット共通

• TABLE : [schema_name.]table_name
• INFILE : 入力データの位置(絶対パス)
• TYPE : CSV もしくは FIXED
• LOADER : DIRECT もしくは BUFFERED
  • DIRECT : 高速ですが特殊なリカバリ手順が必要です。WALをスキップし、共有バッファも汚しません。 この設定がデフォルトです。
  • BUFFERED : 特殊なリカバリは不要です。ただし、WALを書き、共有バッファも汚します。
• MAX_ERR_CNT : ロードを打ち切るエラーのカウントです。デフォルトは 0 (エラーが発生しても流しきります)。
• OFFSET : 先頭から何行をスキップするかを指定します。デフォルトは 0 です。
• LIMIT : ロード行数を指定します。デフォルトは指定なし(全行ロード)です。

CSV フォーマット

• DELIMITER : デリミタを指定します。デフォルトは「,」です。ASCII文字(1バイト文字)でなければなりません。
• QUOTE : 引用符を指定します。デフォルトは「"」です。ASCII文字(1バイト文字)でなければなりません。
• ESCAPE : エスケープ文字を指定します。デフォルトは「"」です。ASCII文字(1バイト文字)でなければなりません。
• NULL : NULL 値を表す文字列を指定します。デフォルトは空文字列(長さ 0 の文字列）です。
• FORCE_NOT_NULL : 入力ファイル中の表現がNULL値文字列であってもNULLとして扱わないカラムを 1行1カラム名で指定します。複数個指定することが可能です。

固定長フォーマット

• COL : 入力ファイルのカラムフォーマット
  • COL TYPE(N) : N バイトの長さを持つ型です。 TYPE は CHAR, VARCHAR, INTEGER または FLOAT でなければなりません。 CHAR と VARCHAR の場合、入力データがテキストであることを表します。 INTEGER と FLOAT の場合はバイナリであることを表します。
  • COL TYPE : デフォルトの長さを持つ型です。 TYPE は以下のうちの一つでなければなりません。
    • SMALLINT = INTGEGER(2)
    • INTEGER = INTEGER(4)
    • BIGINT = INTEGER(8)
    • FLOAT = FLOAT(4)
    • DOUBLE = FLOAT(8)
    • COL TYPE(N+M) : M バイト分オフセットされた N バイトを指定します。
    • COL TYPE(N:M) : N バイト目から始まり M バイト目までを指定します。
    • COL N : COL CHAR(N) と同じです。後方互換のために残されています。
  • PRESERVE_BLANKS : {YES|NO}. YES の場合、 "COL N" を "COL CHAR(N)" とみなします。 NO の場合、 "COL VARCHAR(N)"とみなします。デフォルトは NO です。
  • STRIDE : 行の長さです。行の末尾を捨てる場合に使います。 デフォルトでは指定は無く、行の末尾は捨てません。

Reminder

• ダイレクトロードで使用する場合(LOAD=DIRECT, which is the default)、以下のことに注意しなければなりません：

  PostgreSQL 起動手順

  pg_bulkload がクラッシュし、.loadstatus ファイルが $PGDATA/pg_bulkload に残っていた場合、 データベースは pg_bulkload 独自のリカバリ手順によってリカバリする必要があります。 これは "pg_bulkoad -r" コマンドを "pg_ctl start" より前に実行することにより行います。 PostgreSQL の起動・停止を postgresql スクリプトにより行うことで、このリカバリをし忘れることを防ぎます。 postgresql スクリプトは内部的に "pg_bulkload -r" を実行し、続けて "pg_ctl start" を行っています。 そのためダイレクトロードの利用環境下では、pg_ctl を直接使わずに、 postgresql スクリプトを利用することをお勧めいたします。

  Windows オペレーティングシステム上で pg_bulkload を使う場合、postgresql スクリプトは pg_bulkload パッケージに同梱されていません。 そのため、リカバリ時には "pg_bulkload -r" を手動で実行する必要があります。

  PITR

  WAL を残さないために、PITR によるアーカイブログリカバリは利用できません。 もし PITRを利用する場合には、ロード終了後に対象のデータベースのバックアップを取ってください。

  $PGDATA/pg_bulkload 内のロードステータスファイル

  $PGDATA/pg_bulkload ディレクトリ中のロードステータスファイル (*.loadstatus) は絶対に削除してはいけません。 pg_bulkload のリカバリのために必ず必要になるからです。

  kill -9は使わない

  pg_bulkload を "kill -9" を使って停止させるのはできる限りやめてください。 もし実行すると postgresql スクリプトによるリカバリが実行されます。

• その他の制限は次の通りです。:

  制約

  ロード時のデータの整合性は、一意制約と NULL制約のみ確認します。 その他の制約(参照整合性制約など)は確認しません。 入力データセットの妥当性についてはユーザにより保証してください。

オプションツール : pg_timestamp_in

pg_bulkload に加えて、次のユーザ定義関数がタイムスタンプ文字列のパースのオーバヘッドをスキップするために提供されています。 これも pg_bulkload のパッケージに含まれています。

pg_timestamp_in

2007-01-01 12:34:56

• 年/月/日/時/分/秒 は数字(0x30-0x39)
• 年と月、月と日の間はハイフン(0x2D)
• 年月日と時分秒の間はASCII空白(0x20)
• 時と分、分と秒の間はコロン(0x3A)
• これ以外に、余分な空白やタブを加えてはいけません。

インストール

インストール手順は以下の通りです。インストール先のディレクトリへのアクセス権限は正しく与えられているものとします。

$ cd [directory where postgresql-8.2or3.X.tar.gz is untared]/contrib/
$ tar zxvf pg_bulkload-2.3.X.tar.gz
$ cd pg_bulkload
$ make
$ make install
$ postgresql start
$ psql -f $PGHOME/share/contrib/pg_timestamp.sql database_name

注意点

タイムゾーンを含む入力文字列は高速化の対象外です。 また、上記のフォーマットに合致しないものはPostgreSQLの書式変換ルーチンを通します。 この場合の処理速度は従来のものと同じか、もしくは遅くなります。

pg_timestamp_in は timestamp 型データを高速に読む機能を提供するものの、 通常使われる PostgreSQL の内部関数を置き換えます。 pg_timestampを登録すると、pg_bulkloadに限らず、timestamp型を利用する全ての処理 はこの関数を使うことになります。すなわち、COPYやINSERTでもこの関数を利用します。 この影響を避けるためには、pg_timestamp_in をロードの時だけ利用し、 通常時はアンインストールするなどの対応が必要です。

作者

NTT OSS センタ
Copyright(C) 2007-2008 日本電信電話株式会社

概要

• 1GB の CSV データを COPY と pg_bulkload それぞれでロードします。
• ロード対象テーブル : 4GB のデータがすでに存在しているものとします。
• テーブル定義 : DBT-2(TPC-Cライクなベンチマークキット)で使われる customer テーブルです。
• インデックス定義 : 2つのインデックスを定義しています(PK(int 1つからなるカラム), 非ユニークインデックス(int 1つからなるカラム))

結果

• (インデックス定義済みテーブルへの COPY) vs pg_bulkload

項目	8.1.8	8.2.3
COPY(秒)	1601.4	1586.2
pg_bulkload(秒)	147.7	131.8
比	10.8	12.0

• ((インデックス定義がないテーブルへの COPY) + CREATE INDEX) vs pg_bulkload

項目	8.1.8	8.2.3
COPY(秒)	548.9	596.5
pg_bulkload(秒)	147.7	131.8
比	4.17	4.04

• 結果詳細

項目	8.1.8	8.2.3
pg_bulkload（インデックス定義済みテーブル）	147.7	131.8
pg_bulkload (インデックスなしテーブル)	72.5	72.9
COPY (インデックス定義済みテーブル)	1601.4	1586.2
COPY (インデックスなしテーブル)	127.7	140.2
CREATE INDEX	468.8	408.7

• 測定条件

項目	値
マシン	PowerEdge1900
CPU	Dual Core Intel(R) Xeon(R) Processor5050 CPU3.0GHz
メモリ	2GB （512MB*4）
ディスクサイズ (OSがインストールされているディスク)	SerialATAⅡ80GB
ストレージサイズ (データベースクラスタが格納されているディスク)	RAID0 1.2TB
RAID コントローラキャッシュ	128MB
ハイパースレッド	ON
OSバージョン	RHEL ES release4 update4(32bit)
カーネルバージョン	2.6.9-42.ELsmp
libcバージョン	2.3.4
PostgreSQLバージョン	8.1.8/8.2.3
shared_buffers	1024
checkpoint_segments	1000
checkpoint_timeout	3600
work_mem	1024
maintenance_work_mem	16384
テーブル定義	DBT-2 customer table
インデックスカラム	c_id (PRIMARY KEY)
	c_d_id (非ユニーク B-Tree)
制約	非NULL (全カラム)
既存のデータ量	16,777,216 tuples(4GB)
新規ロードデータ量	4,194,304 tuples(1GB)
入力ファイルタイプ	CSV
pg_bulkload バージョン	pg_bulkload-2.1.2(PG-8.1.8)/2.2.0(PG-8.2.3)