説明

<command>COPY</command> moves data between <productname>PostgreSQL</productname> tables and standard file-system files. <command>COPY TO</command> copies the contents of a table <emphasis>to</emphasis> a file, while <command>COPY FROM</command> copies data <emphasis>from</emphasis> a file to a table (appending the data to whatever is in the table already). <command>COPY TO</command> can also copy the results of a <command>SELECT</command> query. COPYコマンドは、PostgreSQLのテーブルと標準のファイルシステムのファイル間でデータを移動します。 COPY TOコマンドはテーブルの内容をファイルにコピーします。 また、COPY FROMコマンドは、ファイルからテーブルへとデータをコピーします（この時、既にテーブルにあるデータにコピーした内容を追加します）。 また、COPY TOによりSELECT問い合わせの結果をコピーすることができます。

If a column list is specified, <command>COPY TO</command> copies only the data in the specified columns to the file. For <command>COPY FROM</command>, each field in the file is inserted, in order, into the specified column. Table columns not specified in the <command>COPY FROM</command> column list will receive their default values. 列リストが指定されている場合、COPY TOは指定された列のデータのみをファイルへコピーします。 COPY FROMでは、ファイルの各フィールドが順に指定された列に挿入されます。 COPY FROMの列リストに含まれていないテーブル列には、デフォルト値が挿入されます。

<command>COPY</command> with a file name instructs the <productname>PostgreSQL</productname> server to directly read from or write to a file. The file must be accessible by the <productname>PostgreSQL</productname> user (the user ID the server runs as) and the name must be specified from the viewpoint of the server. When <literal>PROGRAM</literal> is specified, the server executes the given command and reads from the standard output of the program, or writes to the standard input of the program. The command must be specified from the viewpoint of the server, and be executable by the <productname>PostgreSQL</productname> user. When <literal>STDIN</literal> or <literal>STDOUT</literal> is specified, data is transmitted via the connection between the client and the server. ファイル名付きのCOPYコマンドは、PostgreSQLサーバに対して直接ファイルへの読み書きをするように命じます。 指定したファイルは必ずPostgreSQLユーザ(サーバを実行しているユーザID)からアクセスできる必要があります。 また、ファイル名はサーバから見たように指定されなければなりません。 PROGRAMが指定された場合、サーバは指定したコマンドを実行しその標準出力を読み取る、または、プログラムの標準入力に書き出します。 コマンドはサーバからの視点で指定しなければならず、また、PostgreSQLユーザによって実行できなければなりません。 STDINやSTDOUTが指定された場合、データはクライアントとサーバ間を流れます。

Each backend running <command>COPY</command> will report its progress in the <structname>pg_stat_progress_copy</structname> view. See <xref linkend="copy-progress-reporting"/> for details. COPYを実行している各バックエンドはその進捗をpg_stat_progress_copyビューで報告します。 詳細は28.4.3を参照してください。

パラメータ

出力

On successful completion, a <command>COPY</command> command returns a command tag of the form 正常に完了した場合、COPYコマンドは以下の形式のコマンドタグを返します。

COPY count

The <replaceable class="parameter">count</replaceable> is the number of rows copied. countはコピーされた行数です。

注釈

<command>COPY TO</command> can be used only with plain tables, not views, and does not copy rows from child tables or child partitions. For example, <literal>COPY <replaceable class="parameter">table</replaceable> TO</literal> copies the same rows as <literal>SELECT * FROM ONLY <replaceable class="parameter">table</replaceable></literal>. The syntax <literal>COPY (SELECT * FROM <replaceable class="parameter">table</replaceable>) TO ...</literal> can be used to dump all of the rows in an inheritance hierarchy, partitioned table, or view. COPY TOは通常のテーブルに対してのみ使用できます。ビューに対して使用することはできません。そして子テーブルもしくは子パーティションから行をコピーしません。 例えば、COPY table TOはSELECT * FROM ONLY tableと同じ行をコピーします。 継承階層やパーティションテーブル、ビューの行をすべてダンプするために、COPY (SELECT * FROM table) TO ...構文が使えます。

<command>COPY FROM</command> can be used with plain, foreign, or partitioned tables or with views that have <literal>INSTEAD OF INSERT</literal> triggers. COPY FROMは通常のテーブル、外部テーブル、パーティションテーブルおよびINSTEAD OF INSERTトリガを持つビューに対して使用することができます。

You must have select privilege on the table whose values are read by <command>COPY TO</command>, and insert privilege on the table into which values are inserted by <command>COPY FROM</command>. It is sufficient to have column privileges on the column(s) listed in the command. COPY TOの場合は値を読み込むテーブルに対するSELECT権限が、COPY FROMの場合は値を挿入するテーブルに対するINSERT権限が必要です。 コマンド内で列挙された列に対する列権限があれば十分です。

If row-level security is enabled for the table, the relevant <command>SELECT</command> policies will apply to <literal>COPY <replaceable class="parameter">table</replaceable> TO</literal> statements. Currently, <command>COPY FROM</command> is not supported for tables with row-level security. Use equivalent <command>INSERT</command> statements instead. テーブルの行単位セキュリティが有効な場合、適切なSELECTポリシーがCOPY table TO文に適用されます。 現在のところ、COPY FROMは行単位セキュリティが有効なテーブルに対してはサポートされません。 代わりにそれと等価なINSERTを使ってください。

