copy - Unix ファイルからクラスへ、またはクラスから Unix ファイルへデータをコピーする。
copy [binary] クラス名 [with oids]
to|from 'ファイル名'|stdin|stdout
[using delimiters 'デリミタ']
Copy は Postgres のクラスと Unix ファイルの間でデータを移す。キーワード binary は後述のように、フィールドの書式化に関する振る舞いを変更する。クラス名は存在するクラスである。キーワード with oids は、内部的にユニークな各行のオブジェクト ID (OID) もコピーする。ファイル名はファイルの絶対 (Unix) パス名である。ファイル名の代わりにキーワード stdin と stdout を使うことができるので、 copy への入力は Libpq アプリケーションによって書き込むことができ、 copy からの出力は Libpq アプリケーションによって読み込むことができる。
binary キーワードを指定すると、すべてのデータを ASCII テキストではなくバイナリ・オブジェクトとして読み書きする。これは通常の copy コマンドよりいくらか速いが、一般的にどのマシン間でも使えるというわけではなく、また要因がデータそのものにあるとはいえ、生成されたファイルはいくらか大きくなる。デフォルトでは、ASCII の copy はデリミタとしてタブ (\\t) を使う。デリミタは using delimiters を使って他の任意の 1 バイト文字に変更することができる。データフィールドにあるデリミタ文字と同じ文字は、引用符で囲まれる。
あなたは、 copy コマンドにより値が読まれるすべてのクラスに対しての読み込み権が必要で、また copy コマンドにより値が追加されるクラスへの書き込み権または追加権が必要となる。
.SS ASCII コピーフォーマット copy が binary キーワードなしで使われると、生成されるファイルは 1 行に 1 インスタンスとなり、各属性はデリミタ文字で区切られる。埋め込まれたデリミタ文字は、その前にバックスラッシュ文字 (\\)が付く。属性値自身は、各属性の型に関連付けられた出力関数により生成される文字列となる。ある型のための出力関数は、バックスラッシュ文字を生成しようとしてはならない。この処理は copy 自身が行う。
各インスタンスの実際のフォーマットは、以下のようになる。
<属性1><タブ><属性2><タブ>...<タブ><属性n><ニューライン>
もし copy がその出力をファイルの代わりに標準出力に送っている場合、処理が完了すると、バックスラッシュ(\\)とピリオド(.)に続いてすぐにニューラインが出力される。同様に、 copy が標準入力からデータを読んでいる場合、ファイルの終了を検出するために、バックスラッシュ(\\)、ピリオド(.)、ニューラインの 3 文字からなる行を期待している。ただし、本当の EOF を検出した場合でも copy (と、それに引き続いてバックエンドそのものも)は終了する。
バックスラッシュ文字は特別な意味を持っている。 NULL 属性は \\N として出力される。文字としてのバックスラッシュは、2 つの連続したバックスラッシュで出力される。文字としてのタブ文字は、バックスラッシュとタブで表現される。文字としてのニューラインは、バックスラッシュとニューラインで表現される。PostgreSQL で作られたのではない ASCII データを読み込む場合、適切に読み込みを行うために、バックスラッシュ文字 (\\) を二重のバックスラッシュ文字 (\\\\) にコンバートしてやる必要がある。
ファイル中の各インスタンスのフォーマットを以下に示す。このフォーマットは 正確に 並んでいなければならないことに注意すること。以下の説明では、符号無しの 4 バイト整数で表される量を uint32 と呼んでいる。
最初の値：
uint32 個のタプル
そして、各タプルとして：
uint32 データセグメントの全体長
uint32 oid (指定された場合)
uint32 NULL 属性の数
[uint32 最初の NULL 属性の数
...
uint32 n 番目の NULL 属性の数],
<data segment>
.SS バイナリデータのアライメント(バウンダリ調整)Sun-3 では、2 バイトの属性は 2 バイト境界でバウンダリ調整が行われ、それより大きいすべての属性は 4 バイト境界でバウンダリ調整される。文字属性は 1 バイトバウンダリとなる。他のマシンでは、1 バイトより大きい属性はすべて 4 バイトバウンダリとなる。可変長属性は、その前に属性の長さが付加されることに注意すること。配列は、単に配列要素の型の連続的なストリームである。
copy コマンドへの引数として使用されるファイルは、ローカルディスク上に置くかまたはネットワークで共有されたファイルシステム上に置くなどの方法で、データベースマシン上に存在するか、またはアクセス可能でなければならない。
Copy は最初のエラーで実行を停止する。これは、 copy from 中に発生した問題の被害を拡大させないようにするためだが、もちろん copy to においても対象となるリレーションが一部変更される。に失敗した後は、エラーをクリアするためにvacuum(l) クエリーを使うべきであろう。
Postgres はその起動時に、ユーザのワークディレクトリ以外のところで動作するため、ファイル "foo" (パス情報がない場合)へのコピーの結果がどこへいったかわからなくなるユーザもいる。こういった場合は、 "foo" は $PGDATA /foo として出力されている。一般的に、コピーするファイルを指定する場合はフルパスで指定する方がよいだろう。
堀田 倫英 <hotta@net-newbie.com>