描述

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 视图中报告其进度。有关详细信息，请参见第 27.4.3 节。

默认情况下，COPY 在处理过程中遇到错误会失败。如果希望尽力而为地尝试装载整个文件，可以使用 ON_ERROR 子句指定其他行为。

参数

输出

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

COPY count

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

注解

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

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

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

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

COPY 命令中指定的文件由服务器而非客户端应用直接读取或写入。因此，这些文件必须位于数据库服务器所在机器上，或者可由数据库服务器访问，而不是仅由客户端访问。它们必须可由 PostgreSQL 用户（服务器运行时使用的用户 ID）访问，并且对该用户可读或可写。同样，使用 PROGRAM 指定的命令也是由服务器而非客户端应用直接执行，因而必须可由 PostgreSQL 用户执行。只有数据库超级用户，或被授予 pg_read_server_files、pg_write_server_files 或 pg_execute_server_program 之一的用户，才允许使用指定文件名或命令的 COPY，因为这允许读取或写入服务器有权访问的任意文件，或者运行服务器有权执行的程序。

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

即使数据会被服务器直接从一个文件读取或者写入一个文件而不通过客户端，输入数据也会被根据 ENCODING 选项或者当前客户端编码解释，并且输出数据会被根据 ENCODING 或者当前客户端编码进行编码。

COPY FROM 在处理过程中会把输入行物理插入表中。如果命令失败，这些行会处于已删除状态；它们不可见，但仍占据磁盘空间。如果在大型复制操作后期失败，这可能造成大量磁盘空间浪费。应使用 VACUUM 回收这些浪费的空间。

FORCE_NULL 和 FORCE_NOT_NULL 可以同时用于同一列。这会把带引号的空值串转换为空值，并把不带引号的空值串转换为空串。

文件格式

示例

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

COPY country TO STDOUT (DELIMITER '|');

启用 FORCE_ARRAY 选项时，整个输出会被包裹在一个 JSON 数组中，各行之间以逗号分隔：

COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT  (FORMAT JSON, FORCE_ARRAY);

输出如下：

[
 {"id":1}
,{"id":2}
]

要将文件中的数据复制到 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' ]

另见