PostgreSQL 7.3 Documentation
PrevNext

COPY

Name

COPY  -- ファイルとテーブルの間でのデータのコピー

Synopsis

COPY table [ ( column [, ...] ) ]
FROM { 'filename' | stdin }
    [ [ WITH ]
          [ BINARY ] 
          [ OIDS ]
          [ DELIMITER [ AS ] 'delimiter' ]

          [ NULL [ AS ] 'null string' ] ]
COPY table [ ( column [, ...] ) ]
    TO { 'filename' | stdout }
    [ [ WITH ]
          [ BINARY ] 
          [ OIDS ]
          [ DELIMITER [ AS ] 'delimiter' ]
          [ NULL [ AS ] 'null string' ] ]

入力

table

既存のテーブルの名前です (スキーマ修飾の可能性もあり)。

column

コピーする列のリストです(オプション)。 列のリストが指定されていない場合は、すべての列が使用されます。

filename

入出力ファイルの Unix 絶対パス名です。

stdin

入力がクライアントアプリケーションからのものであることを指定します。

stdout

出力がクライアントアプリケーションへのものであることを指定します。

BINARY

フィールドのフォーマットをすべてのデータをテキストではなくバイナリで読み書きするように設定します。 バイナリモードで DELIMITER あるいは NULL を指定することはできません。

OIDS

それぞれの行に対する内部的なオブジェクトID（OID）をコピーすることを指定します。

delimiter

ファイルの各行（ライン）のフィールドを区切る文字を指定します。

null string

NULL 値を表す文字列です。デフォルトでは "\N"（バックスラッシュ N）です。しかし、場合によっては、空の文字列の方がよいかもしれません。

Note: コピーをして読み込む際、この文字列と一致するデータ要素は NULL 値として格納されます。 したがって、そのときには、コピーを行ったときに使用した同じ文字列を使用したかどうか確認してください。

出力

COPY

コピーは正常に終了しました。

ERROR:reason

エラーメッセージ内に表示された理由(reason) によってコピーは失敗しました。

説明