Files named in a <command>COPY</command> command are read or written directly by the server, not by the client application. Therefore, they must reside on or be accessible to the database server machine, not the client. They must be accessible to and readable or writable by the <productname>PostgreSQL</productname> user (the user ID the server runs as), not the client. Similarly, the command specified with <literal>PROGRAM</literal> is executed directly by the server, not by the client application, must be executable by the <productname>PostgreSQL</productname> user. <command>COPY</command> naming a file or command is only allowed to database superusers or users who are granted one of the roles <literal>pg_read_server_files</literal>, <literal>pg_write_server_files</literal>, or <literal>pg_execute_server_program</literal>, since it allows reading or writing any file or running a program that the server has privileges to access. COPYコマンドで指定するファイルは、クライアントアプリケーションではなく、サーバが直接読み込み/書き込みを行います。 したがって、それらのファイルは、クライアントではなく、データベースサーバマシン上に存在するか、または、データベースサーバマシンからアクセス可能である必要があります。 さらに、クライアントではなく、PostgreSQLユーザ（サーバを実行しているユーザID）が、アクセス権限と読み書き権限を持っている必要があります。 同様に、PROGRAMで指定されたコマンドは、クライアントアプリケーションではなくサーバにより直接実行されるため、PostgreSQLユーザによって実行可能でなければなりません。 ファイル名またはコマンドを指定したCOPYの実行は、データベースのスーパーユーザとロールpg_read_server_files、pg_write_server_files、pg_execute_server_programの内の1つの権限を許可されたユーザのみに許可されています。このコマンドによって、サーバがアクセス権限を持つ全てのファイルの読み込み、書き込みやプログラムの実行が可能になってしまうためです。

Do not confuse <command>COPY</command> with the <application>psql</application> instruction <command><link linkend="app-psql-meta-commands-copy">\copy</link></command>. <command>\copy</command> invokes <command>COPY FROM STDIN</command> or <command>COPY TO STDOUT</command>, and then fetches/stores the data in a file accessible to the <application>psql</application> client. Thus, file accessibility and access rights depend on the client rather than the server when <command>\copy</command> is used. COPYをpsqlの\copyと混同しないでください。 \copyはCOPY FROM STDINやCOPY TO STDOUTを呼び出し、psqlクライアントからアクセスできるファイルにデータの書き込み/読み込みを行います。 したがって、\copyコマンドでは、ファイルへのアクセスが可能かどうかと、ファイルに対するアクセス権限の有無は、サーバではなくクライアント側に依存します。

