PricingLoginStart free
PostgreSQL Performance & Query Optimization · レッスン

ON CONFLICTによる大規模Upsert

ロック競合と膨張を避けながら、大きなバッチ向けの効率的なマージ処理を実装します。

レッスン 4/413 ステップ

「ON CONFLICTによる大規模Upsert」はCoddyKit上の無料PostgreSQL Performance & Query Optimizationレッスンです。 これはレッスン4/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはPostgreSQL Performance & Query Optimization学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 PostgreSQL Performance & Query Optimizationコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Upserts Need Care at Scale

An upsert inserts a row, but if it would collide with an existing key, it updates the existing row instead. PostgreSQL spells this INSERT ... ON CONFLICT.

For small workloads it is trivial. For ETL-sized batches (tens of thousands to millions of rows) the naive approach causes three problems:

  • Lock contention — concurrent writers fighting over the same rows or index pages.
  • Table bloat — every UPDATE writes a new row version (dead tuple) that VACUUM must later reclaim.
  • WAL and round-trip overhead — row-by-row upserts multiply network and transaction cost.

This lesson builds a merge that is both correct and throughput-friendly.

The ON CONFLICT Shape

ON CONFLICT requires a conflict target: the column(s) or constraint that define a duplicate. PostgreSQL needs a unique or exclusion constraint on that target to arbitrate.

The two actions are DO NOTHING (skip the colliding row) and DO UPDATE (merge new values in).

Inside DO UPDATE, the incoming row is exposed through the special EXCLUDED pseudo-table.

INSERT INTO products (sku, name, price)
VALUES ('A-100', 'Widget', 9.99)
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price;

One Statement, Many Rows

The single most important throughput rule: batch your rows into one statement. A multi-row VALUES list (or a feeding SELECT) is parsed, planned, and committed once instead of N times.

This collapses N network round-trips and N transaction commits into one, often a 10-100x speedup over row-by-row upserts.

INSERT INTO products (sku, name, price)
VALUES
  ('A-100', 'Widget', 9.99),
  ('A-101', 'Gadget', 14.50),
  ('A-102', 'Gizmo', 7.25)
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price;

Staging Table + INSERT...SELECT

For real ETL, load raw data into an unlogged staging table first (often via COPY, the fastest bulk path), then merge from staging into the target with one INSERT ... SELECT ... ON CONFLICT.

Benefits:

  • COPY avoids per-row INSERT overhead.
  • An UNLOGGED staging table skips WAL for the load phase.
  • You can dedupe and transform in the SELECT before merging.
CREATE UNLOGGED TABLE products_stage (LIKE products);

-- bulk load: COPY products_stage FROM '/data/products.csv' CSV;

INSERT INTO products (sku, name, price)
SELECT sku, name, price FROM products_stage
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price;

Deduplicate the Batch First

A subtle but fatal error: a single INSERT statement cannot update the same target row twice. If your batch contains two rows with the same conflict key, PostgreSQL raises:

ERROR: ON CONFLICT DO UPDATE command cannot affect row a second time

Fix it by collapsing duplicates in the source before merging. DISTINCT ON keeps one row per key — typically the newest.

INSERT INTO products (sku, name, price)
SELECT DISTINCT ON (sku) sku, name, price
FROM products_stage
ORDER BY sku, updated_at DESC
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price;

Skip No-Op Updates to Cut Bloat

Every DO UPDATE writes a new row version, even when the new values are identical to the old ones. Those dead tuples bloat the table and create extra work for VACUUM.

Add a WHERE clause to the DO UPDATE so it fires only when something actually changed. Use IS DISTINCT FROM so NULLs compare correctly.

INSERT INTO products (sku, name, price)
SELECT sku, name, price FROM products_stage
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price
WHERE products.name  IS DISTINCT FROM EXCLUDED.name
   OR products.price IS DISTINCT FROM EXCLUDED.price;

Order Batches to Tame Lock Contention

When several ETL workers run concurrently, deadlocks appear if they touch the same keys in different orders. Worker 1 locks key X then Y; worker 2 locks Y then X — both block forever until PostgreSQL kills one.

Defenses:

  • Sort each batch by the conflict key so all workers acquire locks in the same order.
  • Partition work by key range so no two workers share keys.
  • Keep transactions short — long-held row locks magnify contention.
INSERT INTO products (sku, name, price)
SELECT sku, name, price
FROM products_stage
ORDER BY sku            -- consistent lock acquisition order
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price;

Chunk Giant Merges