COPYコマンドは、PostgreSQL のテーブルと標準のファイルシステムのファイル間でデータを移動します。 COPY TO コマンドはテーブルのすべての内容をファイルにコピーします。 また、COPY FROM コマンドは、ファイルからテーブルへとデータをコピーします (このとき、すでにテーブルにあるデータにコピー内容を追加します）。

列のリストが指定されている場合、COPY では、指定された列のデータとファイルの間でのみコピーが行われます。 列リストに入っていない列がテーブル内にある場合、COPY FROM は、それらの列にデフォルトの値を挿入します。

ファイル名付きの COPY コマンドは、PostgreSQL のバックエンドに対して直接ファイルへの読み書きをするように伝えます。そのファイルは必ずバックエンドからアクセスでき、またファイル名はバックエンドからみたように指定されなければなりません。stdin や stdout が指定された場合、データはクライアントのフロントエンドからバックエンドに流れます。

Tip: COPY は psql の \copyとは異なるものであることに注意してください。\copy は COPY FROM stdin や COPY TO stdout を呼び出し、psql クライアントから接続できるファイルにデータの書き込み/読み込みを行います。したがって、\copy コマンドが使用された場合には、ファイルへのアクセスとアクセス権限は、バックエンドではなく、クライアント側に依存します。

注釈

COPY は通常のテーブルに対して使用することができます。 ビューに対しては使用することができません。

BINARY キーワードはすべてのデータをテキストではなく、バイナリオブジェクトとして書き込み/読み込みするように指定します。通常の COPY コマンドより多少速く動作しますが、バイナリコピーしたファイルを異なるマシンアーキテクチャで使用することはできません。

デフォルトではテキストコピーはフィールドの区切り文字としてタブ（"\t"）を使用します。 フィールドの区切り文字は DELIMITER というキーワードを用いて、別の任意の1文字に変更することができます。 区切り文字にたまたま一致するデータフィールド中の文字はバックスラッシュで囲まれます。

COPY TO コマンドによって値が読み込まれるテーブルに関して、select 権限を持っている必要があります。 また、COPY FROM コマンドによって値が挿入されるテーブルに対しても insert 権限が必要です。それに加え、バックエンドは COPY によって読み書きされるファイルに適切な Unix の権限が与えられている必要があります。

COPY FROM は、宛先テーブル上で任意のトリガーとチェック制約を呼び出しますが、ルールは呼び出しません。

COPY では、最初のエラーで処理を停止させます。 これは、COPY TO コマンドを実行している際には何ら問題はありませんが、COPY FROM の場合は、対象となるリレーションは始めのほうの行を受け取り済みです。これらの行は見えませんし、アクセスすることもできませんが、ディスク領域を占有します。大きなコピー処理に何度も失敗した場合には、無視できないほど無駄なディスク領域が増えてしまいます。この無駄な領域を取り戻すために、VACUUM を行う必要があります。

COPY コマンドで指名されたファイルはクライアントアプリケーションではなく、バックエンドが直接読み込み/書き込みを行います。したがって、それらはデータベースサーバ上に存在するか、または、クライアントではなくデータベースサーバからアクセス可能である必要があります。また、クライアントではなく PostgreSQL ユーザ（サーバを実行しているユーザID）で読み書きができる必要もあります。バックエンドがアクセス権限を持つ全てのファイルへの読み込み、書き込みを可能にするため、COPY でファイルを指名するのは、データベースのスーパーユーザのみに許可されています。

Tip: psql の \copy はクライアントの権限で、クライアントのマシンにてファイルの読み書きを行います。 したがって、スーパーユーザの権限は必要ありません。

COPY で指定されるファイル名を常に絶対パスで記述することをお勧めします。COPY TO コマンドの場合ではバックエンドによって強制的にそうなりますが、COPY FROM コマンドでは相対パスによって指定されたファイルを読み込むことも可能となっています。そのパスは、クライアントの作業ディレクトリではなく、バックエンドの作業ディレクトリ（$PGDATA の下のどこか）から相対的なディレクトリとして解釈されます。

ファイル形式

テキスト形式

COPYを BINARY オプションなしで使用した場合、読み書きされるファイルはテーブルの 1 つの行を 1 行で表したテキストファイルとなります。行内の列(属性)は区切り文字で区切られます。属性値自体はその属性のデータ型の出力関数で生成された、または、その入力関数で受け付け可能な文字列です。指定されたヌル値文字列は、属性が NULL の場所で使用されます。 入力ファイルの行にある列数が予期されていたよりも多かったり少なかったりすると、COPY FROM はエラーを出します。

OIDS が指定された場合、OID はユーザデータの列よりも前の、最初の列として読み書きされます (OID が OID を持たないテーブルに対して指定された場合はエラーが発生します)。

データの終了は、バックスラッシュ-ピリオド(\.) から構成される 1 行で表されます。ファイルの終了によって、完全に同じ機能を提供することができますので、データ終了マークは、Unix ファイルから読み込む際には不要です。 しかし、クライアントアプリケーションへの、または、からのコピーの場合は、終了マークを与えることは必要です。

バックスラッシュ文字 (\) は COPY 対象データ内で、行や列の区切り文字と判定されてしまう可能性があるデータ文字列をクォートすることに使用することができます。特に、以下の文字が属性値の一部となっている場合は 必ず バックスラッシュを前に付けなければなりません。バックスラッシュ自体、改行、使用する区切り文字

以下の特別なバックスラッシュから始まる文字の並びは、COPY FROM によって解釈されます。

文字の並び表現
\bバックスペース (ASCII 8)
\f改ページ (ASCII 12)
\n改行 (ASCII 10)
\r復帰 (ASCII 13)
\tタブ (ASCII 9)
\v垂直タブ (ASCII 11)
\数字バックスラッシュに続き、1 から 3 個の 8 進数で表す数字によって、そのコード番号が示す文字を指定します。

現在、COPY TO は 8 進数数字のバックスラッシュ並びを出力することはありませんが、上記一覧に存在しない制御文字には、これを使用します。

N またはピリオド (.) というデータ文字の前には、バックスラッシュを決して付けないで下さい。この組み合わせは、それぞれ、ヌル文字とデータ終了マークのデフォルトと間違って解釈されてしまいます。上で示したバックスラッシュ文字以外の文字はそのまま解釈されます。

COPY データを生成するアプリケーションは、データ内の改行と復帰をそれぞれ、\n と \r に変換することを強く推奨されています。現在(PostgreSQL 7.2 とそれ以前のバージョン)のところ、特殊な引用方法を使用しなくともデータ内の復帰を表すことも、バックスラッシュと改行でデータ内の改行を表すことも可能です。しかし、こういった表現は今後のリリースにてデフォルトでは受け付けられなくなります。

すべての行の終わりには Unix 形式の改行文字（"\n"）であることに注意してください。現在の COPY FROMでは、MS-DOS や Mac 形式の改行が含まれているファイルに対しては、期待どおりの動作を行いません。今後のリリースで変更する予定です。

バイナリ形式

COPY BINARYで使用されるファイル形式は PostgreSQL v7.1で、変更されました。 新しい形式はファイルヘッダ、0 以上のタプル、ファイルトレーラで構成されています。

ファイルヘッダ

ファイルヘッダは 24 バイトの固定フィールドで構成され、その後に可変長の拡張ヘッダがあります。固定フィールドは下記のとおりです。

シグネチャ

12バイトのシーケンスPGBCOPY\n\377\r\n\0です。null(\0)はシグネチャで必ず必要であることに注意してください（シグネチャはきれいに 8 ビットで転送されなかったファイルを容易に識別できるように設計されています。このシグネチャは改行変換のフィルター、nullの削除、上位ビット落ち、パリティの変更などによって変更されます）。

整数レイアウトフィールド（Integer layout field）

ソースのバイト並びにおける int32 の定数 0x01020304。不正なバイト並びが順が検出された場合、潜在的に読み込み先は引き続くフィールドのバイトをひっくり返すことができるようになります。

フラグフィールド（Flags field）

ファイル形式の重要部分を示す int32 ビットマスク。ビットは0（LSB）から31（MSB）までの番号が付けられます。 このフィールドが、全ての後続の整数フィールドのエンディアンを表す、ソースのエンディアン性として格納されることに注意して下さい。ビットの 16-31 は重要なファイル形式に関連することを示すために予約されています。 読み込み先はこの範囲に予期していないビットの列を発見した際には、そのファイルを破棄する必要があります。ビット 0〜ビット 15 は順序の後方互換性のあるファイル形式であるかの合図を行うために予約されています。 読み込み先はこの範囲に予期していないビットの列を発見した際には、無視しなくてはなりません。現在では、1つのフラグビットのみが定義されて、他はすべて0としなければなりません。

Bit 16

もし 1 ならば OID がダンプに含まれます。 0 の場合には含まれません。

拡張ヘッダ領域長（Header extension area length）

それ自身を含まない、ヘッダの残余の int32 のバイト長。初期のバージョンでは、これは0で、そのすぐ後に最初のタプルが続きます。今後の形式の変更では、ヘッダ内に表す情報の追加があるかもしれません。読み込み先は、どのような対処を行えばいいのかがわからないヘッダに関しては、ヘッダを飛ばす必要があります。

拡張ヘッダ領域は自己確認のチャンクのシーケンスを保持するために考えられています。フラグフィールドは読み込み先に拡張領域の内容を知らせるものではありません。特定の拡張ヘッダ内容の設計は後のリリースのために残してあります。

このデザインは、後方互換性のあるヘッダーの追加（拡張ヘッダチャンクの追加、や下位フラグビットの設定）と後方互換性のない変更（変更を合図するための高位フラグビットの設定や必要に応じた拡張領域へのサポート情報追加）に有効です。

タプル

すべてのタプルはタプル内の int16 でのフィールド数から始まります（現時点では、テーブル内のすべてのタプルは同一のフィールド数を持つようになっていますが、常にそうであるとは限りません）。 ですから、タプル中のそれぞれのフィールドで繰り返されて、フィールドデータの前に int16 の typlen が付随します。 typlen フィールドは以下のように解釈されます。

ゼロ

フィールドが NULL で、後続するデータはありません。

> 0

フィールドは固定長のデータ型で、typlen の後にちょうど N バイトのデータがあります。

-1

フィールドは可変長データ型で、次の 4 バイトは可変長ヘッダです。 このヘッダにそれ自身も含めた全長が含まれます。

< -1

将来のために予約しています。

NULL ではないフィールドに対して、読み込み先は目的列の typlen が期待された typlen と一致することを確認することができます。これは単純ですが、データが期待していたものであるかどうかの確認に便利です。

フィールド間では位置揃えのためのパディングや、その他の追加的データはありません。また、形式でデータ型が参照渡しであるか値渡しであるかの判断を行わないことにも注意してください。 これら両方の規定は故意のもので、ファイルの移植性を向上させる働きがあるかもしれません（しかし、エンディアン性と浮動少数形式の問題などから、マシン間のファイルの移動はまだ問題があります）。

OID がダンプに含まれている場合は、OID のフィールドはフィールドカウントの直後に位置します。これは、他のフィールドと何ら違いはありませんが、フィールドカウントにはカウントされません。 特別に typlen を持ちます。 これにより 4 バイトと 8 バイトの OID に対してとりたて負担をかけずに処理を行うことやそれが望ましいと判断された場合に OID を NULL として表示させることもできます。

ファイルトレーラ

ファイルトレーラは、-1を含んだ、int16 の情報単位で構成されます。 これはタプルのフィールドカウントを使用することによって容易に見分けることができます。

読み込み先は、フィールドカウントが-1である、または予期されていた列数とは異なる場合にはその報告を行ってください。これは、データの同期ずれに対する追加確認を提供します。

使用方法

下記の例では、フィールドの区別文字として縦棒（「|」）を使用し、テーブルを標準出力に出します。 

COPY country TO stdout WITH DELIMITER '|';

下記のコマンドは、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 つ目のフィールドは integer です。すべての行は 3 つ目のフィールドに NULL 値を持っています。 

0000000   P   G   B   C   O   P   Y  \n 377  \r  \n  \0 004 003 002 001
0000020  \0  \0  \0  \0  \0  \0  \0  \0 003  \0 377 377 006  \0  \0  \0
0000040   A   F 377 377 017  \0  \0  \0   A   F   G   H   A   N   I   S
0000060   T   A   N  \0  \0 003  \0 377 377 006  \0  \0  \0   A   L 377
0000100 377  \v  \0  \0  \0   A   L   B   A   N   I   A  \0  \0 003  \0
0000120 377 377 006  \0  \0  \0   D   Z 377 377  \v  \0  \0  \0   A   L
0000140   G   E   R   I   A  \0  \0 003  \0 377 377 006  \0  \0  \0   Z
0000160   M 377 377  \n  \0  \0  \0   Z   A   M   B   I   A  \0  \0 003
0000200  \0 377 377 006  \0  \0  \0   Z   W 377 377  \f  \0  \0  \0   Z
0000220   I   M   B   A   B   W   E  \0  \0 377 377

互換性

SQL92

SQL92にはCOPY文はありません。

以下の構文は、7．3 より前のアプリケーションに使われていたものですが、現在でもサポートされています。 

    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' ]

PrevHomeNext
COMMITUpCREATE AGGREGATE