COPY [ BINARY ] table [ WITH OIDS ]
FROM { 'filename' | stdin }
[ [USING] DELIMITERS 'delimiter' ]
[ WITH NULL AS 'null string' ]
COPY [ BINARY ] table [ WITH OIDS ]
TO { 'filename' | stdout }
[ [USING] DELIMITERS 'delimiter' ]
[ WITH NULL AS 'null string' ]
フィールド書式の取り扱いを変更し、テキストではなくバイ ナリ形式で全データの読み書きを行ないます。
既存のテーブル名。
各行に対し、内部用の一意なオブジェクト ID(OID) をコピー します。
入出力ファイルの Unix 絶対パス名。
パイプもしくは端末から入力することを指定します。
パイプもしくは端末に対して出力することを指定します。
入出力フィールドを区切る文字。
NULL 値を表す文字列。 デフォルトは、"\N" (バックスラッシュとN)です。 例えば、空文字に変更することもできます。
Note: COPY FROM の場合、この文字に一致する全てのデータ項目は NULL 値として保存されます。 ですので、同じ文字を使用して COPY TO を行なっている ことを確認する必要があります。
COPY は Postgres のテーブルと標準ファ イルシステム上のファイルとの間でデータを移します。 COPY は Postgres のバックエンドに対し て、直接ファイルを読み書きするよう指示します。 このファイルは、バックエンドから直接参照できるものでなけ ればならず、バックエンドの視点からそのファイル名を指定し なければなりません。 stdin や stdout が指定された場合、データはクライアントフロントエンドから バックエンドに渡されます。
BINARY キーワードは強制的に、テキストではなくバイナリ形式と して全てのデータを読み書きします。 要因はデータ自身に高く依存していますが、通常の copy コマ ンドよりも多少速くなりますが、これは、一般的な移植性を持って おらず、生成されるファイルが多少大きくなります。
デフォルトでは、テキストの copy はタブ("\t") 文字を区切り 文字として使用します。 この区切り文字は、USING DELIMITERS というキーワード句を使 用して他の任意の1 文字に変更することもできます。 区切り文字に一致するデータフィールド内の文字はバックスラッ シュでクォートされます。
COPY で読み取る値を持つ全てのテーブル に対して select アクセス 権限が、 また、COPY で値を挿入するテーブルに対 しては insert もしくは update アクセス 権限が必要です。 また、バックエンドも COPY によって読み 書きされる全てのファイルに対して適切な Unix の権限が必要です。
USING DELIMITERS キーワード句は、全ての列の間の区切り として使われる 1 文字を指定します。 区切り文字内に複数の文字を指定した場合、最初の文字だけが使 用されます。
Tip: COPY と psql の \copy 命令と混同しないで下さい
COPY はルールの呼び出しも、列のデ フォルト操作も行ないません。 しかし、トリガは呼び出します。
COPY は最初のエラーでその操作を停止 します。 これは、COPY FROM の場合には何も問題 を引き起こしませんが、COPY TO の場合 には、当然のことですが、対象リレーションの一部が変更され ます。 コピーに失敗した後、VACUUM を使用して 整理する必要があります。
Postgres のバックエンドの現在の作業ディレクトリは通常、ユー ザの作業ディレクトリとは異なりますので、(絶対パスに関する情 報のない)"foo" へのコピーの結果は熟練し ていないユーザにとって予期しない結果となるかもしれません。 この場合、foo は $PGDATA/foo という結果になります。 一般的には、バックエンドサーバのマシンで参照できる完全なパ スを、コピーするファイルの指定に使用しなければなりません。
COPY の引数として使用するファイルは、 ローカルディスクやネットワークファイルシステム上にあると いうように、データベースサーバ上の、もしくは、データベー スサーバからアクセスできるものでなければなりません。
マシン間で TCP/IP 接続が使用される状態で、対象ファイルが指 定された場合、対象ファイルはユーザのマシンではなく、バック エンドを実行しているマシン上に書き込まれます。
BINARY オプション無しに COPY TO を使用した場合、生成されるファイルは、各列 (属性) を区切り文字で区切って、各行 (インスタンス) を 1 行に 書き込まれます。 データ自体にある区切り文字には、その前にバックスラッ シュ文字("\")が付けられます。 属性値自体は、その属性型に関連付けされた出力関数によっ て生成される文字列になります。 型の出力関数はバックスラッシュを生成しようとしてはい けません。 これは COPY 自身によって取り扱われ ます。
各インスタンスの実際の形式は以下になります。
<attr1><separator><attr2><separator>...<separator><attrn><newline>
WITH OIDS が指定された場合、oid が行の先頭に設置されます。
COPY がその出力をファイルではなく 標準出力に送信する場合、行を区別する改行が出力される、 その直前に、バックスラッシュ ("\") とピリオド (".") を 送信します。 同様に、COPY が標準入力から読み取る 場合では、バックスラッシュとピリオド、その後の改行を、 また、先頭からこの 3 文字からなる行がファイルの終りを 意味することを前提とします。 しかし、この特殊なファイルの終りを意味するパターンが検 出される前に、本当の EOF がある場合、 COPY は、(バックエンド自体もその後 に) 終了します。
バックスラッシュ文字には他にも特別な意味があります。 バックスラッシュ文字そのものは、2 つの連続するバックス ラッシュ("\\")で表されます。 タブ文字そのものはバックスラッシュとタブで表されます。 改行文字そのものはバックスラッシュと改行で表されます。 読み込むテキストデータが Postgres で生成されたものではない場合、適切に読み込まれることを 保証するために、バックスラッシュ文字 ("\") を二重のバッ クスラッシュ ("\\") に変換する必要があるでしょう。
次の例は、縦棒("|")をフィールド区切り文字として使用して、 テーブルから標準出力にコピーを行ないます。
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 つのフィールドがあり、その 1 つ目は char(2)、2 つ目は text です。 そして、全ての行は 3 つ目のフィールドとして、NULL 値を持ちます。 char(2) のフィールドが 4 バイトに なるようにヌルで埋められている点と text のフィールドの前 にその長さがあることに注意して下さい。
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