描述

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 用户（服务器运行所用的用户 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。避免使用设置为 sql_standard 的 IntervalStyle 转储数据也是一个好主意，因为具有不同 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' ]

另请参阅