COPY

説明

COPYコマンドは、PostgreSQLのテーブルと標準のファイルシステムのファイル間でデータを移動します。 COPY TOコマンドはテーブルの内容をファイルにコピーします。 また、COPY FROMコマンドは、ファイルからテーブルへとデータをコピーします（この時、既にテーブルにあるデータにコピーした内容を追加します）。 また、COPY TOによりSELECT問い合わせの結果をコピーすることができます。

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

ファイル名付きのCOPYコマンドは、PostgreSQLサーバに対して直接ファイルへの読み書きをするように命じます。 指定したファイルは必ずPostgreSQLユーザ(サーバを実行しているユーザID)からアクセスできる必要があります。 また、ファイル名はサーバから見たように指定されなければなりません。 PROGRAMが指定された場合、サーバは指定したコマンドを実行しその標準出力を読み取る、または、プログラムの標準入力に書き出します。 コマンドはサーバからの視点で指定しなければならず、また、PostgreSQLユーザによって実行できなければなりません。 STDINやSTDOUTが指定された場合、データはクライアントとサーバ間を流れます。

パラメータ

出力

正常に完了した場合、COPYコマンドは以下の形式のコマンドタグを返します。

COPY count

countはコピーされた行数です。

注釈

COPYは通常のテーブルに対してのみ使用することができます。 ビューに対して使用することはできません。 しかし、COPY (SELECT * FROM viewname) TO ...と記述することはできます。

COPYは指定された特定のテーブルのみを扱います。 つまり子テーブルへまたは子テーブルからのデータのコピーは行いません。 したがって例えば、COPY table TOはSELECT * FROM ONLY tableと同じデータを示します。 しかしCOPY (SELECT * FROM table) TO ...を使用して、継承階層内のすべてのデータをダンプすることができます。

COPY TOの場合は値を読み込むテーブルに対するSELECT権限が、COPY FROMの場合は値を挿入するテーブルに対するINSERT権限が必要です。 コマンド内で列挙された列に対する列権限があれば十分です。

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

COPYをpsqlの\copyと混同しないでください。 \copyはCOPY FROM STDINやCOPY TO STDOUTを呼び出し、psqlクライアントからアクセスできるファイルにデータの書き込み/読み込みを行います。 したがって、\copyコマンドでは、ファイルへのアクセスが可能かどうかと、ファイルに対するアクセス権限の有無は、サーバではなくクライアント側に依存します。

COPYでファイル名を指定する時は、常に絶対パスで記述することをお勧めします。 COPY TOコマンドの場合はサーバによって絶対パス指定に変更させられますが、COPY FROMコマンドでは相対パスで指定されたファイルを読み込むことも可能となっています。 後者では、クライアントの作業ディレクトリではなく、サーバプロセスの作業ディレクトリ（通常はクラスタのデータディレクトリ）からの相対的なディレクトリとして解釈されます。

PROGRAMを用いたコマンド実行は、SELinuxなどのオペレーティングシステムのアクセス制御機構によって制限されるかもしれません。

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

COPYの入出力はDateStyleの影響を受けます。 デフォルト以外のDateStyleが設定された可能性があるPostgreSQLインストレーションとの移植を確実に行いたい場合は、COPYを使う前にDateStyleをISOに設定しなければなりません。 また、IntervalStyleをsql_standardとしてデータをダンプすることは避けることを勧めます。 負の時間間隔値が別のIntervalStyle設定を持つサーバで誤解釈される可能性があるためです。

たとえデータがクライアント経由ではなくサーバにより直接ファイルから読み書きされるとしても、入力データはENCODINGオプションまたは現在のクライアント符号化方式にしたがって解釈され、出力データはENCODINGオプションまたは現在のクライアント符号化方式で符号化されます。

COPYでは、エラーが発生するとすぐに処理を停止します。 COPY TOコマンドの実行では何ら問題ありませんが、COPY FROMの場合は、対象となるテーブルは初めの方の行を既に受け取っています。 これらの行は不可視となり、アクセスすることもできませんが、ディスク領域を占有します。 したがって、大きなコピー処理がかなり進んだ後で失敗した場合には、それなりの量の無駄なディスク領域が使われてしまいます。 この無駄な領域を取り戻すには、VACUUMを行う必要があります。

FORCE_NULLとFORCE_NOT_NULLは同じ列について同時に使うことができます。 その場合の結果は、引用符付きのNULL文字列をNULL値に変換し、引用符なしのNULL文字列を空文字列に変換します。

ファイルの形式

例

次の例では、フィールド区切り文字として縦棒（|）を使用してテーブルをクライアントにコピーします。

COPY country TO STDOUT (DELIMITER '|');

ファイルからcountryテーブルにデータをコピーします。

COPY country FROM '/usr1/proj/bray/sql/country_data';

名前が'A'から始まる国のみをファイルにコピーします。

COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/bray/sql/a_list_countries.copy';

圧縮したファイルにコピーするためには、以下のように出力を外部の圧縮プログラムにパイプで渡すことができます。

COPY country TO PROGRAM 'gzip > /usr1/proj/bray/sql/country_data.gz';

これはSTDINからテーブルにコピーするのに適したデータの例です。

AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE

各行の空白文字は実際にはタブ文字であることに注意してください。

以下は同一のデータをバイナリ形式で出力したものです。 データをUnixユーティリティod -cを使ってフィルタしたものを示します。 テーブルには3列あり、最初のデータ型はchar(2)、2番目はtext、3番目はintegerです。 全ての行の3列目はNULL値です。

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

互換性

標準SQLにはCOPY文はありません。

以下の構文は、PostgreSQLバージョン9.0より前に使用されていたもので、まだサポートされています。

COPY table_name [ ( column_name [, ...] ) ]
    FROM { 'filename' | STDIN }
    [ [ WITH ]
          [ BINARY ]
          [ OIDS ]
          [ DELIMITER [ AS ] 'delimiter' ]
          [ NULL [ AS ] 'null string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote' ]
                [ ESCAPE [ AS ] 'escape' ]
                [ FORCE NOT NULL column_name [, ...] ] ] ]

COPY { table_name [ ( column_name [, ...] ) ] | ( query ) }
    TO { 'filename' | STDOUT }
    [ [ WITH ]
          [ BINARY ]
          [ OIDS ]
          [ DELIMITER [ AS ] 'delimiter' ]
          [ NULL [ AS ] 'null string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote' ]
                [ ESCAPE [ AS ] 'escape' ]
                [ FORCE QUOTE { column_name [, ...] | * } ] ] ]

この構文では、BINARYとCSVがFORMATオプションの引数ではなく、独立したキーワードとして扱われることに注意してください。

以下の構文は、PostgreSQLバージョン7.3より前に使用されていたもので、まだサポートされています。

COPY [ BINARY ] table_name [ WITH OIDS ]
    FROM { 'filename' | STDIN }
    [ [USING] DELIMITERS 'delimiter' ]
    [ WITH NULL AS 'null string' ]

COPY [ BINARY ] table_name [ WITH OIDS ]
    TO { 'filename' | STDOUT }
    [ [USING] DELIMITERS 'delimiter' ]
    [ WITH NULL AS 'null string' ]