\COPY 命令是用来直接从你本地电脑把数据导入 PostgreSQL 的。和 COPY 不一样，COPY 只能操作 PostgreSQL 服务器上的文件，而 \COPY 能操作你客户端这边的文件，比如你笔记本或者台式机上的文件。
当你要用本地电脑上的文件（比如笔记本上的 CSV），就用 \COPY。COPY 只能读服务器上的文件，而 \COPY 让你直接导入手边的数据。
这种方式特别适合你在自己电脑上开发或测试项目，或者你根本没法访问 PostgreSQL 服务器的文件系统。开发者和数据分析师经常用这个方法，能很快把 CSV 文件导进来测试点啥，不用折腾太多。
COPY 和 \COPY 的区别
乍一看 COPY 和 \COPY 很像，但其实它们的工作原理不一样：
COPY在服务器端执行，要求文件必须在 PostgreSQL 能访问的目录里。PostgreSQL 还得有权限读这个文件。\COPY在客户端执行，也就是说文件要在你用的客户端程序（比如psql）能访问的地方。用\COPY，你可以导入你电脑上的文件，就算你没法访问服务器也没关系。
\COPY 的基本用法
命令语法：
\COPY 表名 FROM 'file_path' [WITH] (选项)
解释一下：
表名：你要导入数据的表名。file_path：你本地电脑上文件的路径。选项：可选参数，可以自定义导入行为。
例子：
\COPY students FROM 'C:/data/students.csv' DELIMITER ',' CSV HEADER;
students：要导入数据的表名。'C:/data/students.csv'：你本地电脑上的文件路径。DELIMITER ','：指定文件里的分隔符（这里是逗号）。CSV HEADER：说明文件第一行是列名。
例子：
假设你有个 students.csv 文件，里面是学生数据，放在你本地文件夹，比如 C:/data/students.csv。内容如下：
id,name,age,major
1,John Doe,20,Computer Science
2,Jane Smith,22,Mathematics
3,Emily White,21,Physics
我们要把这些数据导入 students 表。先在 PostgreSQL 里建个表，结构如下：
CREATE TABLE students (
id SERIAL PRIMARY KEY,
name TEXT NOT NULL,
age INTEGER NOT NULL,
major TEXT
);
现在用 \COPY 命令导入数据：
\COPY students FROM 'C:/data/students.csv' DELIMITER ',' CSV HEADER;
执行完这个命令后，students 表里就有了 students.csv 文件里的三条记录。你可以这样查一下：
SELECT * FROM students;
预期结果：
| id | name | age | major |
|---|---|---|---|
| 1 | John Doe | 20 | Computer Science |
| 2 | Jane Smith | 22 | Mathematics |
| 3 | Emily White | 21 | Physics |
\COPY 命令的参数
用 \COPY（特别是 CSV 格式）时，下面这些参数很常用，可以帮你控制数据格式，让导入更顺手：
FORMAT 参数
指定数据格式。最常用的是 text 和 csv。
例子：
\COPY users FROM 'users.csv' WITH (FORMAT csv)
为啥要用： 不加这个参数，PostgreSQL 默认用 tab 分隔的文本格式。csv 更通用也更好读。
HEADER 参数
说明 CSV 文件第一行是列名，不是数据。
例子：
\COPY users FROM 'users.csv' WITH (FORMAT csv, HEADER)
为啥要用： 可以跳过表头，特别适合从 Excel 或别的系统导出的文件。
DELIMITER 参数
指定字段分隔符。CSV 默认是逗号，TEXT 默认是 tab。
例子：
\COPY products FROM 'products.csv' WITH (FORMAT csv, DELIMITER ';')
为啥要用： 有些 CSV 文件用分号分隔（欧洲很常见），这个参数能适应各种格式。
ENCODING 参数
指定文件编码。
例子：
\COPY clients FROM 'clients.csv' WITH (FORMAT csv, HEADER, ENCODING 'WIN1251')
为啥要用： 能正确导入 Windows 或其他系统编码的文件，不用手动转码。
NULL 参数
定义文件里哪个字符串算 NULL。
例子：
\COPY orders FROM 'orders.csv' WITH (FORMAT csv, NULL 'NULL')
为啥要用： 有些文件缺失值用 'NULL' 字符串表示，这样能正确识别成空值。
\COPY 的限制和注意事项
1. PostgreSQL 客户端要求
psql 是支持 \COPY 命令的 PostgreSQL 客户端。一定要用它来操作数据库。别的客户端，比如 pgAdmin，可能不支持 \COPY。
2. 文件编码
注意你导入的文件编码。PostgreSQL 默认要 UTF-8。如果文件是别的编码（比如 Windows-1251），可能会报错。你可以用 iconv 或文本编辑器（比如 VS Code）转成 UTF-8。
3. 文件路径格式
Windows 下路径可能有反斜杠（\）。建议都换成正斜杠（/）。比如用 C:/data/students.csv 代替 C:\data\students.csv。
常见错误和解决办法
1. 文件访问错误。
如果你看到类似：
could not open file "C:/data/students.csv" for reading: No such file or directory
请确认：
- 文件确实在你写的路径下。
- 你写的是绝对路径。
- 你有权限访问这个文件。
2. 数据结构不匹配错误。 如果文件结构和表结构不一样，会报错。比如文件多了列或者数据类型不对，就会出错。导入前先检查下列名和类型。
3. 编码问题。 如果不是 UTF-8 编码，导入后会看到乱码。解决办法：导入前先转成 UTF-8。
用 \COPY 的优点
1. 简单易用。 一条命令就能导入数据，不用把文件传到服务器。
2. 通用性强。 psql 支持所有主流操作系统，\COPY 基本哪都能用。
3. 没有服务器文件权限问题。 因为命令在客户端执行，不用担心服务器文件权限。
限制和建议
虽然很方便，\COPY 也有点限制：
- 不适合超大文件，因为数据要通过网络传输。大文件建议直接在服务器用
COPY。 - 确保你的文件已经准备好：修好错误、删掉多余的行，结构和表一致。
大项目建议先用小文件测试导入，没问题再导全量数据。
GO TO FULL VERSION