COPY — ファイルとテーブルの間でデータをコピーする
COPYtable_name
[ (column_name
[, ...] ) ] FROM { 'filename
' | PROGRAM 'command
' | STDIN } [ [ WITH ] (option
[, ...] ) ] [ WHEREcondition
] COPY {table_name
[ (column_name
[, ...] ) ] | (query
) } TO { 'filename
' | PROGRAM 'command
' | STDOUT } [ [ WITH ] (option
[, ...] ) ] ここでoption
は以下のいずれかです。 FORMATformat_name
FREEZE [boolean
] DELIMITER 'delimiter_character
' NULL 'null_string
' DEFAULT 'default_string
' HEADER [boolean
| MATCH ] QUOTE 'quote_character
' ESCAPE 'escape_character
' FORCE_QUOTE { (column_name
[, ...] ) | * } FORCE_NOT_NULL (column_name
[, ...] ) FORCE_NULL (column_name
[, ...] ) ENCODING 'encoding_name
'
COPY
コマンドは、PostgreSQLのテーブルと標準のファイルシステムのファイル間でデータを移動します。
COPY TO
コマンドはテーブルの内容をファイルにコピーします。
また、COPY FROM
コマンドは、ファイルからテーブルへとデータをコピーします(この時、既にテーブルにあるデータにコピーした内容を追加します)。
また、COPY TO
によりSELECT
問い合わせの結果をコピーすることができます。
列リストが指定されている場合、COPY TO
は指定された列のデータのみをファイルへコピーします。
COPY FROM
では、ファイルの各フィールドが順に指定された列に挿入されます。
COPY FROM
の列リストに含まれていないテーブル列には、デフォルト値が挿入されます。
ファイル名付きのCOPY
コマンドは、PostgreSQLサーバに対して直接ファイルへの読み書きをするように命じます。
指定したファイルは必ずPostgreSQLユーザ(サーバを実行しているユーザID)からアクセスできる必要があります。
また、ファイル名はサーバから見たように指定されなければなりません。
PROGRAM
が指定された場合、サーバは指定したコマンドを実行しその標準出力を読み取る、または、プログラムの標準入力に書き出します。
コマンドはサーバからの視点で指定しなければならず、また、PostgreSQLユーザによって実行できなければなりません。
STDIN
やSTDOUT
が指定された場合、データはクライアントとサーバ間を流れます。
COPY
を実行している各バックエンドはその進捗をpg_stat_progress_copy
ビューで報告します。
詳細は28.4.3を参照してください。
table_name
既存のテーブルの名前です(スキーマ修飾名も可)。
column_name
コピー対象の列リストで、省略可能です。 列リストが指定されていない場合は、生成列を除いてテーブルの全ての列がコピーされます。
query
SELECT
、VALUES
、INSERT
、UPDATE
あるいはDELETE
コマンドで、その結果がコピーされます。
問い合わせを括弧でくくる必要があることに注意してください。
INSERT
、UPDATE
およびDELETE
の問い合わせについてはRETURNING
句を付けなければならず、また、対象のリレーションには、複数の文に展開される条件付きルール、ALSO
ルール、INSTEAD
ルールがあってはなりません。
filename
入出力ファイルのパス名です。
入力ファイル名は絶対パスでも相対パスでも記述することができますが、出力ファイル名は絶対パスでなければなりません。
Windowsユーザの場合、E''
文字列を使用し、パス名内のバックスラッシュを二重にする必要があるかもしれません。
PROGRAM
実行するコマンドです。
COPY FROM
では、入力はコマンドの標準出力から読み取られ、COPY TO
では、出力はコマンドの標準入力に書き出されます。
コマンドはシェルから呼び出されることに注意してください。このため信頼できない入力元からの任意の引数を渡す必要がある場合、シェルにとって特殊な意味を持つかもしれない特殊文字の除去やエスケープを注意深く実施してください。 セキュリティ上の理由のため、固定のコマンド文字列を使用することが最善です。または少なくともユーザからの入力を含めることを避けてください。
STDIN
入力がクライアントアプリケーションからであることを指定します。
STDOUT
出力がクライアントアプリケーションへであることを指定します。
boolean
指定のオプションを有効とするか無効とするかを指定します。
オプションを有効にするには、TRUE
、ON
または1
と、無効にするにはFALSE
、OFF
または0
と記述します。
またboolean
値は省略可能であり、省略時はTRUE
とみなされます。
FORMAT
読み取りまたは書き込みに使用するデータ形式を選択します。
text
、csv
(カンマ区切り値)、またはbinary
です。
デフォルトはtext
です。
FREEZE
あたかもVACUUM FREEZE
コマンドを実行した後のように、行を凍結した状態のデータコピー処理を要求します。
これは、初期データロード処理用の性能オプションとしての利用を意図しています。
ロード元のテーブルが現在の副トランザクションで作成または切り詰めされ、開いているカーソルは存在せず、またこのトランザクションで保持される古めのスナップショットが存在しない場合のみ、行は凍結されます。
今のところ、パーティションテーブルではCOPY FREEZE
を実行できません。
データのロードに成功すると、他のすべてのセッションから即座にデータが参照可能になることに注意してください。 これはMVCC可視性に関する一般的な規則に違反しますので、ユーザはこれが引き起こすかもしれない潜在的な問題に注意しなければなりません。
DELIMITER
ファイルの各行内の列を区切る文字を指定します。
テキスト形式でのデフォルトはタブ文字、CSV
形式ではカンマです。
これは単一の1バイト文字でなければなりません。
このオプションはbinary
形式を使用する場合は許されません。
NULL
NULL値を表す文字列を指定します。
デフォルトは、テキスト形式では\N
(バックスラッシュN)、CSV
形式では引用符のない空文字です。
NULL値と空文字列を区別する必要がない場合は、テキスト形式であっても空文字列を使用した方が良いかもしれません。
このオプションはbinary
形式を使用する場合は許されません。
COPY FROM
の場合、この文字列と一致するデータ要素はNULL値として格納されます。
COPY TO
実行時に使用した同じ文字列を使用するようにしてください。
DEFAULT
デフォルト値を表す文字列を指定します。
文字列が入力ファイルで見つかるたびに、対応する列のデフォルト値が使用されます。
このオプションは、COPY FROM
でのみ使用でき、binary
形式を使用しない場合にのみ使用できます。
HEADER
ファイルがファイル内の各列の名前を持つヘッダ行を含むことを指定します。
出力時には、最初の行にテーブルの列名が含まれます。
入力時には、このオプションがtrue
(または同等の論理値)に設定されている場合、最初の行は破棄されます。
このオプションがMATCH
に設定されている場合、ヘッダ行の列の番号と名前が、テーブルの実際の列名と順番に一致しなければなりません。一致しない場合は、エラーが発生します。
binary
形式を使用している場合、このオプションは使用できません。
MATCH
オプションはCOPY FROM
コマンドでのみ有効です。
QUOTE
データ値を引用符付けする際に使用される引用符文字を指定します。
デフォルトは二重引用符です。
これは単一の1バイト文字でなければなりません。
このオプションはCSV
形式を使用する場合にのみ許されます。
ESCAPE
データ内の文字がQUOTE
の値と一致する場合に、その前に現れなければならない文字を指定します。
デフォルトはQUOTE
の値と同じです(このためデータ内に引用符用文字があるときは二つ続けます)。
これは単一の1バイト文字でなければなりません。
このオプションはCSV
形式を使用する場合のみ許されます。
FORCE_QUOTE
指定された各列内にある全ての非NULL
値を強制的に引用符で囲みます。
NULL
出力は引用符で囲まれません。
*
が指定された場合、非NULL
値はすべての列で引用符付けされます。
このオプションはCOPY TO
において、かつ、CSV
形式を使用する場合のみ許されます。
FORCE_NOT_NULL
指定された列の値をNULL文字列に対して比較しません。
NULL文字列が空であるデフォルトでは、空の値は引用符付けされていなくてもNULLではなく長さが0の文字列として読み取られることを意味します。
このオプションはCOPY FROM
において、かつ、CSV
形式を使用する場合のみで許されます。
FORCE_NULL
指定された列の値を、それが引用符付きであったとしても、NULL文字列と比較し、一致した場合は値をNULL
にセットします。
NULL文字列が空であるデフォルトでは、引用符付きの空文字列をNULLに変換します。
このオプションはCOPY FROM
で、かつCSV
形式を使用する場合のみ許されます。
ENCODING
ファイルがencoding_name
で符号化されていることを指定します。
このオプションが省略された場合、現在のクライアント符号化方式が使用されます。
後述の注釈を参照してください。
WHERE
省略可能なWHERE
句の一般的な形は以下の通りです。
WHERE condition
ここでcondition
は、評価の結果がboolean
型になる任意の式です。
この条件を満たさない行はテーブルに挿入されません。
変数参照を実際の行の値で置き換えた時に真を返す場合に、行は条件を満たします。
今のところ、WHERE
式の中での副問い合わせは認められていませんし、評価はCOPY
自身により行われた変更を見ることはありません(これは、式がVOLATILE
関数の呼び出しを含む場合に問題になります)。
正常に完了した場合、COPY
コマンドは以下の形式のコマンドタグを返します。
COPY count
count
はコピーされた行数です。
psqlはコマンドがCOPY ... TO STDOUT
であった場合、および、それと同等なpsqlのメタコマンド\copy ... to stdout
であった場合は、このコマンドタグを表示しません。
これは、コマンドタグが表示されたデータと混同されないようにするためです。
COPY TO
は通常のテーブルに対してのみ使用できます。ビューに対して使用することはできません。そして子テーブルもしくは子パーティションから行をコピーしません。
例えば、COPY
はtable
TOSELECT * FROM ONLY
と同じ行をコピーします。
継承階層やパーティションテーブル、ビューの行をすべてダンプするために、table
COPY (SELECT * FROM
構文が使えます。
table
) TO ...
COPY FROM
は通常のテーブル、外部テーブル、パーティションテーブルおよびINSTEAD OF INSERT
トリガを持つビューに対して使用することができます。
COPY TO
の場合は値を読み込むテーブルに対するSELECT権限が、COPY FROM
の場合は値を挿入するテーブルに対するINSERT権限が必要です。
コマンド内で列挙された列に対する列権限があれば十分です。
テーブルの行単位セキュリティが有効な場合、適切なSELECT
ポリシーがCOPY
文に適用されます。
現在のところ、table
TOCOPY FROM
は行単位セキュリティが有効なテーブルに対してはサポートされません。
代わりにそれと等価なINSERT
を使ってください。
COPY
コマンドで指定するファイルは、クライアントアプリケーションではなく、サーバが直接読み込み/書き込みを行います。
したがって、それらのファイルは、クライアントではなく、データベースサーバマシン上に存在するか、または、データベースサーバマシンからアクセス可能である必要があります。
さらに、クライアントではなく、PostgreSQLユーザ(サーバを実行しているユーザID)が、アクセス権限と読み書き権限を持っている必要があります。
同様に、PROGRAM
で指定されたコマンドは、クライアントアプリケーションではなくサーバにより直接実行されるため、PostgreSQLユーザによって実行可能でなければなりません。
ファイル名またはコマンドを指定したCOPY
の実行は、データベースのスーパーユーザとロールpg_read_server_files
、pg_write_server_files
、pg_execute_server_program
の内の1つの権限を許可されたユーザのみに許可されています。このコマンドによって、サーバがアクセス権限を持つ全てのファイルの読み込み、書き込みやプログラムの実行が可能になってしまうためです。
COPY
をpsqlの\copy
と混同しないでください。
\copy
はCOPY FROM STDIN
やCOPY TO STDOUT
を呼び出し、psqlクライアントからアクセスできるファイルにデータの書き込み/読み込みを行います。
したがって、\copy
コマンドでは、ファイルへのアクセスが可能かどうかと、ファイルに対するアクセス権限の有無は、サーバではなくクライアント側に依存します。
COPY
でファイル名を指定する時は、常に絶対パスで記述することをお勧めします。
COPY TO
コマンドの場合はサーバによって絶対パス指定に変更させられますが、COPY FROM
コマンドでは相対パスで指定されたファイルを読み込むことも可能となっています。
後者では、クライアントの作業ディレクトリではなく、サーバプロセスの作業ディレクトリ(通常はクラスタのデータディレクトリ)からの相対的なディレクトリとして解釈されます。
PROGRAM
を用いたコマンド実行は、SELinuxなどのオペレーティングシステムのアクセス制御機構によって制限されるかもしれません。
COPY FROM
は、宛先テーブル上で任意のトリガと検査制約を呼び出しますが、ルールは呼び出しません。
IDENTITY列については、COPY FROM
コマンドはINSERT
のオプションOVERRIDING SYSTEM VALUE
と同じように、必ず入力データが提供した列の値を書き込みます。
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文字列を空文字列に変換します。
text
形式を使用する場合、読み書きされるデータはテーブルの1つの行を1行で表したテキストファイルとなります。
行内の列は区切り文字で区切られます。
列の値自体は、その属性のデータ型の出力関数で生成された、または、その入力関数で受け付け可能な文字列です。
値がNULLの列では、代わりに指定されたNULL値を表す文字列が使用されます。
入力ファイルのいずれかの行にある列数が予期された数と違う場合、COPY FROM
はエラーを発生します。
データの終了は、バックスラッシュとピリオド(\.
)のみから構成される1行で表されます。
ファイルの終了により同じ動作になるので、ファイルからの読み込みの場合はデータ終了マークは不要です。
しかし、3.0以前のクライアントプロトコルを使用したクライアントアプリケーションとデータのコピーを行う場合だけは、読み込み、書き込みを問わず、終了マークが必要です。
バックスラッシュ文字(\
)は、COPY
対象データ内で、行や列の区切り文字と判定される可能性があるデータ文字列の引用符付けに使用します。
特に、バックスラッシュ自体、改行、復帰、使用中の区切り文字などの文字が列の値に含まれている場合は、必ず前にバックスラッシュを付けなければなりません。
指定されたNULL文字列はバックスラッシュを付けずにCOPY TO
に送られます。
一方、COPY FROM
では、バックスラッシュを削除する前にNULL文字列と入力を比較します。
したがって、\N
といったNULL文字列が実際の\N
というデータ値と混乱することはあり得ません。
(これは\\N
として表現されます。)
COPY FROM
は、バックスラッシュで始まる次のような文字の並びを識別します。
文字の並び | 表現 |
---|---|
\b | バックスペース(ASCII 8) |
\f | 改ページ(ASCII 12) |
\n | 改行(ASCII 10) |
\r | 復帰(ASCII 13) |
\t | タブ(ASCII 9) |
\v | 垂直タブ(ASCII 11) |
\ 数字 | バックスラッシュに続き1から3個の8進数の数字をコード番号として指定すると、そのコード番号が表すバイトを指定できます。 |
\x 数字 | バックスラッシュ、x という並びに続き1から2個の16進数の数字を指定すると、そのコード番号が表すバイトを指定できます。 |
現在、COPY TO
は、バックスラッシュの後ろに8進数や16進数を付けた形式で文字を出力することはありませんが、上記一覧にある制御文字については、バックスラッシュの文字並びを使用します。
上表で記載されていないバックスラッシュ付きの文字はすべて、その文字自体として解釈されます。
しかし、不要なバックスラッシュの追加には注意してください。
偶然にデータの終わりを示す印(\.
)やヌル文字列(デフォルトでは\N
)と合致する文字列を生成してしまうかもしれないためです。
これらの文字列は他のバックスラッシュの処理を行う前に解釈されます。
COPY
データを生成するアプリケーションは、データ内の改行と復帰をそれぞれ、\n
と\r
に変換することを強く推奨されています。
現在のところ、バックスラッシュと復帰文字でデータ内の復帰を表したり、バックスラッシュと改行文字でデータ内の改行を表すことが可能です。
しかし、こういった表現は今後のリリースでは、受け付けられなくなる可能性があります。
また、COPY
ファイルが異なるマシンをまたがって転送される場合、破損するおそれがかなりあります
(例えば、UnixからWindowsあるいはその逆)。
バックスラッシュで始まる文字の並びはすべて符号化方式変換の後で解釈されます。 バックスラッシュの後ろに8進数や16進数を付けた形式で指定されたバイトはデータベース符号化方式において有効な文字でなければなりません。
COPY TO
は各行の行末にUnix形式の改行(「\n
」)を出力します。
なお、Microsoft Windowsで稼働するサーバの場合は、サーバ上のファイルへのCOPY
の場合にのみ復帰/改行(「\r\n
」)を出力します。
プラットフォームをまたがる一貫性のために、サーバのプラットフォームにかかわらず、COPY TO STDOUT
は常に「\n
」を送信します。
COPY FROM
は、改行、復帰、復帰/改行を行末として扱うことができます。
データを意図したバックスラッシュのない改行や復帰によるエラーの危険性を減らすために、COPY FROM
は、入力行の行末が全て共通でない場合に警告を発します。
この形式オプションは、スプレッドシートなど他の多くのプログラムで使用されるカンマ区切り値(CSV
)ファイル形式をインポート、エクスポートするために使用されます。
PostgreSQLの標準テキスト形式で使用されるエスケープ規則の代わりに、一般的なCSV
のエスケープ機構を生成、認識します。
各レコードの値はDELIMITER
文字で区切られます。
区切り文字、QUOTE
文字、NULL
文字列、復帰、改行文字を含む値の場合、全体の値の前後にQUOTE
文字が付与されます。値の中でQUOTE
文字やESCAPE
文字が現れる場合、その前にエスケープ用の文字が付与されます。
また、FORCE_QUOTE
を使用して、特定列内の非NULL
値を出力する時に強制的に引用符を付与することもできます。
CSV
形式にはNULL
値と空文字列とを区別する標準的な方法はありません。
PostgreSQLのCOPY
では引用符によってこれを区別しています。
NULL
はNULL
パラメータの文字列として出力され、引用符で囲まれません。
一方、NULL
パラメータの文字列に一致する非NULL
値は引用符で囲まれます。
たとえばデフォルトの設定では、NULL
は引用符付けのない空文字列として出力され、空文字列のデータ値は2つの引用符(""
)で出力されます。
データの読み込みの際も同様の規則に従います。
FORCE_NOT_NULL
を使用して、特定列に対しNULL
入力の比較を行わないようにすることもできます。
またFORCE_NULL
を使うことで、引用符付きのNULL文字列のデータの値をNULL
に変換することもできます。
CSV
形式ではバックスラッシュは特別な文字ではありませんので、データ終端記号\.
がデータ値として現れることがあります。
誤った解釈を防ぐために、行内の唯一の項目として\.
というデータ値が現れる場合、出力に自動的に引用符が付けられます。
また、入力では引用符で括られた場合データ終端記号として解釈されません。
他のアプリケーションで作成されたファイルをロードしようとする場合、引用符で括られない列が1つあるだけで、それが\.
という値を持つ可能性があるなら、入力ファイル内のこうした値を引用符で括る必要があります。
CSV
形式では文字はすべて意味を持ちます。
空白文字で括られた引用符付きの値などDELIMITER
以外のすべての文字がこうした文字に含まれます。
これにより、固定長にするためにCSV
の行に空白文字を埋めるシステムから取り出したデータをインポートする時にエラーが発生する可能性があります。
このような状況になった場合、PostgreSQLにデータをインポートする前に、そのCSV
ファイルから余分な空白を除去する前処理が必要になります。
CSV
形式は、復帰文字や改行文字が埋め込まれ引用符で囲まれた値を含むCSV
ファイルを認識し、生成します。
したがって、このファイルでは、テキスト形式とは異なり、1つのテーブル行が1行で表されているとは限りません。
奇妙な(時には間違った)CSV
ファイルを生成するプログラムは多く存在するので、このファイル形式は標準というよりも慣習と言えるものです。
したがって、この機能でインポートできないファイルが存在するかもしれませんし、COPY
が他のプログラムで処理できないファイルを生成するかもしれません。
binary
形式オプションにより、すべてのデータはテキストではなくバイナリ形式で書き込み/読み取りされるようになります。
テキストやCSV
形式よりも多少高速になりますが、バイナリ形式のファイルはマシンアーキテクチャやPostgreSQLのバージョンをまたがる移植性が落ちます。
またバイナリ形式はデータ型に非常に依存します。
たとえば、smallint
列からバイナリデータを出力し、それをinteger
列として読み込むことはできません。同じことをテキスト形式で実行すれば動作するのですが。
binary
ファイルの形式は、ファイルヘッダ、行データを含む0以上のタプル、ファイルトレーラから構成されます。
ヘッダとデータはネットワークバイトオーダです。
7.4以前のリリースのPostgreSQLでは異なるバイナリファイル形式を使用していました。
ファイルヘッダは15バイトの固定フィールドとその後に続く可変長ヘッダ拡張領域から構成されます。 固定フィールドは以下の通りです。
PGCOPY\n\377\r\n\0
という11バイトの並びです。
この署名の必須部分にNULLバイトが含まれていることに注意してください
(この署名は、8ビットを通過させない転送方式によってファイルが破損した場合、これを容易に識別できるように設計されています。
署名は、改行コード変換やNULLバイトの削除、上位ビット落ち、パリティの変更などによって変化します)。
このファイル形式の重要な部分となる32ビット整数のビットマスクです。 ビットには0(LSB) から31(MSB)までの番号が付いています。 このフィールドは、このファイル形式で使用される他の全ての整数フィールドも同様、ネットワークバイトオーダ(最上位バイトが最初に現れる)で保存されていることに注意してください。 ファイル形式上の致命的な問題を表すために、16–31ビットは予約されています。 この範囲に想定外のビットが設定されていることが判明した場合、読み込み先は処理を中断しなければなりません。 後方互換における形式の問題を通知するために、0–15ビットは予約されています。 この範囲に想定外のビットが設定されていても、読み込み先は無視すべきです。 現在、1つのビットだけがフラグビットとして定義されており、残りは0でなければなりません。
1ならば、OIDがデータに含まれています。0ならば、含まれていません。 OIDシステム列は今はもうPostgreSQLでサポートされていませんが、フォーマットには指標が含まれています。
自分自身を除いた、ヘッダの残り部分のバイト長を示す32ビットの整数です。 現在、これは0となっており、すぐ後に最初のタプルが続きます。 今後、ヘッダ内に追加データを格納するような形式の変更があるかもしれません。 読み込み側では、ヘッダ拡張データの扱いがわからない場合、そのデータをスキップしなければなりません。
ヘッダ拡張領域は、それ自身で認識することができる塊の並びを保持するために用意されています。 フラグフィールドは読み込み先に拡張領域の内容を知らせるものではありません。 ヘッダ拡張内容の個々の設計は今後のリリースのために残してあります。
この設計によって、後方互換性を維持するヘッダの追加(ヘッダ拡張チャンクの追加や下位フラグビットの設定)と後方互換性のない変更(変更を通知するための高位フラグビットの設定や必要に応じた拡張領域へのサポート情報追加)の両方に対応できます。
全てのタプルはタプル内のフィールド数を表す16ビットの整数から始まります(現時点では、テーブル内の全てのタプルは同一のフィールド数を持つことになっていますが、今後、これは変更される可能性があります)。 その後に、タプル中のそれぞれのフィールドが続きます。これらのフィールドには、先頭にフィールドデータが何バイトあるかを表す32ビット長のワードが付けられています (このワードが表す長さには自分自身は含まれません。したがって、0になることもあります)。 特殊な値としてNULLフィールドを表す-1が用意されています。 このNULLが指定された場合、値用のバイトはありません。
フィールド間には整列用のパッドやその他の余計なデータはありません。
現在、バイナリ形式のファイル内の全てのデータ値は、バイナリ形式(形式コード1)であると想定されています。 将来の拡張によって、列単位に形式コードを指定するヘッダフィールドが追加される可能性があります。
実際のタプルデータとして適切なバイナリ形式を決定するためには、PostgreSQLのソース、特に各列のデータ型用の*send
関数と*recv
関数(通常はソースの配布物内のsrc/backend/utils/adt
ディレクトリにあります)を調べなければなりません。
このファイルにOIDが含まれる場合、OIDフィールドがフィールド数ワードの直後に続きます。 これは、フィールド数に含まれない点を除いて、通常のフィールドです。 OIDシステム列はPostgreSQLの現在のバージョンではサポートされていないことに注意してください。
ファイルトレーラは、16ビットの整数ワードで構成され、-1が入っています。 タプルのフィールド数ワードとは、容易に区別できます。
読み込み側は、フィールドカウントワードが-1でも、想定した列数でもなかった場合はエラーを報告しなければなりません。 これにより、何らかの理由でデータと一致しなかったことを判定する特別な検査を行うことが可能になります。
次の例では、フィールド区切り文字として縦棒(|
)を使用してテーブルをクライアントにコピーします。
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より前に使用されていたもので、まだサポートされています。
COPYtable_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 NULLcolumn_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
[, ...] | * } ] ] ]
この構文では、BINARY
とCSV
がFORMAT
オプションの引数ではなく、独立したキーワードとして扱われることに注意してください。
以下の構文は、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
' ]