One enormous transaction merging millions of rows holds locks for a long time, balloons WAL, and blocks autovacuum from cleaning up. Break the work into chunks (for example 10k-50k rows) and commit between them.

Smaller transactions release locks sooner, let autovacuum keep pace, and make retries cheap after a failure. The trade-off is slightly more commit overhead — tune the chunk size against your hardware.

-- Merge one bounded slice; loop over key ranges from the app side.
INSERT INTO products (sku, name, price)
SELECT sku, name, price
FROM products_stage
WHERE sku >= 'A-0000' AND sku < 'A-5000'
ON CONFLICT (sku) DO UPDATE
  SET name  = EXCLUDED.name,
      price = EXCLUDED.price;

Choosing the Right Conflict Target

The conflict target must match an actual unique/primary-key or exclusion constraint. You can target by column list ON CONFLICT (sku) or by constraint name ON CONFLICT ON CONSTRAINT products_sku_key.

For partial unique indexes, repeat the index predicate so PostgreSQL can pick the right one:

-- Unique only among active rows
CREATE UNIQUE INDEX products_active_sku
  ON products (sku) WHERE is_active;

INSERT INTO products (sku, name, is_active)
VALUES ('A-100', 'Widget', true)
ON CONFLICT (sku) WHERE is_active DO UPDATE
  SET name = EXCLUDED.name;

ON CONFLICT vs MERGE

PostgreSQL 15+ adds the SQL-standard MERGE, which can INSERT, UPDATE, and DELETE in one pass. For high-throughput upserts, INSERT ... ON CONFLICT is usually still preferred:

  • ON CONFLICT is atomic against concurrent inserts — it handles a race where another transaction inserts the same key, retrying internally.
  • Classic MERGE can raise a unique-violation under heavy concurrency because it does not have that built-in conflict arbitration.

Use MERGE when you need DELETE branches or complex conditional logic; use ON CONFLICT for plain, concurrency-safe upserts.

Maintenance: VACUUM and Indexes

Even an optimized merge produces dead tuples on the updated rows. Keep performance steady with maintenance discipline:

  • Ensure autovacuum keeps up; for hot ETL tables lower autovacuum_vacuum_scale_factor so it triggers more often.
  • After a massive one-off backfill, run VACUUM (ANALYZE) to reclaim space and refresh planner statistics.
  • Every extra index on the target slows the merge (each insert/update maintains all of them) — keep only the indexes you truly need.
VACUUM (ANALYZE) products;

Quick Check

Test your understanding of safe, high-throughput merges.

対話的なレッスンで答える

Recap

Efficient upserts at scale come from a few combined habits:

  • Batch rows into one statement; for ETL, stage with COPY then INSERT ... SELECT ... ON CONFLICT.
  • Deduplicate the batch (DISTINCT ON) so no key appears twice.
  • Skip no-op updates with a WHERE ... IS DISTINCT FROM clause to curb dead tuples and bloat.
  • Order by the conflict key and partition work to avoid deadlocks; chunk huge merges into short transactions.
  • Prefer ON CONFLICT for concurrency-safe upserts; keep autovacuum healthy and indexes lean.

Together these turn a fragile row-by-row merge into a fast, low-contention ETL load.

無料で開始

AI チューターと学ぶ SQL — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース
22
レッスン
88
無料で学習を始めるコース全体を表示

よくある質問

「ON CONFLICTによる大規模Upsert」レッスンは無料ですか？

はい。「ON CONFLICTによる大規模Upsert」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、PostgreSQL Performance & Query Optimizationコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 PostgreSQL Performance & Query Optimizationコースには全4レッスンが含まれています。

「ON CONFLICTによる大規模Upsert」で何を学びますか？

ロック競合と膨張を避けながら、大きなバッチ向けの効率的なマージ処理を実装します。 ブラウザで直接実行するハンズオンコードでPostgreSQL Performance & Query Optimizationを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

PostgreSQL Performance & Query Optimizationを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのPostgreSQL Performance & Query Optimizationは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン4/4です。

「ON CONFLICTによる大規模Upsert」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このPostgreSQL Performance & Query Optimizationレッスンでコードを書いて実行できますか？

はい。すべてのPostgreSQL Performance & Query Optimizationレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. COPYと複数行INSERTのスループット
  2. ロード中のインデックスと制約の延期
  3. 取り込みに向けたWALとチェックポイントのチューニング
  4. ON CONFLICTによる大規模Upsert
← PostgreSQL Performance & Query Optimizationに戻る