COPY [ BINARY ] table [ WITH OIDS ]
FROM { 'filename' |
stdin }
[ USING DELIMITERS 'delimiter' ]
COPY [ BINARY ] table [ WITH OIDS ]
TO { 'filename' |
stdout }
[ USING DELIMITERS 'delimiter' ]
COPY は Postgres の テーブルと標準 Unix ファイル間でデータを移動します。 COPY はPostgres バックエンドに対し、直接、ファイルへの読み書きをするように 通告します。ファイルはバックエンドが直接見える形で、その名前も バックエンドの観点から指定されていなければなりません。 stdin または stdout が指定されている場合は、データはクライアントのフロントエンドから バックエンドに流れます。
キーワード BINARY は全てのデータをテキストではなくバイナリ オブジェクトとして書き込まれたり読み込まれるようにします。 普通のコピー命令より速いですが、一般的には移植性がなく、 この要素がデータそのものに大いに依存するとしても、 出来上がったファイルはいくぶん大きくなります。 デフォルトではテキストコピーはデリミタとしてタブ ("\t") 文字を使います。デリミタはキーワード句 USING DELIMITERS で 他のどのような一文字に変更することも出来ます。デリミタ文字 にたまたま一致するデータフィールド中の文字は引用符が付けられ ます。
COPY によって既に値が読み込まれている 何らかのテーブルへのアクセスが選択されなければなりません。 そして、 COPY によって読み込まれる値を 持っているいかなるテーブルに対しても select 権限があり、 また COPY によって値が挿入されるテーブル に対しては、挿入または更新の権限がなければなりません。 バックエンドには、同時に COPY によって 読み書きされるファイルに適切な Unix のパーミッションが与え られている必要があります。
キーワード句 USING DELIMITERS はカラム間で使用される 全てのデリミタ一文字を指定します。 複数の文字がデリミタ文で指定された場合、初めの一文字が使用 されます。
Tip: psql の \copy 命令 と COPY を混同してはいけません。
BINARY オプションなしで COPY TO が使用されると、 生成されたファイルは、それぞれのカラム(属性)がデリミタ文字で区切 られた一行ごとの行(インスタンス)から成ります。 組み込まれたデリミタ文字の始めにはバックスラッシュ文字 ("\") が 付きます。属性値そのものはそれぞれの属性の型に対応した出力関数 によって生成された文字列です。型の出力関数はバックスラッシュ 文字の生成に関与してはなりません。COPY 自身 がこれを取り扱うからです。
それぞれのインスタンスの実際の形式は以下のようになります。
<attr1><separator><attr2><separator>...<separator><attrn><newline>
WITH OIDS が指定された場合、oid が行の先頭に付きます。
COPY がその出力をファイルではなく標準 出力に出す場合、処理の結果、それぞれ分離した行の改行のすぐ 後にバックスラッシュ ("\") と ピリオド(".") を送出します。 同様 COPY が標準入力からデータを読み込む 場合は、 ファイルの終了 (end-of-file) を規定する行の始めの 3 文字 として、改行とそれに引き続くバックスラッシュ ("\") と ピリオド(".") をがあることを前提にします。とは言っても、COPY は この特殊なファイル終了の様式が検出される 以前に正規の EOF を見付けた場合終了します。(バックエンド自身も 引き続いて終了します。)
バックスラッシュには別の特別な意味があります。NULL 属性は "\N" と表現されます。リテラルのバックスラッシュは二つの続いた バックスラッシュ ("\\") と表現されます。リテラルのタブ文字は バックスラッシュとタブで表現されます。リテラルの改行はバック スラッシュと改行で表現されます。Postgres で 生成されていないテキストデータを読み込む時は、正常に読み込みが 出来るようにバックスラッシュ文字 ("\") を二つのバックスラッシュ ("\\") に変換する必要があります。
COPY BINARY の場合、ファイルの初めの 4 バイト はそのファイルの中のインスタンスの数を示しています。 この数がゼロの場合は、COPY BINARY はファイル の終了までデータを読み込みに行きます。数が指定されていると、 その数のインスタンスが読み込まれた時点で読み込みを中止します。 ファイル内に残っているデータは無視されます。
ファイルの中のそれぞれのインスタンスの形式は以下のようになって います。この形式は全くこのままでなくては なりません。符号なしの 4 バイト整数の値は下記のテーブルで uint32 と呼ばれています。
Table 14-1. バイナリコピーファイルの内容
| ファイルの先頭 | |
| uint32 | タプルの数 |
| For each tuple | |
| uint32 | タプルデータの総ての長さ |
| uint32 | (指定されている場合) oid |
| uint32 | null 属性の数 |
| [uint32,...,uint32] | 0 から数え始めた属性の属性番号 |
| - | <tuple data> |
次の例ではフィールドのデリミタとして縦棒 ("|") を使って テーブルを標準出力に出します。
COPY country TO stdout USING DELIMITERS '|';
Unix ファイルからデータをテーブル "country" にコピーします。
COPY country FROM '/usr1/proj/bray/sql/country_data';
この例は stdin からテーブルにコピー する時の有効なデータを示しています。 (したがって、最終行に終結の指定があります。)
AF AFGHANISTAN AL ALBANIA DZ ALGERIA ... ZM ZAMBIA ZW ZIMBABWE \.
Linux/i586 マシンでのバイナリ形式による同じデータの出力です。 データは Unix のユーティリティ od -c で フィルタをかけた後のものです。テーブルには 3 つのフィールドが あります。初めは char(2) で二番目は text です。全ての行は第三番目のフィールド に null 値を持っています。 char(2) が null で埋められて 4 バイトに そしてテキストのフィールドはその長さが前に来ていることに注意 して下さい。
355 \0 \0 \0 027 \0 \0 \0 001 \0 \0 \0 002 \0 \0 \0
006 \0 \0 \0 A F \0 \0 017 \0 \0 \0 A F G H
A N I S T A N 023 \0 \0 \0 001 \0 \0 \0 002
\0 \0 \0 006 \0 \0 \0 A L \0 \0 \v \0 \0 \0 A
L B A N I A 023 \0 \0 \0 001 \0 \0 \0 002 \0
\0 \0 006 \0 \0 \0 D Z \0 \0 \v \0 \0 \0 A L
G E R I A
... \n \0 \0 \0 Z A M B I A 024 \0
\0 \0 001 \0 \0 \0 002 \0 \0 \0 006 \0 \0 \0 Z W
\0 \0 \f \0 \0 \0 Z I M B A B W E
COPY はカラムのデフォルトに対し、ルールも アクションも呼び出しません。しかし、トリガは呼び出されます。
COPY は最初のエラーで操作を打ち切ります。 このことは COPY FROM イベントでは問題に なりませんが、COPY TO ではもちろん 目的リレーションが一部修正されます。 コピーが失敗した場合 VACUUM 問合せ で掃除してください。
Postgres バックエンドの現在の作業ディレクトリは通常 ユーザの作業ディレクトリと異なりますので、(追加した パスの情報がないい限り)ファイル "foo" への コピーは疑うことを知らないユーザに予期せぬ結果をもたらす ことがあります。この場合、 foo は 最終的に $PGDATA/foo になります。 一般的に、バックエンドサーバマシンに出て来るフルパス名を コピーするファイルの指定時に使用しなければなりません。
COPY に対する引数として使用される ファイルはローカルディスク上またはネットワークファイル システムとしてデータベースサーバマシンがアクセスできる 様になっているか、存在していなければなりません。
あるマシンから他のマシンに TCP/IP 接続がされているとき、そして 目的ファイルが指定されているとき、その目的ファイルはユーザの マシンではなくバックエンドが走っているマシン上に書かれます。