It is recommended that the file name used in <command>COPY</command> always be specified as an absolute path. This is enforced by the server in the case of <command>COPY TO</command>, but for <command>COPY FROM</command> you do have the option of reading from a file specified by a relative path. The path will be interpreted relative to the working directory of the server process (normally the cluster's data directory), not the client's working directory. COPYでファイル名を指定する時は、常に絶対パスで記述することをお勧めします。 COPY TOコマンドの場合はサーバによって絶対パス指定に変更させられますが、COPY FROMコマンドでは相対パスで指定されたファイルを読み込むことも可能となっています。 後者では、クライアントの作業ディレクトリではなく、サーバプロセスの作業ディレクトリ（通常はクラスタのデータディレクトリ）からの相対的なディレクトリとして解釈されます。

Executing a command with <literal>PROGRAM</literal> might be restricted by the operating system's access control mechanisms, such as SELinux. PROGRAMを用いたコマンド実行は、SELinuxなどのオペレーティングシステムのアクセス制御機構によって制限されるかもしれません。

<command>COPY FROM</command> will invoke any triggers and check constraints on the destination table. However, it will not invoke rules. COPY FROMは、宛先テーブル上で任意のトリガと検査制約を呼び出しますが、ルールは呼び出しません。

For identity columns, the <command>COPY FROM</command> command will always write the column values provided in the input data, like the <command>INSERT</command> option <literal>OVERRIDING SYSTEM VALUE</literal>. IDENTITY列については、COPY FROMコマンドはINSERTのオプションOVERRIDING SYSTEM VALUEと同じように、必ず入力データが提供した列の値を書き込みます。

<command>COPY</command> input and output is affected by <varname>DateStyle</varname>. To ensure portability to other <productname>PostgreSQL</productname> installations that might use non-default <varname>DateStyle</varname> settings, <varname>DateStyle</varname> should be set to <literal>ISO</literal> before using <command>COPY TO</command>. It is also a good idea to avoid dumping data with <varname>IntervalStyle</varname> set to <literal>sql_standard</literal>, because negative interval values might be misinterpreted by a server that has a different setting for <varname>IntervalStyle</varname>. COPYの入出力はDateStyleの影響を受けます。 デフォルト以外のDateStyleが設定された可能性があるPostgreSQLインストレーションとの移植を確実に行いたい場合は、COPYを使う前にDateStyleをISOに設定しなければなりません。 また、IntervalStyleをsql_standardとしてデータをダンプすることは避けることを勧めます。 負の時間間隔値が別のIntervalStyle設定を持つサーバで誤解釈される可能性があるためです。

Input data is interpreted according to <literal>ENCODING</literal> option or the current client encoding, and output data is encoded in <literal>ENCODING</literal> or the current client encoding, even if the data does not pass through the client but is read from or written to a file directly by the server. たとえデータがクライアント経由ではなくサーバにより直接ファイルから読み書きされるとしても、入力データはENCODINGオプションまたは現在のクライアント符号化方式にしたがって解釈され、出力データはENCODINGオプションまたは現在のクライアント符号化方式で符号化されます。

<command>COPY</command> stops operation at the first error. This should not lead to problems in the event of a <command>COPY TO</command>, but the target table will already have received earlier rows in a <command>COPY FROM</command>. These rows will not be visible or accessible, but they still occupy disk space. This might amount to a considerable amount of wasted disk space if the failure happened well into a large copy operation. You might wish to invoke <command>VACUUM</command> to recover the wasted space. COPYでは、エラーが発生するとすぐに処理を停止します。 COPY TOコマンドの実行では何ら問題ありませんが、COPY FROMの場合は、対象となるテーブルは初めの方の行を既に受け取っています。 これらの行は不可視となり、アクセスすることもできませんが、ディスク領域を占有します。 したがって、大きなコピー処理がかなり進んだ後で失敗した場合には、それなりの量の無駄なディスク領域が使われてしまいます。 この無駄な領域を取り戻すには、VACUUMを行う必要があります。

<literal>FORCE_NULL</literal> and <literal>FORCE_NOT_NULL</literal> can be used simultaneously on the same column. This results in converting quoted null strings to null values and unquoted null strings to empty strings. FORCE_NULLとFORCE_NOT_NULLは同じ列について同時に使うことができます。 その場合の結果は、引用符付きのNULL文字列をNULL値に変換し、引用符なしのNULL文字列を空文字列に変換します。

ファイルの形式

例

The following example copies a table to the client using the vertical bar (<literal>|</literal>) as the field delimiter: 次の例では、フィールド区切り文字として縦棒（|）を使用してテーブルをクライアントにコピーします。

COPY country TO STDOUT (DELIMITER '|');

To copy data from a file into the <literal>country</literal> table: ファイルからcountryテーブルにデータをコピーします。

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

To copy into a file just the countries whose names start with 'A': 名前が'A'から始まる国のみをファイルにコピーします。

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

To copy into a compressed file, you can pipe the output through an external compression program: 圧縮したファイルにコピーするためには、以下のように出力を外部の圧縮プログラムにパイプで渡すことができます。

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

Here is a sample of data suitable for copying into a table from <literal>STDIN</literal>: これはSTDINからテーブルにコピーするのに適したデータの例です。

AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE

Note that the white space on each line is actually a tab character. 各行の空白文字は実際にはタブ文字であることに注意してください。

The following is the same data, output in binary format. The data is shown after filtering through the Unix utility <command>od -c</command>. The table has three columns; the first has type <type>char(2)</type>, the second has type <type>text</type>, and the third has type <type>integer</type>. All the rows have a null value in the third column. 以下は同一のデータをバイナリ形式で出力したものです。 データを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

互換性

There is no <command>COPY</command> statement in the SQL standard. 標準SQLにはCOPY文はありません。

The following syntax was used before <productname>PostgreSQL</productname> version 9.0 and is still supported: 以下の構文は、PostgreSQLバージョン9.0より前に使用されていたもので、まだサポートされています。

COPY table_name [ ( column_name [, ...] ) ]
    FROM { 'filename' | STDIN }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE NOT NULL column_name [, ...] ] ] ]

COPY { table_name [ ( column_name [, ...] ) ] | ( query ) }
    TO { 'filename' | STDOUT }
    [ [ WITH ]
          [ BINARY ]
          [ DELIMITER [ AS ] 'delimiter_character' ]
          [ NULL [ AS ] 'null_string' ]
          [ CSV [ HEADER ]
                [ QUOTE [ AS ] 'quote_character' ]
                [ ESCAPE [ AS ] 'escape_character' ]
                [ FORCE QUOTE { column_name [, ...] | * } ] ] ]

Note that in this syntax, <literal>BINARY</literal> and <literal>CSV</literal> are treated as independent keywords, not as arguments of a <literal>FORMAT</literal> option. この構文では、BINARYとCSVがFORMATオプションの引数ではなく、独立したキーワードとして扱われることに注意してください。

The following syntax was used before <productname>PostgreSQL</productname> version 7.3 and is still supported: 以下の構文は、PostgreSQLバージョン7.3より前に使用されていたもので、まだサポートされています。

COPY [ BINARY ] table_name
    FROM { 'filename' | STDIN }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

COPY [ BINARY ] table_name
    TO { 'filename' | STDOUT }
    [ [USING] DELIMITERS 'delimiter_character' ]
    [ WITH NULL AS 'null_string' ]

関連項目