COPY

描述

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

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

带文件名的COPY指示PostgreSQL服务器直接从文件中读写数据。 该文件必须是PostgreSQL用户（服务器运行的用户ID）可以访问的， 而且文件名必须从服务器的角度声明。如果使用了PROGRAM选项， 则服务器执行给定的命令并读取该程序的标准输出，或写入到该程序的标准输入。 该命令必须从服务器的角度声明，并且是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服务器的用户可读或写，而不是客户端程序。 由PROGRAM选项指定的命令必须是由服务器来执行的，而不是客户端程序，必须是由PostgreSQL所属的用户。 COPY在指定一个程序或是命令时只允许数据库超级用户来执行，因为它允许读写任意服务器有权限访问的文件。

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

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

执行一个PROGRAM选项指定的命令有可能还会受到操作系统的存取权限控制，如在SELinux下。

COPY FROM在执行时会触发目标表上所有触发器和检查约束。不过，不会执行规则。

COPY输入和输出会被DateStyle参数影响。 为了和其它PostgreSQL不同服务器间进行数据转移(它们可能是非缺省DateStyle设置)，应该在使用COPY TO前把DateStyle参数值设置为ISO。 另外也建议在导出数据时，不要将IntervalStyle参数设置为sql_standard。 因为负的区间值可能会被对IntervalStyle有不同设置的服务器误解。

输入数据通过ENCODING参数或是当前客户端编码来解译，输出数据也是通过ENCODING参数或是为当前客户端的编码来编码， 即使数据不经过客户端的，仍会通过服务器直接将数据从文件中读出或者写入到文件中去。

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

FORCE_NULL和FORCE_NOT_NULL可以同时使用在相同的字段上。 这导致转换引用的空字符串到空值，转换未引用的空字符串到空字符串。

文件格式

例子

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

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过滤之后输出的。 该表有三个字段；第一个是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_name [, ...] ) ]
    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_name [, ...] ] ] ]

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

请注意：在这个语法中，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' ]