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' ]
フィールドのフォーマットを全てのデータをテキストではなく バイナリで読み書きするように設定します。バイナリーフォーマットでは、 DELIMITERSとWITH NULLのオプションは無意味となります。
存在するテーブルの名前です。
それぞれの行に対する内部的な一意のオブジェクトID(OID)をコピーすることを 指定します。
入出力ファイルの Unix 絶対パス名です。
入力がクライアントアプリケーションからのものかを指定します。
出力がクライアントアプリケーションへのものかを指定します。
ファイルの各行(ライン)のフィールドを区切る文字です。
これは、NULLの値を表す文字列です。デフォルトでは "\N"(バックスラッシュN)です。 しかし、場合によっては、空の文字列の方が良いかも知れません。
Note: コピーをして読み込む際、この文字列と一致するデータ要素はNULL値として格納されます。 したがって、その時には、コピーを行った際に使用した同じ文字列を使用したかどうか確認してください。
COPYコマンドは、Postgres のテーブルと標準のファイルシステムのファイル間でデータを移動します。 COPY TOコマンドはテーブルのすべての内容をファイルに コピーします。また、COPY FROMコマンドは ファイルからテーブルへとデータをコピーします(この時、すでにテーブルにある データにコピー内容を追加します)。
COPYコマンドは、Postgresの バックエンドに対して直接ファイルへの読み書きをするように通告します。 ファイル名が指定された場合は、そのファイルは必ずバックエンドから 接続でき、またファイル名はバックエンドからみたように指定されなければなりません。 stdinやstdoutが指定された場合、 データはクライアントのフロントエンドからバックエンドに流れます。
Tip: COPYはpsqlの \copyとは異るものであることにご注意下さい。 \copyはCOPY FROM stdinや COPY TO stdoutを呼び出し、 psqlクライアントから接続できるファイルに データを書き込み/読み込みを行います。したがって、\copy コマンドが使用された場合には、ファイルへの接続と接続権限は、 バックエンドではなく、クライアント側に依存します。
キーワードBINARYは全てのデータをテキストではなく、バイナリオブジェクトとして 書き込まれたり読み込まれるようにします。通常のコピーコマンドより いく分速く動作しますが、バイナリのコピーファイルは動作マシンの基本構造 によって移植性に欠けます。
デフォルトではテキストコピーはフィールドの区切り文字としてタブ("\t")を使用します。 フィールドの区切り文字はUSING DELIMITERSというキーワードを用いて、別の 任意の1文字に変更することができます。区切り文字にたまたま一致するデータフィールド中の 文字はバックスラッシュでくくられます。区切り文字は必ず1文字であることに注意して下さい。 2字以上の文字が指定された場合には、最初の1字が区切り文字として使用されます。
COPYコマンドによって値が読み込まれたあらゆるテーブルは selectを実行する権限が必要となります。 また、COPYコマンドによって値が挿入されたテーブルには insertやupdate権限が必要です。 それに加え、バックエンドはCOPYによって読み書きされるファイル に適切なUnixの権限が与えられている必要があります。
COPY TOコマンドはルールを呼び出したり、列のデフォルトに 影響を与えることは行いません。トリガと検査制約は呼び出します。
COPYでは、最初のエラーで処理を停止させます。 これは、COPY FROMコマンドを実行している際には 何ら問題はありませんが、対象となるリレーションは COPY TOの始めのほうの行を受け取りずみです。 これらの行は見えませんし、接続することもできませんが、ディスク領域を 占有します。大きなコピー処理に失敗した場合には無駄なディスク領域が 増えてしまいます。この無駄な領域を取り戻すために、VACUUMを 行う必要があります。
COPYで指名されたファイルはクライアントアプリケーションではなく、バックエンドが直接 読み込み/書き込みを行います。したがって、それらはデータベースサーバ上に存在するか、 または、クライアントではなくサーバから接続可能である必要があります。また、クライアントではなく Postgresユーザ(バックエンドが起動しているユーザID)で読み書きができる必要もあります。 COPYでファイルを指名するのは、データベースの スーパーユーザのみに許可されています。というのは、バックエンドが書き込み権限を持っている どんなファイルに対しても書き込みを許可するためです。
Tip: psqlの\copyは クライアントの権限で、クライアントのマシンにて読み書きを行います。 したがって、スーパーユーザの権限は必要ありません。
COPYで指定されるファイル名は絶対パスで記述されることを 推薦します。COPY TOコマンドの場合ではバックエンドによって 強制的にそうなりますが、COPY FROMコマンドでは 相対パスによって指定されたファイルを読み込むことも可能となっています。 そのパスは、クライアントの作業環境ではなく、バックエンドの作業環境 ($PGDATAの下のどこか)と連携して解釈されます。
COPY TOがBINARYオプション無しで使用されると、 生成されたファイルは、それぞれの列(属性)が区切り文字で区切られた 一行ごとの行(インスタンス)から構成されます。データの中にある区切り文字には バックスラッシュ("\")が付きます。属性値そのものはそれぞれの属性 の型に対応した出力関数によって生成された文字列です。型の出力関数は バックスラッシュ文字の生成に関与してはなりません。COPY 自身がこれを取り扱います。
それぞれのインスタンスの実際の形式は下記のようになります。
<attr1><separator><attr2><separator>...<separator><attrn><newline>
すべての行の終りにはUnix形式の改行文字("\n")であることに注意して下さい。
COPY FROMでは、DOSやMac形式の改行が含まれている
ファイルに対しては、希望に沿う動作を行いません。
WITH OIDSが指定された場合、OIDが行の先頭に付きます。
COPY TOが出力をファイルではなく、標準出力に出す場合、 行の最後にバックスラッシュ("\")とピリオド(".")を送出し、そのあと改行を行います。 同様に、COPY FROMが標準入力からデータを読み込む場合は、 ファイルの終了(end-of-file)を規定する行の始めの3文字として、 バックスラッシュ("\")とピリオド(".")とそれに引き続く改行があることを前提とします。 しかし、この特殊なファイル終了の様式が検出される前に、入力接続が閉ざされた場合、 正常に終了されます(バックエンドも引き続いて終了します。)
バックスラッシュには別の特別な意味があります。バックスラッシュ文字そのものは 二つの連続したバックスラッシュ("\\")で表現されます。タブ文字そのものは バックスラッシュとタブで表現されます。(列の区切り文字としてタブを使用していない場合は、 データに含めるためにその区切り文字にバックスラッシュを付けて下さい。)改行そのものは バックスラッシュと改行で表現されます。Postgresで生成されたものでない テキストデータを読み込む時は、正常に読み込みを行うためにバックスラッシュ文字("\")を 二つのバックスラッシュ("\\")に変換する必要があります。
COPY BINARYで使用されるファイル形式は Postgres v7.1で、変更されました。新しい形式はファイルヘッダー、0以上のタプル、 ファイルトレーラーで構成されています。
ファイルヘッダは24バイトの固定フィールドで構成され、その後に 可変長の拡張ヘッダがあります。固定フィールドは下記の通りです。
12バイトのシーケンス"PGBCOPY\n\377\r\n\0" -- NULLはシグネチャーで 必ず必要であることにご注意下さい。(シグネチャーはきれいに8ビットで 転送されなかったファイルを容易に識別できるように設計されています。この シグネチャーは改行変換のフィルター、消えてしまったNULL、上位ビット落ち、 あるいはパリティの変更によって変更されます。)
ソースのバイト並びにおけるint32の定数0x01020304。不正なバイト並びが順が検出された場合、 潜在的に読み込み先は引き続くフィールドのバイトをひっくり返すことができるようになります。
ファイル形式の重要部分を示すint32ビットマスク。ビットは0 (LSB)から31 (MSB) まで番号が付けられます。このフィールドがソースのエンディアン性として格納され、 すべての後続の整数のフィールドでも同様です。ビットの16-31は重要なファイル形式に 関連することを示すために予約されています。読み込み先はこの範囲に予期していない ビットの列を発見した際には、そのファイルを破棄する必要があります。 ビットの0-15は順序の両立性のあるファイル形式であるかの合図を行うために 予約されています。読み込み先はこの範囲に予期していないビットの列を発見した際には、 無視しなくてはなりません。現在では、1つのフラグビットのみが定義されて、他はすべて ゼロとなります。
もし1ならば、OIDがダンプに含まれます。0の時には含まれません。
それ自身を含まない、ヘッダの残余のint32のバイト長。初期のバージョンでは、これは0で、 そのすぐ後に最初のタプルが続きます。今後の形式の変更では、ヘッダに表示させる 情報の追加があるかもしれません。読み込み先は、どのような対処を行えばいいのかが 分からないヘッダに関しては、ヘッダを飛ばす必要があります。
拡張ヘッダ領域は 自己確認のチャンクのシーケンスを保持するために考えられています。 フラグフィールドは読み込み先に拡張領域の内容を知らせるものではありません。特定の 拡張ヘッダ内容のデザインは後のリリースのために残してあります。
このデザインは、順序の両立性のあるヘッダの追加(拡張ヘッダチャンク、 または下位フラグビット)と両立性のない変更(変更を合図するために 高位フラグビットを設定し、必要に応じて拡張領域にサポート情報を追加する) に有効です。
すべてのタプルはタプル内のint16でのフィールド数から始まります。(現時点では、 テーブル内のすべてのタプルは同一のフィールド数を持っようになっていますが、 常にそうであるとは限りません。) ですから、タプル中のそれぞれのフィールドで 繰り返されて、フィールドデータの前にint16のtyplenが付随します。typlen フィールドはこのように解釈されます。
フィールドがNULLで、後続するデータがない
フィールドは固定長のデータ型で、typlenの後に 丁度Nバイトのデータがある
フィールドはvarlenaデータ型で、次の4バイトはそれ自身も含めた varlenaヘッダーの合計長さ
後のために保存
NULLではないフィールドに対して、読み込み先は目的列のtyplenが期待された typlenと一致することを確認することができます。これは単純ですが、 データが期待していたものであるかどうかの確認に便利です。
フィールド間ではアラインパディングや、その他の追加的データはありません。 また、形式でデータ型が参照パスであるか値パスであるかの判断を行わない ことにもご注意下さい。これら両方の規定は故意のもので、ファイルの 移植性を向上させる働きがあるかもしれません(しかし、エンディアン性 と浮動少数形式のことなどから、マシン間のファイルの移動はまだ問題があります)。
OIDがダンプに含まれている場合は、OIDのフィールドはフィールドカウントの 直後に位置します。これは、他のフィールドとなんら違いはありませんが、フィールド カウントにはカウントされません。typlenを持ち、これで4バイトと8バイトのOIDに 対してとりたて負担をかけずに処理を行います。また、今後の実装でOIDがオプションとなった場合、OIDを NULLとして表示させます。
下記の例では、フィールドの区別子として縦棒 ("|") を使用し、テーブルを標準出力に出します。
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番目は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