描述

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

如果指定了列列表，则 COPY TO 仅将指定列中的数据复制到文件中。对于 COPY FROM，文件中的每个字段按顺序插入到指定的列中。 COPY FROM 列列表中未指定的表列将接收其默认值。

带有文件名 COPY 指示 PostgreSQL 服务器直接从文件读取或写入文件。 PostgreSQL 用户（服务器运行的 User ID）必须可以访问该文件，并且必须从服务器的角度指定名称。当指定 PROGRAM 时，服务器执行给定的命令并从程序的标准输出读取，或写入程序的标准输入。必须从服务器的角度指定命令，并且 PostgreSQL 用户可以执行该命令。当指定 STDIN 或 STDOUT 时，数据通过客户端和服务器之间的连接传输。

运行 COPY 的每个后端将在 pg_stat_progress_copy 视图中报告其进度。有关详细信息，请参见 第 28.4.3 节。

参数

输出

成功完成后，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 用户执行。只有数据库超级用户或被授予 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 的情况下，因为负间隔值可能会被具有不同 IntervalStyle 设置的服务器误解。

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

COPY 在第一个错误时停止操作。在 COPY TO 事件中，这不应导致问题，但目标表已经在 COPY FROM 中接收了较早的行。这些行将不可见或不可访问，但它们仍然占用磁盘空间。如果在大型复制操作中发生故障，这可能会浪费大量磁盘空间。您可能希望调用 VACUUM 以回收浪费的空间。

FORCE_NULL 和 FORCE_NOT_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' ]

另请参见