描述

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 TO 复制的行与 SELECT * FROM ONLY 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 用户可执行。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 的影响。为确保可移植到可能使用非默认 DateStyle 设置的其他 PostgreSQL 安装，在使用 COPY TO 之前应将 DateStyle 设置为 ISO。避免使用 IntervalStyle 设置为 sql_standard 来转储数据也是一个好主意，因为具有不同 IntervalStyle 设置的服务器可能会误解负区间值。

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

COPY FROM 命令在进行过程中物理地将输入行插入表中。如果命令失败，这些行将以已删除的状态保留；这些行将不可见，但仍占用磁盘空间。如果在大型复制操作中间发生故障，这可能会导致大量浪费的磁盘空间。VACUUM 应用于恢复浪费的空间。

FORCE_NULL 和 FORCE_NOT_NULL 可以同时应用于同一列。这会导致将带引号的 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。所有行在第三列中都有一个 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 语句。

在 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' ]

另请参阅