0Pricing
PostgreSQL Performance & Query Optimization · 课时

COPY 与多行 INSERT 的吞吐量

在真实约束下进行基准测试，选择每秒处理行数最高的数据导入方式。

COPY 与多行 INSERT 的吞吐量 是 CoddyKit 上的免费 PostgreSQL Performance & Query Optimization 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 PostgreSQL Performance & Query Optimization 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 PostgreSQL Performance & Query Optimization 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Ingestion Speed Matters

When you load millions of rows into PostgreSQL, the method you choose determines whether the job takes seconds or hours. This lesson benchmarks the two main ingestion paths: COPY and multi-row INSERT.

  • COPY streams rows through a single, optimized bulk path.
  • Multi-row INSERT packs many tuples into one statement to amortize round-trips.

The right choice depends on data source, round-trip cost, and how the rows arrive.

The Naive Baseline: Single-Row INSERT

The slowest pattern is one row per statement. Each statement pays for parsing, planning, a network round-trip, and (without batching) a separate commit.

At thousands of rows, the per-statement overhead dominates and throughput collapses. This is the baseline every other method beats.

-- Slow: one round-trip and (by default) one commit per row
INSERT INTO events (user_id, kind, payload) VALUES (1, 'click', '{}');
INSERT INTO events (user_id, kind, payload) VALUES (2, 'view',  '{}');
INSERT INTO events (user_id, kind, payload) VALUES (3, 'click', '{}');
-- ... repeated 1,000,000 times

Multi-Row INSERT: Amortizing Round-Trips

A multi-row INSERT lists many tuples in one statement. You pay parse and plan cost once, send one network round-trip, and commit the whole batch together.

  • A good batch size is typically 500 to 5,000 rows per statement.
  • Going much higher gives diminishing returns and bloats the parsed statement.
-- One statement, one round-trip, many rows
INSERT INTO events (user_id, kind, payload) VALUES
  (1, 'click', '{}'),
  (2, 'view',  '{}'),
  (3, 'click', '{}'),
  (4, 'view',  '{}');
-- typically 500-5000 tuples per statement

COPY: The Bulk Highway

COPY is PostgreSQL's purpose-built bulk loader. It bypasses per-row statement parsing entirely and streams rows through a tight loop, making it usually the fastest way to ingest large volumes.

  • COPY ... FROM loads data into a table.
  • It reads text, CSV, or binary formats.

Server-side COPY FROM 'file' requires superuser or the pg_read_server_files role; clients usually use \copy instead.

-- Server-side COPY from a CSV file (needs file access privileges)
COPY events (user_id, kind, payload)
FROM '/data/events.csv'
WITH (FORMAT csv, HEADER true);

Client-Side \copy and COPY FROM STDIN

When the file lives on the client (not the server), use psql's \copy meta-command or COPY ... FROM STDIN. These stream data over the existing client connection, so no special server file privileges are needed.

Most ETL drivers (psycopg, JDBC, libpq) expose a streaming COPY FROM STDIN API that is the fastest programmatic load path.

-- psql meta-command: file is read on the CLIENT machine
\copy events (user_id, kind, payload) FROM 'events.csv' WITH (FORMAT csv, HEADER true)

-- Equivalent SQL that streams from the client connection
COPY events (user_id, kind, payload) FROM STDIN WITH (FORMAT csv);

Why COPY Wins: Less Per-Row Work

The throughput gap comes from what each row costs:

  • Single INSERT: parse + plan + execute + round-trip + commit per row.
  • Multi-row INSERT: parse + plan once per batch; still builds a full parse tree for every tuple.
  • COPY: no SQL parsing per row at all; values are decoded directly into tuples.

COPY also generates fewer WAL records per row of work, which is a large part of its speed advantage.

Benchmarking Fairly

To compare methods honestly, hold everything else constant and measure wall-clock time plus rows per second. Use \timing in psql, or wrap loads in a timed harness.

  • Load the same dataset each run.
  • TRUNCATE between runs so you start from an empty, comparable state.
  • Run each method a few times and take the median to dampen noise.
\timing on

TRUNCATE events;
-- run method A (multi-row INSERT batches), note the time

TRUNCATE events;
-- run method B (COPY FROM), note the time

-- rows_per_second = row_count / elapsed_seconds

Transactions and Commit Costs

A common reason single-row INSERTs are slow is one commit per row. Each commit forces a WAL flush (an fsync) to disk. Wrapping many inserts in a single transaction collapses thousands of fsyncs into one.

