描述

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 视图中报告其进度。详见 Section 27.4.3。

默认情况下，如果 COPY 在处理过程中遇到错误就会失败。对于希望尽力加载整个文件的用例，可以使用 ON_ERROR 子句来指定其他行为。

参数

输出

成功完成时，COPY 命令会返回如下形式的命令标签

COPY count

其中 count 是被复制的行数。

注记

COPY TO 可以用于普通表和已填充数据的物化视图。例如，COPY table TO 会复制与 SELECT * FROM ONLY table 相同的行。但是它不直接支持其他关系类型，例如分区表、继承子表或视图。要从这类关系中复制所有行，请使用 COPY (SELECT * FROM table) TO。

COPY FROM 可以用于普通表、外部表或分区表，也可以用于带有 INSTEAD OF INSERT 触发器的视图。

你必须对被 COPY TO 读取其值的表拥有选择权限，并且对被 COPY FROM 向其插入值的表拥有插入权限。只要拥有命令中列出的列上的列权限就足够了。

如果为表启用了行级安全性，相关的 SELECT 策略将应用于 COPY table TO 语句。目前，对于启用了行级安全性的表，不支持 COPY FROM。请改用等效的 INSERT 语句。

COPY 命令中命名的文件由服务器直接读取或写入，而不是由客户端应用读取或写入。因此，它们必须位于数据库服务器机器上或能被其访问，而不是客户端。它们必须能被 PostgreSQL 用户（服务器运行所用的用户 ID）访问、读取或写入，而不是客户端。类似地，用 PROGRAM 指定的命令由服务器直接执行，而不是由客户端应用执行，并且必须能被 PostgreSQL 用户执行。COPY 指定文件或命令的做法只允许数据库超级用户或被授予 pg_read_server_files、pg_write_server_files 或 pg_execute_server_program 角色之一的用户使用，因为它允许读取或写入服务器有权访问的任何文件或运行程序。

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

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

使用 PROGRAM 执行命令可能会受到操作系统访问控制机制（如 SELinux）的限制。

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

对于标识列，COPY FROM 命令将始终写入输入数据中提供的列值，就像 INSERT 选项 OVERRIDING SYSTEM VALUE 一样。

COPY 的输入和输出会受到 DateStyle 的影响。为了确保能移植到其他 PostgreSQL 安装（它们可能使用非默认的 DateStyle 设置），DateStyle 应被设置为 ISO，然后再使用 COPY TO。另外，最好避免在 IntervalStyle 设置为 sql_standard 的情况下转储数据，因为负的间隔值可能会被具有不同 IntervalStyle 设置的服务器误解。

输入数据会根据 ENCODING 选项或当前客户端编码来解释，输出数据会以 ENCODING 或当前客户端编码进行编码，即使数据不经过客户端而是由服务器直接从文件读取或向文件写入。

COPY FROM 命令在执行过程中会物理地将输入行插入到表中。如果命令失败，这些行会处于已删除状态；这些行将不可见，但仍会占用磁盘空间。如果失败发生在一个大型复制操作的后期，这可能意味着相当可观的磁盘空间被浪费。应当使用 VACUUM 来回收被浪费的空间。

FORCE_NULL 和 FORCE_NOT_NULL 可以同时在同一个列上使用。这会把加了引号的 NULL 字符串转换为空值，把未加引号的 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。所有行在第三列都有一个空值。

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 版之前使用，目前仍受支持：

COPY table_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 NULL column_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' ]

另请参阅