COPY

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用户执行。只有数据库超级用户，或被授予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 '|');

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