描述

COPY在 PostgreSQL表与标准文件系统文件之间传输数据。COPY TO将表的内容复制到文件，而COPY FROM 则将数据从文件复制到表中（追加到表中已有的数据之后）。COPY TO也可以复制 SELECT查询的结果。

如果指定了列列表，COPY将只在指定列与文件之间复制数据。如果表中存在未列入列列表的列，COPY FROM将为这些列插入默认值。

带文件名的 COPY 会指示 PostgreSQL 服务器直接从文件读取或向文件写入。该文件必须可由服务器访问，并且其名称必须从服务器的视角指定。当指定 STDIN 或 STDOUT 时，数据通过客户端与服务器之间的连接传输。

参数

输出

成功完成时，COPY命令会返回形如

COPY count

的命令标签。count为复制的行数。

注解

COPY只能用于普通表，不能用于视图。但可以写 COPY (SELECT * FROM viewname) TO ...。

BINARY关键字使所有数据以二进制格式而不是文本格式存储/读取。它比普通文本模式略快，但二进制格式的文件在跨机器体系结构和PostgreSQL版本之间的可移植性较差。此外，二进制格式非常依赖于数据类型；例如，从smallint列输出二进制数据再读入integer列是不行的，尽管这在文本格式中完全可行。

你必须对COPY TO读取其值的表具有 SELECT权限，并对COPY FROM 插入其值的表具有INSERT权限。对于命令中列出的列，具有列级权限即可。

COPY 命令中命名的文件由服务器直接读取或写入，而不是由客户端应用进行。因此，这些文件必须位于数据库服务器机器上或可由其访问，而不是客户端上。它们必须可由 PostgreSQL 用户（服务器运行时使用的用户 ID）访问并可读或可写，而不是由客户端访问。带有文件名的 COPY 只允许数据库超级用户使用，因为它允许读取或写入服务器有权访问的任何文件。

不要把 COPY 与 psql 的指令 \copy 混淆。\copy 会调用 COPY FROM STDIN 或 COPY TO STDOUT，然后在 psql 客户端可访问的文件中获取/存储数据。因此，使用 \copy 时，文件的可访问性和访问权限取决于客户端而不是服务器。

建议在COPY中使用的文件名始终指定为绝对路径。对于COPY TO，服务器会强制这一点；但对于 COPY FROM，你仍可选择从使用相对路径指定的文件中读取。该路径将相对于服务器进程的工作目录（通常是集簇的数据目录）而非客户端的工作目录进行解释。

COPY FROM将调用目标表上的任何触发器和检查约束。但是它不会调用规则。

COPY的输入和输出会受 DateStyle影响。为确保数据能移植到其他可能使用非默认 DateStyle设置的PostgreSQL 安装中，使用COPY TO前应将 DateStyle设置为ISO。同样也建议避免在 IntervalStyle设置为sql_standard时转储数据，因为负的 interval 值可能会被采用不同 IntervalStyle设置的服务器误解。

输入数据会按照当前客户端编码解释，输出数据也会按照当前客户端编码编码，即使数据并不通过客户端、而是由服务器直接从文件读取或写入文件也是如此。

COPY 会在遇到第一个错误时停止操作。对于 COPY TO，这应当不会导致问题；但对于 COPY FROM，目标表此时已经接收了前面的行。这些行不可见也不可访问，但仍占用磁盘空间。如果在一次大型复制操作已经进行很久后才失败，可能会浪费大量磁盘空间。可以调用 VACUUM 回收这些浪费的空间。

文件格式

示例

下面的示例使用竖线（|）作为字段分隔符将一个表复制到客户端：

COPY country TO STDOUT WITH 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。所有行在第三列都是空值。

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语句。

以下语法曾在PostgreSQL7.3 之前的版本中使用，目前仍受支持：

COPY [ BINARY ] tablename [ WITH OIDS ]
    FROM { 'filename' | STDIN }
    [ [USING] DELIMITERS 'delimiter' ]
    [ WITH NULL AS 'null string' ]

COPY [ BINARY ] tablename [ WITH OIDS ]
    TO { 'filename' | STDOUT }
    [ [USING] DELIMITERS 'delimiter' ]
    [ WITH NULL AS 'null string' ]