输出

成功完成后，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。并且最好避免将 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。所有行在第三个列中有空值。

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

另请参阅