sql-copy.zh.md

## 复制

COPY — 在文件和表之间复制数据

## 概要

```
COPY table_name [ ( column_name [, ...] ) ]
    FROM { 'filename' | PROGRAM 'command' | STDIN }
    [ [ WITH ] ( option [, ...] ) ]
    [ WHERE condition ]

COPY { table_name [ ( column_name [, ...] ) ] | ( query ) }
    TO { 'filename' | PROGRAM 'command' | STDOUT }
    [ [ WITH ] ( option [, ...] ) ]

where option can be one of:

    FORMAT format_name
    FREEZE [ boolean ]
    DELIMITER 'delimiter_character'
    NULL 'null_string'
    HEADER [ boolean ]
    QUOTE 'quote_character'
    ESCAPE 'escape_character'
    FORCE_QUOTE { ( column_name [, ...] ) | * }
    FORCE_NOT_NULL ( column_name [, ...] )
    FORCE_NULL ( column_name [, ...] )
    ENCODING 'encoding_name'
```

## 描述

`复制`在 PostgreSQL 表和标准文件系统文件之间移动数据。`复制到`复制表格的内容*到*一个文件，而`复制自`复制数据*从*将文件添加到表中（将数据附加到表中已有的内容）。`复制到`也可以复制一个结果`选择`询问。

如果指定了列列表，`复制到`仅将指定列中的数据复制到文件中。为了`复制自`，文件中的每个字段都按顺序插入到指定的列中。表中未指定的列`复制自`列列表将收到它们的默认值。

`复制`使用文件名指示 PostgreSQL 服务器直接读取或写入文件。该文件必须可由 PostgreSQL 用户（服务器运行的用户 ID）访问，并且必须从服务器的角度指定名称。什么时候`程序`指定时，服务器执行给定的命令并从程序的标准输出读取，或写入程序的标准输入。该命令必须从服务器的角度指定，并且可由 PostgreSQL 用户执行。什么时候`标准输入`或者`标准输出`指定时，数据通过客户端和服务器之间的连接传输。

