PostgreSQL 的 COPY 命令

PostgreSQL 的 COPY 命令是高效数据导入导出的核心工具，性能远超常规 INSERT 语句。以下是 COPY 命令的深度解析：

一 COPY 命令基础

1.1 基本语法对比

命令类型	语法示例	执行位置	文件访问权限
服务器端COPY	COPY table FROM '/path/file.csv';	数据库服务器	需要postgres系统用户权限
客户端COPY	\copy table FROM 'file.csv';	客户端机器	使用客户端用户权限

1.2 核心功能矩阵

功能	COPY FROM	COPY TO
数据加载速度	每秒万行级	每秒万行级
事务处理	单事务操作	单事务操作
二进制支持	是	是
错误处理	可跳过错误行	-

二 高级使用技巧

2.1 复杂数据转换

-- 导入时转换数据类型
COPY users(id, name, reg_date) 
FROM '/data/users.csv' 
WITH (FORMAT csv, HEADER,
      DELIMITER '|',
      NULL 'NULL',
      FORCE_NOT_NULL (id, name),
      ENCODING 'UTF8');

2.2 条件导出

-- 导出查询结果
COPY (SELECT * FROM orders WHERE order_date > '2025-01-01') 
TO '/data/recent_orders.csv' 
WITH (FORMAT csv, HEADER);

三 性能优化方案

3.1 批量加载最佳实践

# 使用并行加载（拆分文件后）
for i in {1..4}; do
  psql -c "COPY large_table FROM '/data/part$i.csv' WITH (FORMAT csv)" &
done
wait

3.2 关键性能参数

参数	推荐值	影响
maintenance_work_mem	1GB+	提高导入排序效率
max_wal_size	4GB+	减少WAL检查点
synchronous_commit	off	禁用同步提交加速导入

四 异常处理机制

4.1 错误日志记录

-- 创建错误日志表
CREATE TABLE import_errors (
    line_num integer,
    error_msg text,
    raw_data text
);

-- 带错误记录的导入
BEGIN;
CREATE TEMP TABLE temp_import (LIKE target_table);
COPY temp_import FROM '/data/source.csv' 
  WITH (FORMAT csv, HEADER);
INSERT INTO target_table
  SELECT * FROM temp_import
  ON CONFLICT DO NOTHING;
INSERT INTO import_errors
  SELECT pg_copy_log();
COMMIT;

4.2 二进制格式处理

# 导出二进制数据
pg_dump -t table_name -Fc -f output.dump dbname

# 二进制文件转换
pg_restore -l output.dump > output.list

五 监控与维护

5.1 性能监控查询

-- 查看COPY操作历史
SELECT query, duration 
FROM pg_stat_statements 
WHERE query LIKE 'COPY%' 
ORDER BY duration DESC;

-- 检查导入进度（PostgreSQL 14+）
SELECT pid, query, pg_stat_get_progress_info('COPY') 
FROM pg_stat_activity 
WHERE backend_type = 'client backend';

5.2 维护建议

1. 定期清理临时文件：COPY操作可能产生大量WAL日志
2. 版本升级验证：不同PostgreSQL版本COPY行为可能有差异
3. 网络优化：跨数据中心传输时考虑压缩选项

COPY命令是PostgreSQL数据迁移的核心工具，掌握其高级用法可以显著提升ETL效率。对于TB级数据迁移，建议：

• 使用二进制格式减少I/O
• 结合表分区并行加载
• 在维护窗口禁用WAL归档
• 考虑使用pg_bulkload扩展处理超大规模数据

更详细内容请查看官方文档：

https://www.postgresql.org/docs/17/sql-copy.html

谨记：心存敬畏，行有所止。