RETURNING 句を使うと、INSERT、UPDATE、DELETE 文が、影響を与えた行に関するデータを返すことができます。最もよく使われるのは挿入後に自動生成された ID を取得する用途ですが、任意のカラムや計算した値を返すこともできます。これにより別途クエリを発行する手間が省け、PostgreSQL の便利な機能となっています。
RETURNING 句を使うと、INSERT、UPDATE、DELETE 文が、影響を与えた行に関するデータを返すことができます。最もよく使われるのは挿入後に自動生成された ID を取得する用途ですが、任意のカラムや計算した値を返すこともできます。これにより別途クエリを発行する手間が省け、PostgreSQL の便利な機能となっています。
-- get the auto-generated id back from the insert (no separate SELECT needed)
INSERT INTO users (name, email) VALUES ('Ann', '[email protected]')
RETURNING id; -- returns the new id
-- return multiple columns or all of them
INSERT INTO users (name) VALUES ('Bob')
RETURNING id, name, created_at; -- including DB-generated values
INSERT INTO users (name) VALUES ('Carol') RETURNING *; -- the whole row
最もよくある用途は次のとおりです。挿入後には通常、（関連する挿入で使ったり、クライアントに返したりするために）生成された主キーが必要になります。RETURNING id を使えばそれを直接取得でき、別途クエリを発行する必要がありません。
-- see what was updated
UPDATE products SET price = price * 1.1 WHERE category = 'books'
RETURNING id, name, price; -- the NEW values after the update
-- capture deleted rows (e.g. for archiving/logging)
DELETE FROM sessions WHERE expired = true
RETURNING id, user_id; -- which rows were deleted
RETURNING は UPDATE（更新後の新しい値を確認する）でも DELETE（削除された行を取得する。アーカイブや確認に便利）でも動作します。
Without RETURNING:
INSERT ...; then a separate SELECT to get the id → TWO round-trips, and a potential
race (the SELECT might not reliably get YOUR row).
With RETURNING:
one statement returns the affected data atomically → fewer round-trips, no race.
-- use a CTE with RETURNING to insert and use the id in the same statement
WITH new_user AS (
INSERT INTO users (name) VALUES ('Ann') RETURNING id
)
INSERT INTO profiles (user_id, bio)
SELECT id, 'Hello' FROM new_user; -- use the returned id directly
RETURNING 句は便利で頻繁に使われる PostgreSQL の機能であり、データを変更する際の効率性と正確性の点で価値があります。
最も一般的で重要な用途は、INSERT から自動生成された ID を取得することです。これはほぼ普遍的なニーズであり（挿入後には、関連する操作で使ったりアプリケーションに返したりするために、新しい主キーがほぼ必ず必要になります）、RETURNING id がそれを 1 つの文で直接提供してくれます。
RETURNING がなければ、生成された ID を取得するために別途 SELECT が必要になり、これは追加のラウンドトリップと潜在的な競合状態（同時実行のシナリオでは、その別の SELECT が必ずしも自分の特定の行を確実に取得できるとは限らない）を意味します。そのため RETURNING はより効率的かつより正確です。
挿入以外にも、RETURNING は UPDATE（更新後の新しい値を確認する）や DELETE（削除された行を取得する。アーカイブ、ログ記録、削除の確認に便利）でも動作します。
CTE と組み合わせれば、返された ID を使って関連テーブルへの挿入を 1 つの文で行うといった強力なパターンが実現できます。
データ変更後に生成された値（特に ID）を取得することは常に必要とされ、RETURNING はそれを効率的かつ原子的に（余分なクエリや競合状態を回避して）提供してくれるため、RETURNING 句を理解することは価値があり頻繁に応用される PostgreSQL の知識です。これはデータ変更のコードをより明確に、より効率的に、より正確にしてくれるものであり、Postgres を扱う実際のアプリケーションで日常的に使われる実用的な利便性です。特に挿入後に生成された ID を取得するという普遍的なニーズにおいて重要です。