每个后端运行`复制`将报告其进展情况`pg_stat_progress_copy`看法。看[第 28.4.6 节](progress-reporting.html#COPY-PROGRESS-REPORTING)详情。

## 参数

*`表名`*

现有表的名称（可选模式限定）。

*`列名`*

要复制的列的可选列表。如果未指定列列表，则将复制表中除生成列之外的所有列。

*`询问`*

一种[`选择`](sql-select.html),[`价值观`](sql-values.html),[`插入`](sql-insert.html),[`更新`](sql-update.html)， 或者[`删除`](sql-delete.html)要复制其结果的命令。请注意，查询周围需要括号。

为了`插入`,`更新`和`删除`查询必须提供 RETURNING 子句，并且目标关系不能有条件规则，也不能`还`规则，也不是`反而`扩展到多个语句的规则。

*`文件名`*

输入或输出文件的路径名。输入文件名可以是绝对路径或相对路径，但输出文件名必须是绝对路径。Windows 用户可能需要使用`E''`字符串并将路径名中使用的任何反斜杠加倍。

`程序`

要执行的命令。在`复制自`，输入是从命令的标准输出中读取的，并且在`复制到`，输出被写入命令的标准输入。

请注意，该命令由 shell 调用，因此如果您需要将任何来自不受信任来源的参数传递给 shell 命令，则必须小心去除或转义任何可能对 shell 具有特殊含义的特殊字符。出于安全原因，最好使用固定的命令字符串，或者至少避免在其中传递任何用户输入。

`标准输入`

指定输入来自客户端应用程序。

`标准输出`

指定输出到客户端应用程序。

*`布尔值`*

指定是否应打开或关闭所选选项。你可以写`真的`,`在`， 或者`1`启用该选项，并且`错误的`,`离开`， 或者`0`禁用它。这*`布尔值`*value 也可以省略，在这种情况下`真的`假设。

`格式`

选择要读取或写入的数据格式：`文本`,`csv`（逗号分隔值），或`二进制`.默认是`文本`.

`冻结`

请求复制已冻结行的数据，就像在运行`真空冷冻`命令。这旨在作为初始数据加载的性能选项。仅当正在加载的表已在当前子事务中创建或截断时，行才会被冻结，没有游标打开并且该事务没有持有旧快照。目前无法执行`复制冻结`在分区表上。

请注意，一旦数据成功加载，所有其他会话将立即能够看到数据。这违反了 MVCC 可见性的正常规则，用户指定应该意识到这可能导致的潜在问题。

`分隔符`

指定在文件的每一行（行）中分隔列的字符。默认是文本格式的制表符，逗号`CSV`格式。这必须是一个单字节字符。使用时不允许此选项`二进制`格式。

`空值`

指定表示空值的字符串。默认是`\N`（反斜杠-N）文本格式，以及一个不带引号的空字符串`CSV`格式。在您不想区分空字符串和空字符串的情况下，您可能更喜欢使用文本格式的空字符串。使用时不允许此选项`二进制`格式。

### 笔记

使用时`复制自`，任何与此字符串匹配的数据项都将存储为空值，因此您应确保使用与您使用的相同的字符串`复制到`.

`标题`

指定文件包含带有文件中每一列名称的标题行。输出时，第一行包含表中的列名，输入时，第一行被忽略。此选项仅在使用时允许`CSV`格式。

`引用`

指定引用数据值时要使用的引用字符。默认为双引号。这必须是一个单字节字符。此选项仅在使用时允许`CSV`格式。

`逃脱`

指定应该出现在匹配的数据字符之前的字符`引用`价值。默认值与`引用`值（以便引用字符在数据中出现时加倍）。这必须是一个单字节字符。此选项仅在使用时允许`CSV`格式。

`FORCE_QUOTE`

强制引用用于所有非`空值`每个指定列中的值。`空值`输出永远不会被引用。如果`*`是指定的，非`空值`值将在所有列中引用。此选项仅在`复制到`，并且仅在使用时`CSV`格式。

`FORCE_NOT_NULL`

不要将指定列的值与空字符串匹配。在空字符串为空的默认情况下，这意味着空值将被读取为长度为零的字符串而不是空值，即使它们没有被引用。此选项仅在`复制自`，并且仅在使用时`CSV`格式。

`FORCE_NULL`

将指定列的值与空字符串匹配，即使它已被引用，如果找到匹配项，请将值设置为`空值`.在空字符串为空的默认情况下，这会将带引号的空字符串转换为 NULL。此选项仅在`复制自`，并且仅在使用时`CSV`格式。

`编码`

指定文件以*`编码名称`*.如果省略此选项，则使用当前客户端编码。有关详细信息，请参阅下面的注释。

`在哪里`

可选的`在哪里`子句具有一般形式

```
WHERE condition
```

在哪里*`（健康）状况`*是任何计算结果类型的表达式`布尔值`.任何不满足此条件的行都不会插入到表中。如果在实际行值替换任何变量引用时返回 true，则该行满足条件。

目前，子查询是不允许的`在哪里`表达式，并且评估看不到由`复制`本身（当表达式包含对`易挥发的`职能）。

## 输出

成功完成后，一个`复制`命令返回形式的命令标签

```
COPY count
```

这*`数数`*是复制的行数。

### 笔记

psql 将仅在命令不存在时打印此命令标记`复制...到标准输出`，或等效的 psql 元命令`\copy ... 到标准输出`.这是为了防止将命令标签与刚刚打印的数据混淆。

## 笔记

`复制到`只能用于普通表，不能用于视图，并且不能从子表或子分区复制行。例如，`复制 *`桌子`* 到`复制相同的行`仅从 * 中选择 *`桌子`*`.语法`复制（选择 * 从 *`桌子`*） 到 ...`可用于转储继承层次结构、分区表或视图中的所有行。

`复制自`可以与普通表、外部表或分区表一起使用，也可以与具有`代替插入`触发器。

您必须对读取其值的表具有选择权限`复制到`, 以及插入值的表的插入权限`复制自`.对命令中列出的列具有列权限就足够了。

如果为表启用了行级安全性，则相关的`选择`政策将适用于`复制 *`桌子`* 到`陈述。目前，`复制自`具有行级安全性的表不支持。使用等价物`插入`而是声明。

以 a 命名的文件`复制`命令由服务器直接读取或写入，而不是由客户端应用程序读取或写入。因此，它们必须驻留在数据库服务器机器上或可供其访问，而不是客户端。它们必须可由 PostgreSQL 用户（服务器运行的用户 ID）访问和读写，而不是客户端。同样，用指定的命令`程序`由服务器直接执行，而不是由客户端应用程序执行，必须由 PostgreSQL 用户执行。`复制`仅允许数据库超级用户或被授予其中一种角色的用户命名文件或命令`pg_read_server_files`,`pg_write_server_files`， 或者`pg_execute_server_program`，因为它允许读取或写入任何文件或运行服务器有权访问的程序。

不要混淆`复制`使用 psql 指令`[\copy](app-psql.html#APP-PSQL-META-COMMANDS-COPY)`.`\复制`调用`从标准输入复制`或者`复制到标准输出`，然后在 psql 客户端可访问的文件中获取/存储数据。因此，文件可访问性和访问权限取决于客户端而不是服务器`\复制`用来。

建议使用的文件名`复制`始终指定为绝对路径。这是由服务器在以下情况下强制执行的`复制到`， 但对于`复制自`您确实可以选择从相对路径指定的文件中读取。该路径将被解释为相对于服务器进程的工作目录（通常是集群的数据目录），而不是客户端的工作目录。

执行命令`程序`可能会受到操作系统的访问控制机制的限制，例如 SELinux。

`复制自`将调用任何触发器并检查目标表上的约束。但是，它不会调用规则。

对于标识列，`复制自`命令将始终写入输入数据中提供的列值，例如`插入`选项`压倒一切的系统价值`.

`复制`输入和输出受`日期样式`.确保对可能使用非默认安装的其他 PostgreSQL 安装的可移植性`日期样式`设置，`日期样式`应该设置为`国际标准化组织`使用前`复制到`.避免使用`间隔样式`设置`sql_standard`，因为负间隔值可能会被具有不同设置的服务器误解为`间隔样式`.

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

`复制`在第一个错误时停止操作。这不应该导致在发生问题时出现问题`复制到`，但目标表已经接收到较早的行`复制自`.这些行将不可见或不可访问，但它们仍会占用磁盘空间。如果故障恰好发生在大型复制操作中，这可能相当于浪费了大量的磁盘空间。您可能希望调用`真空`来回收浪费的空间。

`FORCE_NULL`和`FORCE_NOT_NULL`可以在同一列上同时使用。这导致将带引号的空字符串转换为空值，将不带引号的空字符串转换为空字符串。

## 文件格式

### 文本格式

当。。。的时候`文本`使用格式时，读取或写入的数据是一个文本文件，每行一行。行中的列由分隔符分隔。列值本身是每个属性数据类型的输出函数生成的或输入函数可接受的字符串。指定的空字符串用于代替空列。`复制自`如果输入文件的任何行包含比预期更多或更少的列，则会引发错误。

数据的结尾可以由仅包含反斜杠句点的单行表示（`\。`）。从文件中读取时不需要数据结束标记，因为文件结尾非常好；只有在使用 3.0 之前的客户端协议将数据复制到客户端应用程序或从客户端应用程序复制数据时才需要它。

反斜杠字符 (`\`) 可用于`复制`data 引用可能被视为行或列分隔符的数据字符。特别是以下字符*必须*如果它们作为列值的一部分出现，则以反斜杠开头：反斜杠本身、换行符、回车符和当前分隔符。

指定的空字符串由`复制到`不添加任何反斜杠；反过来，`复制自`在删除反斜杠之前将输入与空字符串匹配。因此，一个空字符串，如`\N`不能与实际数据值混淆`\N`（这将表示为`\\N`）。

以下特殊反斜杠序列由`复制自`：

| 顺序 | 代表 |
| --- | --- |
| `\b` | 退格（ASCII 8） |
| `\f` | 换页 (ASCII 12) |
| `\n` | 换行符（ASCII 10） |
| `\r` | 回车 (ASCII 13) |
| `\t` | 制表符（ASCII 9） |
| `\v` | 垂直制表符 (ASCII 11) |
| `\`*`数字`*\|后跟一到三个八进制数字的反斜杠指定具有该数字代码的字节 |  |
| `\x`*`数字`* | 反斜杠`x`后跟一个或两个十六进制数字指定具有该数字代码的字节 |

目前，`复制到`永远不会发出八进制或十六进制数字的反斜杠序列，但它确实使用上面列出的其他序列来处理这些控制字符。

上表中未提及的任何其他反斜杠字符将被视为代表自身。但是，请注意不要添加不必要的反斜杠，因为这可能会意外生成与数据结束标记匹配的字符串 (`\。`) 或空字符串 (`\N`默认情况下）。这些字符串将在任何其他反斜杠处理完成之前被识别。

强烈建议应用程序生成`复制`数据转换数据换行符和回车到`\n`和`\r`序列分别。目前可以用反斜杠和回车来表示数据回车，用反斜杠和换行来表示数据换行。但是，这些表示形式可能不会在未来的版本中被接受。他们也很容易受到腐败的影响，如果`复制`文件在不同的机器之间传输（例如，从 Unix 到 Windows，反之亦然）。

所有反斜杠序列都在编码转换后进行解释。用八进制和十六进制数字反斜杠序列指定的字节必须在数据库编码中形成有效字符。

`复制到`将以 Unix 风格的换行符终止每一行（“`\n`”）。在 Microsoft Windows 上运行的服务器改为输出回车/换行符（“`\r\n`”），但仅适用于`复制`到服务器文件；为了跨平台的一致性，`复制到标准输出`总是发送“`\n`” 无论服务器平台如何。`复制自`可以处理以换行符、回车符或回车符/换行符结尾的行。为了降低由于作为数据的未反斜杠换行符或回车而导致的错误风险，`复制自`如果输入中的行结尾不完全相同，则会抱怨。

### CSV 格式

此格式选项用于导入和导出逗号分隔值 (`CSV`) 许多其他程序（例如电子表格）使用的文件格式。代替 PostgreSQL 标准文本格式使用的转义规则，它生成并识别常见的 CSV 转义机制。

每条记录中的值由`分隔符`特点。如果值包含分隔符，则`引用`性格`空值`字符串、回车符或换行符，则整个值都以`引用`字符，以及任何出现在 a 的值中`引用`性格或`逃脱`字符前面是转义字符。你也可以使用`FORCE_QUOTE`在输出非时强制引用`空值`特定列中的值。

这`CSV`格式没有标准的方法来区分`空值`来自空字符串的值。PostgreSQL的`复制`通过引用来处理这个问题。一种`空值`输出为`空值`参数字符串并且不被引用，而一个非`空值`匹配的值`空值`参数字符串被引用。例如，在默认设置下，`空值`写为不带引号的空字符串，而空字符串数据值用双引号 (`“”`）。读取值遵循类似的规则。您可以使用`FORCE_NOT_NULL`阻止`空值`特定列的输入比较。你也可以使用`FORCE_NULL`将带引号的空字符串数据值转换为`空值`.

因为反斜杠在`CSV`格式，`\。`，数据结束标记，也可以显示为数据值。为避免任何误解，`\。`在一行中作为单独条目出现的数据值在输出时自动引用，并且在输入时，如果引用，则不会被解释为数据结束标记。如果您正在加载由另一个应用程序创建的文件，该文件具有一个未加引号的列并且可能具有值`\。`，您可能需要在输入文件中引用该值。

### 笔记

在`CSV`格式，所有字符都有意义。由空格或任何字符以外的字符包围的引用值`分隔符`, 将包括这些字符。如果您从填充的系统导入数据，这可能会导致错误`CSV`带有空白的线条到某个固定宽度。如果出现这种情况，您可能需要预处理`CSV`文件以删除尾随空格，然后再将数据导入 PostgreSQL。

### 笔记

CSV 格式将识别和生成带有包含嵌入式回车和换行符的引用值的 CSV 文件。因此，这些文件并不像文本格式文件那样严格地每表行一行。

### 笔记

许多程序会生成奇怪且偶尔不正常的 CSV 文件，因此文件格式与其说是标准，不如说是一种约定。因此，您可能会遇到一些无法使用此机制导入的文件，并且`复制`可能会产生其他程序无法处理的文件。

### 二进制格式

这`二进制`format option causes all data to be stored/read as binary format rather than as text. It is somewhat faster than the text and`CSV`formats, but a binary-format file is less portable across machine architectures and PostgreSQL versions. Also, the binary format is very data type specific; for example it will not work to output binary data from a`smallint`column and read it into an`integer`column, even though that would work fine in text format.

The`binary`file format consists of a file header, zero or more tuples containing the row data, and a file trailer. Headers and data are in network byte order.

### Note

PostgreSQL releases before 7.4 used a different binary file format.

#### File Header

The file header consists of 15 bytes of fixed fields, followed by a variable-length header extension area. The fixed fields are:

Signature

11-byte sequence`PGCOPY\n\377\r\n\0`— note that the zero byte is a required part of the signature. (The signature is designed to allow easy identification of files that have been munged by a non-8-bit-clean transfer. This signature will be changed by end-of-line-translation filters, dropped zero bytes, dropped high bits, or parity changes.)

Flags field

32-bit integer bit mask to denote important aspects of the file format. Bits are numbered from 0 (LSB) to 31 (MSB). Note that this field is stored in network byte order (most significant byte first), as are all the integer fields used in the file format. Bits 16–31 are reserved to denote critical file format issues; a reader should abort if it finds an unexpected bit set in this range. Bits 0–15 are reserved to signal backwards-compatible format issues; a reader should simply ignore any unexpected bits set in this range. Currently only one flag bit is defined, and the rest must be zero:

Bit 16

If 1, OIDs are included in the data; if 0, not. Oid system columns are not supported in PostgreSQL anymore, but the format still contains the indicator.

Header extension area length

32-bit integer, length in bytes of remainder of header, not including self. Currently, this is zero, and the first tuple follows immediately. Future changes to the format might allow additional data to be present in the header. A reader should silently skip over any header extension data it does not know what to do with.

The header extension area is envisioned to contain a sequence of self-identifying chunks. The flags field is not intended to tell readers what is in the extension area. Specific design of header extension contents is left for a later release.

This design allows for both backwards-compatible header additions (add header extension chunks, or set low-order flag bits) and non-backwards-compatible changes (set high-order flag bits to signal such changes, and add supporting data to the extension area if needed).

#### Tuples

Each tuple begins with a 16-bit integer count of the number of fields in the tuple. (Presently, all tuples in a table will have the same count, but that might not always be true.) Then, repeated for each field in the tuple, there is a 32-bit length word followed by that many bytes of field data. (The length word does not include itself, and can be zero.) As a special case, -1 indicates a NULL field value. No value bytes follow in the NULL case.

There is no alignment padding or any other extra data between fields.

目前，二进制格式文件中的所有数据值都假定为二进制格式（格式代码一）。预计未来的扩展可能会添加一个允许指定每列格式代码的标题字段。

要确定实际元组数据的适当二进制格式，您应该查阅 PostgreSQL 源，特别是`*发送`和`*接收`每个列的数据类型的函数（通常这些函数位于`src/后端/utils/adt/`源分发目录）。

如果文件中包含 OID，则 OID 字段紧跟在字段计数字之后。它是一个普通字段，只是它不包含在字段计数中。请注意，当前版本的 PostgreSQL 不支持 oid 系统列。

#### 文件预告片

文件尾部由一个包含 -1 的 16 位整数字组成。这很容易与元组的字段计数词区分开来。

如果字段计数字既不是 -1 也不是预期的列数，阅读器应该报告错误。这提供了额外的检查，以防止以某种方式与数据不同步。

## 例子

以下示例使用竖线 (`|`) 作为字段分隔符：

```
COPY country TO STDOUT (DELIMITER '|');
```

要将文件中的数据复制到`国家`桌子：

```
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';
```

这是一个适合复制到表中的数据示例`标准输入`：

```
AF      AFGHANISTAN
AL      ALBANIA
DZ      ALGERIA
ZM      ZAMBIA
ZW      ZIMBABWE
```

请注意，每一行的空格实际上是一个制表符。

以下是相同的数据，以二进制格式输出。数据通过 Unix 实用程序过滤后显示`od -c`.该表有三列；第一个有类型`字符（2）`，第二个有类型`文本`, 第三个有类型`整数`.所有行在第三列中都有一个空值。

```
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 标准中的语句。

以下语法在 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 [, ...] | * } ] ] ]
```

请注意，在此语法中，`二进制`和`CSV`被视为独立的关键字，而不是 a 的参数`格式`选项。

以下语法在 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' ]
```

## 也可以看看

[第 28.4.6 节](progress-reporting.html#COPY-PROGRESS-REPORTING)