描述

COPY在表和文件之间交换数据。COPY TO 把一个表的所有内容都拷贝到一个文件，而COPY FROM从一个文件 里拷贝数据到一个表里(把数据附加到表中已经存在的内容里)。COPY TO 还能拷贝SELECT查询的结果。

如果声明了一个字段列表，COPY将只在文件和表之间拷贝已声明字段的数据。 如果表中有任何不在字段列表里的字段，那么COPY FROM将为那些字段插入缺省值。

带文件名的COPY指示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出来的数据必须有选取数据的权限， 对任何要COPY FROM入数据的表必须有插入权限。 对列在命令中的列拥有列权限是足够的。

COPY命令里面的文件必须是由服务器直接读或写的文件， 而不是由客户端应用读写。因此，它们必须位于数据库服务器上或者可以被数据库 服务器所访问，这些事情不应该由客户端来做。它们必须被运行 PostgreSQL服务器的用户可读或写， 而不是客户端。只允许数据库超级用户COPY一个文件， 因为它允许读写任意服务器有权限访问的文件。

不要混淆COPY和psql的 \copy指令。\copy调用 COPY FROM STDIN或COPY TO STDOUT，然后把数据抓取/存储到一个psql 客户端可以访问的文件中。因此，使用\copy的时候，文件访问 权限是由客户端而不是服务器端决定的。

建议在COPY里的文件名字总是使用绝对路径。 在COPY TO的时候是由服务器强制进行的，但是对于 COPY FROM，你的确可从一个相对路径的文件里读取。 该路径将解释为相对于服务器的工作目录(通常是数据目录)，而不是客户 端的工作目录。

COPY FROM会激活所有触发器和检查约束。不过，不会激活规则。

COPY输入和输出被DateStyle影响。 为了和其它PostgreSQL安装移植(它们可能是非缺省 DateStyle设置)，应该在使用COPY TO前把 DateStyle设置为ISO。 通过将IntervalStyle设置为sql_standard来避免转储数据 也是一个好主意。因为负的区间值可能会被对IntervalStyle有不同设置的 服务器误解。

Input data is interpreted according to the current client encoding, and output data is encoded in 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. 输入数据通过当前客户机编码来解译，输出数据被编码为当前客户机编码， 即使数据不经过客户端的，仍会通过服务器直接将数据从文件中读出或者写入到文件中去。

COPY在第一个错误处停下来。这些在COPY TO 中不应该导致问题，但在COPY FROM时目标表会已经接收到早先的行， 这些行将不可见或不可访问，但是仍然会占据磁盘空间。如果你碰巧拷贝大块数据文件的话， 这些东西积累起来可能会占据相当大的磁盘空间。你可以调用VACUUM 来恢复那些磁盘空间。

文件格式

例子

下面的例子把一个表拷贝到客户端，使用竖直条(|)作为域分隔符：

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';

下面是一个可以从STDIN中拷贝数据到表中的例子：

AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE

注意，每行里的空白实际上是一个水平制表符。

下面的是同样的数据，以二进制形式输出。这些数据是用Unix工具od -c过滤之后输出的。 该表有三个字段；第一个是char(2)，第二个是text，第三个是integer。所有的行在第三个域都是一个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语句。

PostgreSQL9.0以前使用下面的语法，现在仍然支持：

COPY table_name [ ( column [, ...] ) ]
    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 [, ...] ] ] ]

COPY { table_name [ ( column [, ...] ) ] | ( 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 [, ...] | * } ] ] ]

请注意：在这个语法中，BINARY和CSV是作为独立的关键字， 而不是作为FORMAT选项的一个参数。

PostgreSQL7.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' ]