描述

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 读取其值的表具有选择权限，并且对 COPY FROM 插入值的表具有插入权限。对命令中列出的列具有列权限就足够了。

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

在 COPY 命令中命名的文件由服务器直接读取或写入，而不是由客户端应用程序读取或写入。因此，它们必须驻留在数据库服务器机器上或可供数据库服务器机器访问，而不是客户端。它们必须可供 PostgreSQL 用户（服务器运行的用户名）访问并可供其读取或写入，而不是客户端。同样，使用 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 可以同时在同一列上使用。这将导致将带引号的空字符串转换为空值，并将不带引号的空字符串转换为空字符串。

文件格式

示例

以下示例使用竖线 (|) 作为字段分隔符将表复制到客户端

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

另请参阅