Both COPY and multi-row INSERT already commit per-statement, but if you script many statements, wrap them in one explicit transaction.

BEGIN;
INSERT INTO events (user_id, kind) VALUES (1, 'click');
INSERT INTO events (user_id, kind) VALUES (2, 'view');
-- ... many statements, ONE fsync at the end
COMMIT;

Indexes, Triggers, and Constraints Slow Loads

The fastest ingestion method still crawls if every inserted row must update five indexes and fire triggers. A classic bulk-load tactic is to load first, then build indexes.

  • Drop or disable non-essential indexes, then recreate them after the load.
  • Building an index once over the full table is far cheaper than maintaining it row by row.
  • Disable expensive triggers during the load when the data is trusted.
-- Bulk-load pattern: strip overhead, load, then rebuild
DROP INDEX IF EXISTS idx_events_user_id;

COPY events (user_id, kind, payload)
FROM '/data/events.csv' WITH (FORMAT csv, HEADER true);

CREATE INDEX idx_events_user_id ON events (user_id);

UNLOGGED Tables and Staging

For transient staging data, an UNLOGGED table skips WAL writes entirely, which can dramatically speed up loads. The trade-off: unlogged tables are not crash-safe and are truncated after a crash.

A robust ETL pattern loads into an unlogged or temporary staging table with COPY, transforms it, then inserts the clean result into the durable target.

-- Fast, non-durable staging area for ETL
CREATE UNLOGGED TABLE events_staging (
  user_id integer,
  kind    text,
  payload jsonb
);

COPY events_staging FROM '/data/events.csv' WITH (FORMAT csv, HEADER true);

INSERT INTO events SELECT * FROM events_staging WHERE kind IS NOT NULL;

Choosing Under Real Constraints

Pick the method that fits how the data arrives:

  • Bulk file or stream available? Use COPY / \copy — it is the throughput winner.
  • Rows arrive programmatically in code? Prefer your driver's COPY FROM STDIN; if unavailable, fall back to multi-row INSERT in batches of 500-5,000.
  • Need per-row conflict handling (ON CONFLICT)? COPY can't do that — use multi-row INSERT, or COPY to a staging table then UPSERT.
-- COPY has no ON CONFLICT; stage then upsert when you need it
COPY events_staging FROM STDIN WITH (FORMAT csv);

INSERT INTO events AS e (user_id, kind, payload)
SELECT user_id, kind, payload FROM events_staging
ON CONFLICT (user_id, kind) DO UPDATE
  SET payload = EXCLUDED.payload;

Quick Check: Maximize Throughput

Test your understanding of the core ingestion decision.

Recap

You can now benchmark and choose ingestion methods deliberately:

  • COPY / \copy is the throughput winner for bulk file and streaming loads; it skips per-row parsing and minimizes WAL.
  • Multi-row INSERT (500-5,000 rows per statement) beats single-row inserts and is the fallback when you need ON CONFLICT.
  • Wrap loads in one transaction to avoid per-row fsync costs.
  • Drop indexes, disable triggers, use UNLOGGED staging tables to remove per-row overhead, then rebuild.
  • Benchmark fairly: same data, TRUNCATE between runs, \timing, take the median rows/second.

常见问题解答

「COPY 与多行 INSERT 的吞吐量」课时是免费的吗？

是的 — 「COPY 与多行 INSERT 的吞吐量」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 PostgreSQL Performance & Query Optimization 课程的其余内容，请升级到 CoddyKit PRO。 PostgreSQL Performance & Query Optimization 课程共包含 4 节课。

「COPY 与多行 INSERT 的吞吐量」这节课中我会学到什么？

在真实约束下进行基准测试，选择每秒处理行数最高的数据导入方式。 你通过在浏览器中直接运行的动手代码来练习 PostgreSQL Performance & Query Optimization，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 PostgreSQL Performance & Query Optimization 需要有经验吗？

无需任何先前经验。CoddyKit 上的 PostgreSQL Performance & Query Optimization 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「COPY 与多行 INSERT 的吞吐量」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 PostgreSQL Performance & Query Optimization 课中编写并运行代码吗？

能。每节 PostgreSQL Performance & Query Optimization 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. COPY 与多行 INSERT 的吞吐量
  2. 导入期间延后建立索引与约束
  3. 调整 WAL 与检查点以优化数据导入
  4. 使用 ON CONFLICT 实现大规模插入或更新
← 返回 PostgreSQL Performance & Query Optimization