【初心者向け】PostgreSQL RETURNING句の入門ガイド

はじめに：なぜPostgreSQLのRETURNING句を学ぶべきなのか？

PostgreSQLを使っている皆さん、こんにちは！データベース操作、特にデータの追加（INSERT）、更新（UPDATE）、削除（DELETE）は、アプリケーション開発において避けて通れない基本的な作業です。これらの操作を行う際に、「今追加したデータのIDを知りたい」「更新する前の元のデータを確認したい」「削除したデータの内容を記録しておきたい」といったニーズがしばしば発生します。

多くの初心者の方は、このようなニーズに対応するために、まずデータを変更するSQL文（INSERT, UPDATE, DELETE）を実行し、その次に別途SELECT文を発行して、変更されたデータを取得するという手順を踏むかもしれません。例えば、新しいユーザーを登録（INSERT）した後、そのユーザーに自動で割り当てられたID（主キーなど）を知るために、さらにSELECT文を使って登録したユーザーを探し出す、といった具合です。

この二段階の手順、特に複数のSQL文を使うアプローチは、一見単純に見えますが、いくつかの問題点を含んでいます。

効率性の低下: データベースとの通信が複数回発生します。特にネットワーク経由でデータベースにアクセスする場合、これは処理時間の増加につながります。
コードの複雑化: アプリケーションのコード側でも、複数のSQL文を実行し、それぞれの結果を処理するロジックを記述する必要があります。これはコードの可読性や保守性を損なう可能性があります。
正確性の問題: 最初の操作（INSERT/UPDATE/DELETE）と、それに続くSELECTの間に、他のユーザーやプロセスが同じデータに対して別の操作を行う可能性があります。これにより、意図しないデータが取得されたり、操作結果と取得結果の間に不整合が生じたりするリスクがあります。特に、自動生成されるIDを取得する場合、同時実行される他のINSERT操作と混同してしまう危険性があります。（古いシステムでは、lastval()のような関数を使って直前のINSERTのIDを取得することもありましたが、同時実行される複数の接続がある環境では安全ではありませんでした。）

PostgreSQLには、これらの問題を華麗に解決するための非常に強力で便利な機能があります。それが、RETURNING句です。

RETURNING句を使うと、INSERT, UPDATE, DELETEといったデータを変更するSQL文の実行と同時に、その操作によって影響を受けたデータの情報を取得することができます。つまり、「データを追加したら、その追加された行のこのカラムの値を見せて」「この条件でデータを更新したら、更新後のその行のこのカラムの値と、更新前のその行のこのカラムの値を見せて」「この条件でデータを削除したら、削除されたその行のこのカラムの値を見せて」といったリクエストを、たった1つのSQL文で実現できるようになります。

これはデータベース操作の効率、正確性、そしてアプリケーションコードの簡潔さを劇的に向上させます。特に、ウェブアプリケーションやAPIサーバーなど、複数のユーザーが同時にデータベースにアクセスするような環境では、RETURNING句は不可欠と言えるほど重要な役割を果たします。

この記事では、PostgreSQLのRETURNING句を初めて学ぶ方を対象に、その基本的な使い方から、なぜ使うべきなのかという理由（メリット）、様々な応用方法、そして使う上での注意点まで、詳しく丁寧にご説明します。約5000語というボリュームで、あなたのRETURNING句への理解を深め、実際の開発で自信を持って使えるようになることを目指します。

さあ、PostgreSQLの強力な機能であるRETURNING句の世界へ踏み出しましょう！

RETURNING句の基本的な構文と使い方

RETURNING句は、INSERT, UPDATE, DELETE文の末尾に付け加えて使用します。基本的な構文は非常にシンプルです。

sql -- INSERT文の場合 INSERT INTO table_name (column1, column2, ...) VALUES (value1, value2, ...) RETURNING column_name1, column_name2, ...;

sql -- UPDATE文の場合 UPDATE table_name SET column1 = value1, column2 = value2, ... WHERE condition RETURNING column_name1, column_name2, ...;

sql -- DELETE文の場合 DELETE FROM table_name WHERE condition RETURNING column_name1, column_name2, ...;

見ての通り、それぞれの文の最後にRETURNINGというキーワードを置き、その後に取得したいカラム名や式をカンマ区切りで指定します。RETURNING *と指定すれば、その操作によって影響を受けた行の全てのカラムを取得することもできます。

では、それぞれの文での具体的な使い方を見ていきましょう。

まず、例として簡単なproductsテーブルを作成します。

sql CREATE TABLE products ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, price NUMERIC(10, 2) NOT NULL, stock INTEGER DEFAULT 0, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP );

このテーブルには、自動採番されるid（SERIAL型）、製品名、価格、在庫数、作成日時があります。

1. INSERT文でのRETURNING句

新しい製品を追加し、その際に自動生成されたidと、データベース側で設定されたcreated_atの値を取得したい場合を考えます。

RETURNING句を使わない場合、通常は以下のようにします。

“`sql
— まずINSERTを実行
INSERT INTO products (name, price, stock)
VALUES (‘Laptop’, 1200.00, 50);

— その後、追加された行を特定してIDや作成日時を取得（この特定が難しい！）
— 例1: 名前と価格が完全に一致する、かつ最近作成されたもの？ -> 同名同価格の別製品と区別できない可能性
— SELECT id, created_at FROM products WHERE name = ‘Laptop’ AND price = 1200.00 ORDER BY created_at DESC LIMIT 1;

— 例2: もし何らかの方法で主キー以外のユニークな情報があれば使えるが、常にそうとは限らない
— 例3: 非推奨だが lastval() を使う方法もあった (同時実行で問題)
“`

この「追加された行を特定して取得する」という部分が、同時実行環境では非常に困難で危険です。

RETURNING句を使えば、これが非常に簡単かつ安全になります。

sql -- INSERTと同時に、生成されたIDと作成日時を取得 INSERT INTO products (name, price, stock) VALUES ('Laptop', 1200.00, 50) RETURNING id, created_at;

この1つのSQL文を実行するだけで、PostgreSQLは製品をテーブルに追加し、追加された行のidとcreated_atの値を結果として返します。アプリケーション側では、この結果セットを受け取るだけで目的を達成できます。

結果の例（データベースシステムからの応答イメージ）：

id | created_at -----+------------------------------- 101 | 2023-10-27 10:00:00.123456+09 (1 row)

このように、追加された製品のIDが101であり、作成日時が特定のタイムスタンプであることがわかります。

2. UPDATE文でのRETURNING句

既存の製品の価格や在庫数を更新し、その際に「更新後の新しい価格と在庫数」や、「更新前の古い価格」を取得したい場合があります。

例えば、IDが101の製品（Laptop）の価格を10%値上げし、在庫を10個減らす場合を考えます。更新後の新しい価格と在庫数を知りたいとします。

sql -- UPDATEと同時に、更新後の価格と在庫数を取得 UPDATE products SET price = price * 1.10, stock = stock - 10 WHERE id = 101 RETURNING name, price, stock; -- 更新後のname, price, stockを取得

このクエリを実行すると、IDが101の製品が更新され、更新後の製品名、価格、在庫数が返されます。

結果の例：

name | price | stock --------+----------+------- Laptop | 1320.000 | 40 (1 row)

価格が1200.00から1320.000に、在庫が50から40になったことが確認できます。（NUMERIC型の精度によっては表示が異なります）

さらに、RETURNING句では、PostgreSQLの特別なエイリアスOLDとNEWを使うことで、更新前のデータと更新後のデータを区別して取得することもできます。（これはトリガー関数でも使われる概念ですが、UPDATE ... RETURNINGでも利用できます。）

例えば、更新前の価格と更新後の価格の両方を取得したい場合：

sql -- UPDATEと同時に、更新前の価格と更新後の価格を取得 UPDATE products SET price = price * 1.10, stock = stock - 10 WHERE id = 101 RETURNING name, OLD.price AS old_price, NEW.price AS new_price; -- OLD.priceで更新前の価格、NEW.priceで更新後の価格

結果の例：

name | old_price | new_price --------+-----------+----------- Laptop | 1200.00 | 1320.000 (1 row)

このように、OLD.プレフィックスを付けてカラム名を指定すると更新前の値が、NEW.プレフィックスを付けると更新後の値が取得できます。これは、データの変更履歴を記録したり、特定のカラムがどのように変更されたかを確認したりする際に非常に便利です。ただし、OLDとNEWはUPDATE文でのみ有効です。INSERT文ではOLDは存在せず、DELETE文ではNEWは存在しません。

3. DELETE文でのRETURNING句

特定の製品を削除し、その際に「削除された製品の情報」を取得したい場合があります。これは、削除されたデータをログとして記録したり、ユーザーに「この製品を削除しました」と確認メッセージを表示したりする際に役立ちます。

例えば、IDが101の製品（Laptop）を削除する場合を考えます。削除された製品のID、名前、価格を取得したいとします。

sql -- DELETEと同時に、削除された行の情報を取得 DELETE FROM products WHERE id = 101 RETURNING id, name, price; -- 削除された行のid, name, priceを取得

このクエリを実行すると、IDが101の製品がテーブルから削除され、削除された製品のID、名前、価格が返されます。

結果の例：

id | name | price -----+--------+--------- 101 | Laptop | 1320.00 (1 row)

削除されたデータの内容を確認することで、意図したデータが正しく削除されたことをアプリケーション側で把握できます。DELETE文の場合、RETURNING *と指定すれば、削除された行の全てのカラムを取得できます。UPDATEとは異なり、DELETEではOLDは暗黙的に削除前の状態を示しますが、通常はプレフィックスなしでカラム名を指定するだけで削除前の（つまり削除された）値が取得されます。NEWは削除後の状態を意味するため、DELETE文では利用できません。

まとめ：基本構文

SQL文	基本構文	`OLD`/`NEW`の利用可否	備考
`INSERT`	`INSERT ... RETURNING column1, column2, ...`	`NEW`のみ（プレフィックスなしと同等）	挿入された行の値を取得
`UPDATE`	`UPDATE ... WHERE ... RETURNING column1, OLD.col2, NEW.col3, ...`	`OLD`, `NEW`	更新前後の値を取得
`DELETE`	`DELETE ... WHERE ... RETURNING column1, column2, ...`	`OLD`のみ（プレフィックスなしと同等）	削除された行の値を取得

このように、RETURNING句はINSERT, UPDATE, DELETEの各文と組み合わせて、操作の影響を受けた行の情報を、同じクエリ内で効率的かつ安全に取得できる強力な機能です。次のセクションでは、RETURNING句を使うことの具体的なメリットについて、さらに深く掘り下げていきます。

なぜRETURNING句を使うのか？メリットの詳細

「基本的な使い方はわかったけど、結局、RETURNINGを使わないで別にSELECTを発行するのと何が違うの？」「わざわざ新しい構文を覚える必要があるの？」と感じている初心者の方もいるかもしれません。

しかし、RETURNING句は単なる構文の短縮以上の価値を持っています。ここからは、RETURNING句を使うことで得られる具体的なメリットを、様々な視点から詳しく解説します。これらのメリットを理解すれば、なぜRETURNING句がPostgreSQLでの開発において標準的に使われるべき機能なのかが明確になるはずです。

1. 圧倒的な効率性（ネットワークとデータベース負荷の軽減）

最も明白なメリットの一つは、データベース操作の効率向上です。

RETURNING句を使わない場合、例えばINSERT操作の結果として生成されたIDを取得するためには、少なくとも以下の2つのステップが必要です。

アプリケーションからデータベースへ INSERT文を送信・実行
アプリケーションからデータベースへ SELECT文を送信・実行

これらのステップの間には、ネットワーク上をSQL文が行き来し、データベースがそれぞれのSQL文を解析・実行し、結果をネットワーク経由でアプリケーションに返す、といった通信と処理が発生します。特に、アプリケーションサーバーとデータベースサーバーが物理的に離れている場合や、ネットワーク遅延が大きい環境では、この「往復」の回数が処理時間に大きく影響します。

一方、RETURNING句を使った場合は、以下の1つのステップで完了します。

アプリケーションからデータベースへ INSERT ... RETURNING ... 文を送信・実行

データベースは1つのSQL文を受け取り、内部でINSERT処理を実行し、その結果として影響を受けた行の情報を取得し、まとめてアプリケーションに返します。ネットワーク通信は1往復で済み、データベース側でも1回のSQL文としてまとめて処理されるため、オーバーヘッドが削減されます。

特に、頻繁に行われるデータベース操作（例: ウェブサイトでのユーザー登録、商品のカート追加、注文処理など）において、この効率性の違いは蓄積され、システム全体のパフォーマンスに大きな影響を与えます。大規模なアプリケーションや多くの同時ユーザーを抱えるシステムでは、無視できない差となります。

2. データの正確性とアトミック性（同時実行環境での安全性）

前述の通り、INSERTやUPDATEの直後に別のSELECTを発行する場合、そのごく短い時間差の間に他のセッションが同じテーブルに対して操作を行う可能性があります。

例えば、自動採番されるID（SERIAL列など）を持つテーブルにINSERTする場合を考えます。

セッションA:
1. INSERT INTO users (name) VALUES ('Alice'); を実行。自動でIDが101と割り振られる。
2. （この間に）セッションBが INSERT INTO users (name) VALUES ('Bob'); を実行。自動でIDが102と割り振られる。
3. セッションAが、何らかの方法（例: SELECT id FROM users WHERE name = 'Alice' ORDER BY created_at DESC LIMIT 1; や非推奨の lastval() など）で直前のINSERTのIDを取得しようとする。

このシナリオにおいて、セッションAがIDを取得する際に、セッションBの操作によってテーブルの状態が変わっている可能性があります。特に lastval() のような関数は、現在のセッションの直前のシーケンス値を取得しますが、これはトランザクションとは独立しているため、複数の文をまとめて実行したり、非同期処理を行ったりする場合には、期待通りの値を取得できないリスクがあります。また、名前などで検索する方法は、同名のデータが複数存在する場合や、登録直後に名前が更新される可能性がある場合など、常に安全とは言えません。

RETURNING句は、INSERT, UPDATE, DELETEの単一の原子的な（アトミックな）操作の一部として、影響を受けた行の情報を取得します。つまり、データの変更と情報の取得が、データベース内部で不可分な一連の処理として行われます。

INSERT ... VALUES (...) RETURNING id; を実行した場合、PostgreSQLは行をテーブルに追加し、その追加された行のIDを直ちに取得して返します。この間に他のセッションが別の行を追加しても、取得されるIDは、まさにそのINSERT文自身が追加した行のIDであることが保証されます。

これは、同時実行されるトランザクションが多いシステムにおいて、データの正確性を確保し、意図しないバグやデータ不整合を防ぐ上で非常に重要です。自動生成される主キーを取得するような場面では、RETURNING句が事実上の標準的な、そして最も安全な手法と言えます。

3. コードの簡潔化と保守性の向上

アプリケーションのコードの視点から見ると、RETURNING句はコードを大幅に簡潔にすることができます。

RETURNINGを使わない場合、アプリケーションコードでは、SQL文を構築・実行し、結果を確認する、という一連の処理を複数回記述する必要があります。

“`python

Python + psycopg2 の例 (RETURNINGを使わない場合)

import psycopg2

conn = psycopg2.connect(…)
cursor = conn.cursor()

try:
# ユーザーを追加
cursor.execute(“INSERT INTO users (name, email) VALUES (%s, %s)”, (‘Alice’, ‘[email protected]’))
conn.commit()

# 追加したユーザーのIDを取得 (例: メールアドレスで検索)
cursor.execute("SELECT id FROM users WHERE email = %s", ('[email protected]',))
user_id = cursor.fetchone()[0] # 結果からIDを取得

print(f"追加されたユーザーのID: {user_id}")

# さらに他の処理...

except Exception as e:
conn.rollback()
print(f”エラー: {e}”)
finally:
cursor.close()
conn.close()
“`

このコードでは、executeメソッドとデータベースへの通信が2回発生しています。また、「追加したユーザーをどうやって特定するか？」というロジックをアプリケーション側で考える必要があり、これはエラーの温床になりがちです。

RETURNING句を使うと、これが1回のデータベース操作で済みます。

“`python

Python + psycopg2 の例 (RETURNINGを使う場合)

import psycopg2

conn = psycopg2.connect(…)
cursor = conn.cursor()

try:
# ユーザーを追加し、同時にIDを取得
cursor.execute(“INSERT INTO users (name, email) VALUES (%s, %s) RETURNING id”, (‘Alice’, ‘[email protected]’))

# 結果セットからIDを取得
result = cursor.fetchone()
user_id = result[0] # RETURNINGで指定したカラムの値を取得

conn.commit() # INSERTはCOMMIT/ROLLBACKが必要

print(f"追加されたユーザーのID: {user_id}")

# さらに他の処理...

except Exception as e:
conn.rollback()
print(f”エラー: {e}”)
finally:
cursor.close()
conn.close()
“`

コードがシンプルになり、意図がより明確になります。「ユーザーを追加して、そのIDを取得する」という操作が、1つのSQL文と、その結果を処理する部分だけで表現されています。これにより、アプリケーションコードの可読性が向上し、デバッグや保守が容易になります。

また、トランザクション管理の観点からもシンプルになります。RETURNING句を使わない場合は、最初のINSERT（やUPDATE/DELETE）とそれに続くSELECTを同じトランザクション内に含める必要がありますが、RETURNINGを使えば操作全体が単一のSQL文として実行されるため、トランザクション境界の管理がより直感的になります。

4. UPDATE/DELETE文での柔軟な情報取得（変更前後の状態確認）

UPDATE文やDELETE文において、影響を受けた行の「変更前の状態」「変更後の状態」を取得できることは、特定のユースケースで非常に役立ちます。

監査ログ: データの変更があった際に、変更前後の値を記録しておきたい場合があります。UPDATE ... RETURNING OLD.*, NEW.* を使えば、更新される行の全てのカラムについて、更新前の値と更新後の値を効率的に取得し、それを別の監査ログテーブルにINSERTするといった処理を実装できます。
処理結果の通知: 例えば、在庫管理システムで商品の在庫数を減らすUPDATEを行った後、「〇〇商品の在庫が△△個から××個になりました」のように、変更前後の在庫数をユーザーに通知したい場合があります。UPDATE ... RETURNING OLD.stock, NEW.stock のようにすれば、必要な情報を簡単に取得できます。
データのバックアップ/復旧補助: DELETEする前に、削除されるデータの内容を完全に取得して別の場所に退避しておきたい場合があります。DELETE ... RETURNING * とすれば、削除対象の行の全カラムデータを取得できます。

これらのシナリオにおいて、RETURNING句を使わない場合は、UPDATE/DELETEの前に別途SELECT文を発行して現在の状態を取得し、UPDATE/DELETEの後に（UPDATEの場合はもう一度SELECTを発行して更新後の状態を取得するか、アプリケーション側で計算して）情報を得る、という複雑な手順が必要になります。RETURNING句は、これらの操作をシンプルかつ確実に実行する手段を提供します。

5. トランザクションとの親和性

データベース操作の正確性を保証するためには、トランザクションが重要です。複数の操作を一つの論理的な単位にまとめ、全て成功するか、全て失敗するかのいずれかになるようにします。

RETURNING句は、INSERT, UPDATE, DELETEというデータ変更操作と、それに続く情報取得を、データベース側の単一の文の実行として行います。もしこの文の実行中にエラーが発生した場合、文全体の効果（データの変更も含めて）はロールバックされます。これにより、データ変更と情報取得の間で不整合が起こるリスクを最小限に抑えることができます。

例えば、INSERT ... RETURNING id 文を実行中にデータベースのエラーが発生した場合、行の挿入は行われず、IDも返されません。もしINSERTとSELECT id WHERE ... を別々の文で行っていた場合、最初のINSERTは成功したが次のSELECTが失敗した、あるいはその逆、という状況も考えられます。RETURNING句を使うことで、操作全体がよりアトミックになり、トランザクション制御の単位が明確になります。

これらのメリットを総合すると、RETURNING句は単なるSQLの糖衣構文ではなく、PostgreSQLを使ったアプリケーション開発において、パフォーマンス、安全性、そして開発効率を高めるための非常に重要な機能であることがわかります。特に、自動採番されるIDを取得する場面や、更新/削除前後のデータを把握したい場面では、積極的に利用を検討すべきです。

次のセクションでは、RETURNING句で取得できる様々なデータ型や、カラム名の代わりに式を指定する方法について掘り下げていきます。

様々なデータ型のRETURNING句での扱い

RETURNING句で取得できる値は、元のテーブルのカラムのデータ型に依存します。PostgreSQLがサポートする多様なデータ型は、そのままRETURNING句で取得した結果のデータ型として扱われます。

アプリケーション側でRETURNING句の結果を受け取る際には、使用しているプログラミング言語やデータベースドライバが、PostgreSQLのデータ型をどのように対応する言語のデータ型にマッピングするかを理解しておくことが重要です。多くのドライバは、PostgreSQLの標準的なデータ型を、それぞれの言語の標準的な型（数値、文字列、真偽値、日付/時刻オブジェクトなど）に自動的に変換してくれます。

ここでは、いくつかの代表的なデータ型について、RETURNING句で取得した場合のイメージと注意点を説明します。

例として、以下のような様々なデータ型を含むテーブルを考えます。

sql CREATE TABLE complex_data ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, age INTEGER, is_active BOOLEAN DEFAULT TRUE, registration_date DATE DEFAULT CURRENT_DATE, last_login_time TIMESTAMP WITH TIME ZONE, balance NUMERIC(18, 2), settings JSONB, tags TEXT[], -- 配列型 unique_code UUID DEFAULT gen_random_uuid() -- UUID型 );

このテーブルにデータをINSERTし、RETURNING * を使って全てのカラムの値を取得してみましょう。

sql INSERT INTO complex_data (name, age, balance, settings, tags, last_login_time) VALUES ( 'Charlie', 30, 1500.75, '{"theme": "dark", "notifications": true}', '{"premium", "beta"}', '2023-10-27 10:30:00+09' ) RETURNING *;

結果のイメージ：

id | name | age | is_active | registration_date | last_login_time | balance | settings | tags | unique_code ----+---------+-----+-----------+-------------------+-----------------------+----------+------------------------------+-------------+-------------------------------------- 1 | Charlie | 30 | t | 2023-10-27 | 2023-10-27 10:30:00+09 | 1500.75 | {"theme": "dark", ...} | {premium,beta} | a1b2c3d4-e5f6-7890-1234-567890abcdef (1 row)

代表的なデータ型の扱い

数値型 (INTEGER, BIGINT, NUMERIC, REAL, DOUBLE PRECISIONなど):
- PostgreSQLの数値型は、プログラミング言語の対応する数値型（int, long, float, double, Decimalなど）にマッピングされます。NUMERIC型は精度が重要なので、多くの言語では専用のDecimal型やBigDecimal型として扱われます。
- 例: id (SERIAL -> INTEGER), age (INTEGER), balance (NUMERIC)
文字列型 (VARCHAR, TEXTなど):
- プログラミング言語の文字列型にマッピングされます。
- 例: name (VARCHAR)
真偽値型 (BOOLEAN):
- 多くの言語ではブーリアン型（true/false）にマッピングされます。PostgreSQLのテキスト表現ではtまたはfと表示されることが多いです。
- 例: is_active (BOOLEAN)
日付/時刻型 (DATE, TIME, TIMESTAMP, TIMESTAMPTZなど):
- プログラミング言語の対応する日付/時刻オブジェクトや構造体にマッピングされます。タイムゾーン情報（WITH TIME ZONE）を持つ型は、タイムゾーン込みで扱われます。
- 例: registration_date (DATE), last_login_time (TIMESTAMPTZ)
JSON/JSONB型:
- これらの型で保存されたデータは、多くの言語ではJSONオブジェクトや連想配列、辞書型などにマッピングされます。ドライバによっては文字列として返されることもありますが、JSON解析ライブラリを使って容易に扱えます。JSONBは効率的な格納形式であり、通常はJSONと同様に扱われます。
- 例: settings (JSONB)
配列型 (ARRAY):
- PostgreSQLの配列型は、プログラミング言語のリストや配列型にマッピングされます。要素の型もPostgreSQLの型に対応します。
- 例: tags (TEXT[]) -> 言語によっては文字列のリストや配列
UUID型:
- 多くの言語でUUID型がサポートされており、それにマッピングされます。UUID型がない場合は文字列として扱われることが多いです。
- 例: unique_code (UUID)
その他の型:
- PostgreSQLはジオメトリ型、ネットワークアドレス型、列挙型など、様々な特殊な型をサポートしています。これらの型がRETURNING句で返される場合、ドライバが対応していればその言語の対応する型にマッピングされますが、対応していない場合は文字列などの汎用的な型として返されることがあります。それぞれのドライバのドキュメントを確認することが重要です。

RETURNING句で複数のカラムを指定した場合、結果は通常、指定したカラムの値を順に並べたタプル、リスト、あるいは連想配列（カラム名をキーとする辞書）のような形式で返されます。どの形式で返されるかは、使用するプログラミング言語やデータベースドライバ、さらにはドライバの設定によります。

例えば、Pythonのpsycopg2では、cursor.fetchone()はタプルを返し、cursor.fetchall()はタプルのリストを返します。カラム名でアクセスしたい場合は、psycopg2.extras.DictCursorなどを使用すると、辞書のようなオブジェクトとして結果を取得できます。

“`python

Python + psycopg2 + DictCursor の例

import psycopg2
import psycopg2.extras # DictCursorを使うためにインポート

conn = psycopg2.connect(…)

DictCursorを使用すると、結果を辞書形式で取得できる

cursor = conn.cursor(cursor_factory=psycopg2.extras.DictCursor)

try:
cursor.execute(“INSERT INTO products (name, price) VALUES (%s, %s) RETURNING id, name, price”, (‘Mouse’, 25.00))

result = cursor.fetchone() # 結果は辞書形式のオブジェクト

product_id = result['id'] # カラム名でアクセス
product_name = result['name']
product_price = result['price']

conn.commit()

print(f"追加された製品: ID={product_id}, 名前={product_name}, 価格={product_price}")

except Exception as e:
conn.rollback()
print(f”エラー: {e}”)
finally:
cursor.close()
conn.close()
“`

このように、使用するドライバやORMのドキュメントを参照し、RETURNING句で取得した値をアプリケーションコードで適切に扱う方法を理解しておくことが重要です。

RETURNING句での式の利用

RETURNING句では、単にテーブルのカラム名を指定するだけでなく、式を指定することも可能です。これにより、データベース側で計算や変換を行った結果を直接取得できます。これは、アプリケーション側で同じ計算を繰り返す手間を省き、効率をさらに向上させるのに役立ちます。

指定できる式は、PostgreSQLがSELECTリストで受け付けるほとんどの式と同じです。これには以下のようなものが含まれます。

算術演算 (+, -, *, /)
文字列操作 (|| (連結), 関数など)
数学関数 (ROUND(), FLOOR(), CEILING(), SQRT(), etc.)
日付/時刻関数 (NOW(), CURRENT_DATE, EXTRACT(), etc.)
条件式 (CASE WHEN ... END)
キャスト (::type)
データベース特有の関数
カラムの組み合わせ

例を見てみましょう。

1. 算術演算

製品の価格を更新し、その際に税込み価格（例えば消費税10%）を計算して取得したい場合：

sql UPDATE products SET price = price * 1.10 -- 価格を10%値上げ WHERE id = 102 RETURNING name, price AS new_price, ROUND(price * 1.10, 2) AS price_with_tax; -- 更新後の価格と税込み価格を取得

この例では、price * 1.10 という式を計算し、それを price_with_tax というエイリアス名で取得しています。ROUND() 関数で小数点以下第2位に丸めています。price AS new_price は、更新後のpriceカラムの値そのものを取得していますが、これも式の一種（カラム名式）とみなせます。

2. 文字列操作や関数

ユーザー名を更新し、その際にユーザー名の長さを取得したい場合や、特定の形式に整形したい場合：

sql UPDATE users SET name = 'Alice Smith' WHERE id = 101 RETURNING id, name, LENGTH(name) AS name_length, UPPER(name) AS name_upper; -- 更新後の名前、長さ、大文字を取得

ここでは、LENGTH() 関数で文字列の長さを取得し、UPPER() 関数で文字列を大文字に変換して取得しています。

3. 日付/時刻関数

レコードが作成された日時を挿入し、その際に特定の日付フォーマットで取得したい場合や、タイムスタンプから年だけを抽出したい場合：

sql INSERT INTO orders (product_id, quantity) VALUES (101, 5) RETURNING id, created_at, TO_CHAR(created_at, 'YYYY-MM-DD HH24:MI:SS') AS formatted_created_at, EXTRACT(YEAR FROM created_at) AS creation_year;

TO_CHAR() 関数でタイムスタンプを指定したフォーマットの文字列に変換し、EXTRACT() 関数でタイムスタンプから年だけを抽出しています。

4. 条件式 (CASE WHEN)

在庫数を更新し、更新後の在庫数に応じて「在庫状態」を判定して取得したい場合：

sql UPDATE products SET stock = stock - 1 WHERE id = 101 RETURNING id, name, stock AS current_stock, CASE WHEN stock > 10 THEN 'Sufficient' WHEN stock BETWEEN 1 AND 10 THEN 'Low' ELSE 'Out of Stock' END AS stock_status;

CASE WHEN 式を使って、更新後のstockの値に基づいたカスタムの文字列を取得しています。

5. OLD/NEWと式の組み合わせ

UPDATE文で、変更前後の値を使って計算を行い、その結果を取得したい場合：

sql UPDATE products SET price = price * 1.10 WHERE id = 101 RETURNING id, OLD.price AS old_price, NEW.price AS new_price, NEW.price - OLD.price AS price_difference; -- 変更前後の価格差を計算

このように、OLD.やNEW.プレフィックスと組み合わせることで、変更がどれくらいの差分で発生したかなどを直接取得できます。

RETURNING句で式を利用することで、データベースの計算能力を活かし、アプリケーションコードのロジックをシンプルに保つことができます。複雑な計算やデータ整形が必要な場合でも、データベース側で一度に処理して結果を受け取ることで、効率的かつ安全なデータ処理を実現できます。

ただし、RETURNING句で実行する式があまりに複雑すぎたり、大量のデータを処理する上で非効率な式だったりすると、文全体のパフォーマンスに影響を与える可能性はあります。通常は、単純な計算や組み込み関数の利用であれば問題ありませんが、複雑な集計や外部関数呼び出しなどを多用する場合は、パフォーマンスへの影響を考慮する必要があります。

次のセクションでは、RETURNING句が特にその真価を発揮する場面の一つである「自動採番されるシーケンス値の取得」について詳しく見ていきます。

RETURNING句とシーケンス（自動採番IDの取得）

PostgreSQLでテーブルの主キーなどに使われる自動採番の列は、通常SERIAL, BIGSERIAL, あるいはIDENTITY型として定義されます。これらの型を使うと、新しい行が挿入されるたびに、データベースは内部で管理しているシーケンスから一意の連番を取得してその列に自動的に割り当てます。

例えば、先ほど作成したproductsテーブルのid列はSERIAL型です。

sql CREATE TABLE products ( id SERIAL PRIMARY KEY, ... );

SERIALは実際にはINTEGER型であり、テーブル作成時に以下の処理を自動で行ってくれます。

新しいシーケンス（例: products_id_seq）を作成する。
id列のデフォルト値を、このシーケンスの次の値を取得する式 (nextval('products_id_seq'::regclass)) に設定する。
id列にNOT NULL制約を設定する。
id列を主キー（またはユニーク制約）として設定する。

新しい行をINSERTする際にid列に値を指定しないか、DEFAULTを指定すると、このデフォルト値の式が評価され、シーケンスから取得された次の値がidに割り当てられます。

sql -- IDを指定しない、またはDEFAULTを指定する INSERT INTO products (name, price) VALUES ('Keyboard', 75.00); -- idは自動生成される INSERT INTO products DEFAULT VALUES; -- idのみ自動生成される (他の列はデフォルト値またはNULL)

この自動生成されたIDを、INSERT操作の直後に知る必要がある場面は非常に多いです。例えば、新しいユーザーを登録したら、そのユーザーのIDをウェブページのURLに含めてリダイレクトしたり、ユーザーIDをセッション情報として保存したりします。

従来のID取得方法の問題点

RETURNING句が広く使われるようになる前や、RETURNING句をサポートしないデータベースシステムでは、以下のような方法で自動生成IDを取得しようとすることがありました。

lastval() 関数: SELECT lastval(); を実行して、現在のセッションで最後にnextval()が呼ばれたシーケンスの値を返す方法。
- 問題点: lastval()はシーケンスの値を取得しますが、その値がどのテーブルのどの行に使われた値なのかを保証しません。特に、複数のテーブルで同じシーケンスを共有していたり、複数のINSERT操作が高速に連続して実行されたりする環境では、意図しないIDを取得してしまう危険性があります。また、トランザクションとは独立しているため、トランザクション境界を跨ぐと挙動が不明確になることがあります。これはPostgreSQLのマニュアルでも非推奨とされています。
currval() 関数: SELECT currval('sequence_name'); を実行して、現在のセッションで指定したシーケンスから最後に取得された値を返す方法。
- 問題点: currval()を使うためには、事前にそのセッションで一度nextval()を呼んでおく必要があります（つまり、INSERTが成功している必要があります）。また、lastval()と同様に、その値がどの行に使われたかを直接保証するものではありません。lastval()よりは安全性が高いとされますが、やはり同時実行環境では注意が必要です。
INSERT後に条件で検索: INSERTしたデータの内容（名前、タイムスタンプなど）を元にSELECT文を発行して、追加された行のIDを取得する方法。
- 問題点: 前述の通り、検索条件が一意に特定の行を識別できるとは限りません。同名同価格の製品を複数登録する可能性があったり、登録直後にデータが変更されたりする可能性があります。また、この方法もINSERTとSELECTの間に時間差があり、同時実行による不整合のリスクがあります。

RETURNING句による安全なID取得

RETURNING句は、これらの問題に対するシンプルかつ決定的な解決策を提供します。INSERT文で新しい行が作成された直後に、その作成された行の自動採番されたIDを取得できることが保証されます。

sql INSERT INTO products (name, price) VALUES ('Monitor', 300.00) RETURNING id;

この1つのSQL文は、以下の処理をアトミックに行います。

シーケンスから次の値を割り当てて、新しい行をproductsテーブルに挿入する。
挿入されたばかりのその行からidの値を読み取る。
そのidの値を結果として返す。

この処理全体がデータベース内部で、他のセッションの影響を受けることなく実行されます。したがって、返されるidは、まさにそのINSERT文によって追加された行のIDであることが100%保証されます。

これは特に、複数のユーザーが同時に新規登録を行うようなウェブアプリケーションでは必須の機能です。各ユーザーの登録処理は独立して行われ、それぞれのINSERT文が自身のRETURNING idによって、自身が追加したユーザーの正確なIDを取得できます。

IDENTITY列との組み合わせ

PostgreSQL 10以降で導入されたIDENTITY列は、SQL標準に準拠した自動採番の方法です。SERIALと同様にシーケンスを利用しますが、列の定義方法が異なります。

sql CREATE TABLE users ( user_id INT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, username VARCHAR(255) NOT NULL );

GENERATED BY DEFAULT AS IDENTITY と定義された列は、INSERT時に値を指定しないかDEFAULTを指定すると、シーケンスから値が生成されます。値を指定することも可能ですが、その場合は明示的にOVERRIDING SYSTEM VALUEを指定する必要があります。

GENERATED ALWAYS AS IDENTITY と定義された列は、INSERT時に値を指定することができません。必ずシステム（シーケンス）が生成した値が使われます。

IDENTITY列の場合も、自動生成された値を取得する最も推奨される方法はRETURNING句です。

sql INSERT INTO users (username) VALUES ('Bob') RETURNING user_id;

IDENTITY列を使う場合も、RETURNING句による値の取得は、最も安全で効率的な方法です。

まとめ：シーケンスとRETURNING

SERIAL, BIGSERIAL, IDENTITY列で自動生成されるIDは、RETURNING句を使って取得するのが最も安全で確実な方法です。
INSERT ... RETURNING id とすることで、挿入された行のIDを他の同時実行処理の影響を受けずに取得できます。
lastval() や currval()、またはデータ内容による検索といった代替手段は、同時実行環境での正確性に問題を抱えているため、特別な理由がない限り避けるべきです。

自動生成IDの取得は、多くのデータベース操作において非常に頻繁に発生するシナリオです。ここでRETURNING句を正しく理解し、適切に利用することは、アプリケーションの信頼性と堅牢性を高める上で非常に重要です。

RETURNING句と他の機能との連携

PostgreSQLにはRETURNING句以外にも、様々な強力な機能があります。これらの機能をRETURNING句と組み合わせることで、より複雑で高度なデータ操作を、効率的かつ安全に行うことができます。ここでは、代表的な機能であるWITH句（CTE）やトリガーとの連携を見てみましょう。

1. RETURNING句とWITH句 (Common Table Expressions – CTE)

WITH句（共通テーブル式、CTE）は、一時的な名前付き結果セットを定義するために使用されます。複雑なクエリを小さな部分に分割したり、同じ結果セットをクエリ内で複数回参照したりするのに役立ちます。

INSERT, UPDATE, DELETE文は、WITH句と組み合わせることができます。そして、WITH句の中で、あるいはWITH句の結果に対して、RETURNING句を使用することが可能です。

例1: WITH句で生成したデータを使ってINSERTし、結果を取得する

ある計算や他のテーブルからの取得に基づいて挿入するデータを準備し、その挿入結果（生成されたIDなど）を取得したい場合。

sql WITH new_product_data AS ( -- ここで一時的なデータセットを作成 SELECT 'Wireless Mouse' AS name, 50.00 AS price, 100 AS stock ) INSERT INTO products (name, price, stock) SELECT name, price, stock FROM new_product_data -- WITH句で定義したデータを使ってINSERT RETURNING id, name; -- 挿入された行のIDと名前を取得

この例では、new_product_dataというCTEで挿入する製品情報を定義し、そのCTEからデータをINSERTしています。そして、そのINSERT文に対してRETURNING句を使用し、挿入された製品のIDと名前を取得しています。これは、複雑なデータを生成してから一括で挿入し、その結果を処理する際に便利です。

例2: UPDATE/DELETEの結果を他の処理で利用し、さらに結果を取得する

UPDATEやDELETEによって変更された行の情報を取得し、その情報を別の処理（例えば別のテーブルへのINSERTやログ記録）に利用しつつ、最終的に変更された行の情報そのものも取得したい場合。

例えば、在庫を減らした製品のうち、在庫がゼロになったものを別のテーブルに記録しつつ、在庫がゼロになった製品の情報を取得したい場合。

“`sql
WITH updated_stock AS (
— 在庫を減らすUPDATEを実行し、更新後のID, name, stockを取得
UPDATE products
SET stock = stock – 10
WHERE id IN (101, 102, 103) — 例として複数の製品の在庫を減らす
RETURNING id, name, stock
)
— updated_stock CTE は、在庫が減らされた製品のリストとその更新後の在庫数を含む
— ここで、在庫がゼロになった製品を別のテーブル (例えば out_of_stock_log) に挿入するなどの処理が可能
— INSERT INTO out_of_stock_log (product_id, log_time) SELECT id, NOW() FROM updated_stock WHERE stock <= 0;

— 最終的に、在庫が減らされた製品のリスト（WITH句の結果）を返す
SELECT id, name, stock FROM updated_stock;
“`

この例では、updated_stockというCTEの中でUPDATE ... RETURNING id, name, stock を実行しています。このCTEは、UPDATEによって影響を受けた全ての行（在庫が減らされた製品）のid, name, stockを一時的な結果セットとして保持します。その後のSELECT * FROM updated_stock; は、このCTEの内容、つまり在庫が減らされた製品のリストを返します。

もし、さらにこの操作全体の「最終的な結果」として、例えば在庫がゼロになった製品だけの情報を取得したい場合は、以下のようにします。

sql WITH updated_stock AS ( UPDATE products SET stock = stock - 10 WHERE id IN (101, 102, 103) RETURNING id, name, stock ) -- WITH句の結果から、stockが0以下の行を選択して返す SELECT id, name FROM updated_stock WHERE stock <= 0;

このように、WITH句とRETURNING句を組み合わせることで、複雑なデータ操作を段階的に記述し、各段階や最終的な結果として必要な情報を効率的に取得することができます。

2. RETURNING句とトリガー (Triggers)

トリガーは、データベースの特定イベント（INSERT, UPDATE, DELETEなど）が発生した際に自動的に実行される関数です。トリガー関数内では、影響を受ける行の古い値（OLD）や新しい値（NEW）にアクセスできます。

RETURNING句は、トリガー関数とは独立して動作しますが、トリガーが実行される前後の状態を把握する上で間接的に関連することがあります。

例えば、UPDATE操作でRETURNING OLD.*, NEW.* を使うと、トリガーが実行される前の値（OLD）と、トリガーが実行された後の値（NEW）を取得できます。（正確には、トリガーの種類によって異なります。BEFOREトリガーの場合はトリガー関数内でNEWを変更できますが、AFTERトリガーではできません。RETURNING句で取得されるNEWの値は、BEFOREトリガーによる変更が反映された後の値になります。）

例: 更新前後の価格差をトリガーとRETURNINGで確認する

“`sql
— トリガー関数（例: 価格変更をログに記録）
CREATE OR REPLACE FUNCTION log_price_change()
RETURNS TRIGGER AS $$
BEGIN
— NEW.price と OLD.price にアクセスしてログ記録などを行う
— RAISE NOTICE ‘Price changed from % to % for product %’, OLD.price, NEW.price, NEW.id;
RETURN NEW; — UPDATEの場合はNEWを返すのが一般的
END;
$$ LANGUAGE plpgsql;

— UPDATE AFTER トリガーを設定
CREATE TRIGGER price_update_trigger
AFTER UPDATE OF price ON products
FOR EACH ROW
EXECUTE FUNCTION log_price_change();

— RETURNING OLD.price, NEW.price を使ってUPDATEを実行
UPDATE products
SET price = price * 1.05
WHERE id = 101
RETURNING id, OLD.price AS old_price, NEW.price AS new_price;
“`

このシナリオでは、UPDATE文が実行されると、まず価格が更新され、その後にAFTER UPDATEトリガーであるlog_price_changeが実行されます。トリガー関数内ではOLD.priceとNEW.priceを使って価格変更前後の値にアクセスできます。そして、UPDATE文自身のRETURNING OLD.price, NEW.price によって、アプリケーション側でも同じ更新前後の値を取得できます。

RETURNING句は主にアプリケーションがデータベース操作の結果を効率的に受け取るためのものですが、トリガーと組み合わせて使用することで、データベース内部での処理（トリガー）とアプリケーションでの結果取得（RETURNING）を連携させることができます。例えば、トリガーでデータのバリデーションや追加の処理を行った後、そのトリガーの結果をRETURNING句で取得した値から判断する、といったことが考えられます。（ただし、トリガー関数内でエラーを発生させると文全体がロールバックされるため、RETURNINGで結果を受け取っても意味がなくなります。）

このように、RETURNING句はPostgreSQLの他の強力な機能と組み合わせることで、より複雑で柔軟なデータ操作パターンを実現できます。WITH句との組み合わせは、特に多段階のデータ処理や、中間結果を利用するシナリオで非常に強力です。

パフォーマンスに関する考慮事項

RETURNING句を使うことによるパフォーマンスへの影響は、通常、別のSELECT文を発行する場合と比較して、はるかに優れています。これは、前述の通り、データベースとの通信ラウンドトリップが削減され、データベース内部で操作と結果取得がまとめて行われるためです。

しかし、RETURNING句を使う際に考慮すべきパフォーマンスに関するポイントがいくつかあります。

取得するカラムの量: RETURNING * を使って全カラムを取得する場合、操作対象のテーブルが多くのカラムを持っていたり、そのカラムに非常に大きなデータ（例: TEXT, BYTEA, JSONBで大量のデータ）が含まれていたりすると、返される結果セットのサイズが大きくなります。この結果セットをネットワーク経由でアプリケーションに転送したり、アプリケーション側でメモリにロードしたりするのに時間がかかったり、リソースを消費したりする可能性があります。必要なカラムだけを具体的に指定することが、無駄なデータ転送を防ぎ、パフォーマンス向上につながります。
“`sql
— 良い例：必要なIDだけを取得
INSERT INTO large_table (…) VALUES (…) RETURNING id;

— 悪い例になりうる例：不要なlarge_textカラムも取得
— INSERT INTO large_table (id, large_text, …) VALUES (…, ‘…’, …) RETURNING *;
“`
操作対象の行数: INSERT, UPDATE, DELETE 文が対象とする行が多い場合、RETURNING句もそれらの全行に対して実行され、結果として複数行が返されます。大量の行が操作される場合、返される結果セットも巨大になる可能性があります。アプリケーション側でこのような巨大な結果セットを効率的に処理できるかを確認する必要があります。数百行、数千行程度であれば通常問題になりませんが、数十万、数百万といった単位になる場合は、結果の取得と処理にかかる時間やメモリ使用量に注意が必要です。
- 例えば、一括データ更新で大量の行をUPDATE ... RETURNING する場合、アプリケーションは返される全行の結果を待つ必要があります。
- もし大量の行を操作する際にRETURNINGが必要なら、バッチ処理で分割して行う、あるいはアプリケーション側での結果処理方法を最適化するなどの検討が必要になることがあります。
式の計算コスト: RETURNING句で複雑な式（特に、ユーザー定義関数や集計関数を呼ぶ式など）を使用する場合、その式の計算コストが全体の実行時間に影響を与える可能性があります。単純な算術演算や組み込み関数であれば通常問題ありませんが、高負荷な計算をRETURNING句内で多数実行すると、パフォーマンスが低下する可能性があります。必要な計算はRETURNING句で行うか、アプリケーション側で行うか、あるいは事前に計算済みの値を格納しておくかなど、トレードオフを考慮する必要があります。
インデックス: UPDATEやDELETEのWHERE句の条件には、適切なインデックスが貼られていることが重要です。RETURNING句そのもののパフォーマンスというよりは、操作対象の行を効率的に特定するために、基となるINSERT, UPDATE, DELETE文のパフォーマンスが重要になります。RETURNING句自体は、操作によって影響を受けた行から値を読み取るだけなので、通常はインデックスを必要としません。

一般的に、RETURNING句は、関連するINSERT, UPDATE, DELETE操作が効率的に実行されている限り、大きなパフォーマンスボトルネックになることは少ないです。むしろ、別のSELECTを発行することによって生じるオーバーヘッド（ネットワーク、コンテキストスイッチ、キャッシュ効率の低下など）を回避できるため、多くの場合はRETURNING句を使う方が高性能になります。

結論として、RETURNING句を使うことによるパフォーマンス上のメリットは大きいですが、取得するデータ量（カラム数 × 行数）と、RETURNING句内で実行する式の計算コストには注意を払い、必要に応じて最適化を検討しましょう。特に大規模なデータ操作を行う場合は、これらの点を意識することが重要です。

アプリケーション層での利用例

RETURNING句は、SQLレベルでの機能ですが、その真価を発揮するのはアプリケーションコードと連携して使用される場合です。様々なプログラミング言語やフレームワークからPostgreSQLを操作する際に、RETURNING句の結果をどのように受け取り、活用するかを見てみましょう。

ほとんどの主要なプログラミング言語向けのPostgreSQLドライバ（ライブラリ）は、RETURNING句の結果セットを、通常のSELECT文の結果と同様に扱うことができます。結果は1行または複数行になる場合があり、それぞれの行はカラムの値を保持しています。

ここでは、代表的な言語での利用例をいくつか紹介します。

Python + psycopg2

PythonでPostgreSQLを扱う際の標準的なライブラリの一つにpsycopg2があります。psycopg2はRETURNING句の結果をタプル（または辞書、DictCursorを使用した場合）のリストとして返します。

“`python
import psycopg2
import psycopg2.extras

def add_product(name, price, stock):
conn = None
product_id = None
try:
conn = psycopg2.connect(“dbname=mydatabase user=myuser password=mypass host=localhost port=5432”)
# DictCursorを使用すると結果をカラム名で取得できる
cursor = conn.cursor(cursor_factory=psycopg2.extras.DictCursor)

    # INSERT ... RETURNING
    cursor.execute(
        "INSERT INTO products (name, price, stock) VALUES (%s, %s, %s) RETURNING id, name",
        (name, price, stock)
    )

    # RETURNING句は結果セットを返すので、fetchone() または fetchall() で取得
    result = cursor.fetchone()

    if result:
        product_id = result['id']
        product_name = result['name']
        print(f"製品 '{product_name}' を追加しました。ID: {product_id}")
    else:
        print("製品の追加に失敗したか、結果が返されませんでした。")


    conn.commit()

except psycopg2.Error as e:
    if conn:
        conn.rollback()
    print(f"データベースエラー: {e}")
except Exception as e:
    print(f"その他のエラー: {e}")
finally:
    if cursor:
        cursor.close()
    if conn:
        conn.close()

関数呼び出し

add_product(“Tablet”, 350.00, 30)
“`

executeメソッドでRETURNING句を含むSQL文を実行した後、fetchone()（1行だけ返されることがわかっている場合、例えば主キーによるINSERTや単一行UPDATE/DELETE）またはfetchall()（複数行返される可能性がある場合）を使って結果を取得します。DictCursorを使うと、結果の行をカラム名をキーとした辞書のように扱えるため便利です。

Node.js + node-postgres

Node.jsでPostgreSQLを扱う際の一般的なライブラリはnode-postgres (pg) です。これもRETURNING句の結果を、通常のクエリ結果と同様に、行オブジェクトの配列として返します。

“`javascript
const { Pool } = require(‘pg’);

const pool = new Pool({
user: ‘myuser’,
host: ‘localhost’,
database: ‘mydatabase’,
password: ‘mypass’,
port: 5432,
});

async function addProduct(name, price, stock) {
const client = await pool.connect();
try {
// INSERT … RETURNING
const res = await client.query(
‘INSERT INTO products (name, price, stock) VALUES ($1, $2, $3) RETURNING id, name’,
[name, price, stock]
);

    // RETURNING句の結果は res.rows に含まれる
    if (res.rows.length > 0) {
        const addedProduct = res.rows[0]; // 挿入された行は通常1つ
        console.log(`製品 '${addedProduct.name}' を追加しました。ID: ${addedProduct.id}`);
        return addedProduct.id;
    } else {
        console.log("製品の追加に失敗したか、結果が返されませんでした。");
        return null;
    }

} catch (err) {
    console.error('データベースエラー:', err);
    throw err; // エラーを再スロー
} finally {
    client.release(); // クライアントをプールに戻す
}

}

// 関数呼び出し (async/await)
addProduct(“Smartphone”, 600.00, 25)
.catch(console.error);
“`

client.queryメソッドはPromiseを返し、解決されると結果オブジェクトが得られます。RETURNING句の結果は、この結果オブジェクトのrowsプロパティに配列として格納されています。各要素はカラム名をプロパティとするオブジェクトです。

Java + JDBC

JavaでPostgreSQLを扱うにはJDBCドライバを使用します。JDBCでは、INSERT, UPDATE, DELETE文の実行は通常Statement.executeUpdate()またはPreparedStatement.executeUpdate()で行いますが、RETURNING句を使用する場合はStatement.execute()またはPreparedStatement.execute()を使用し、その後Statement.getResultSet()またはPreparedStatement.getResultSet()で結果セットを取得します。これは、RETURNING句が結果セットを返すため、更新件数だけを返すexecuteUpdateでは対応できないためです。

“`java
import java.sql.*;

public class ProductDao {

private static final String DB_URL = "jdbc:postgresql://localhost:5432/mydatabase";
private static final String USER = "myuser";
private static final String PASS = "mypass";

public int addProduct(String name, double price, int stock) {
    int generatedId = -1;
    Connection conn = null;
    PreparedStatement pstmt = null;
    ResultSet rs = null;

    try {
        conn = DriverManager.getConnection(DB_URL, USER, PASS);

        // INSERT ... RETURNING
        String sql = "INSERT INTO products (name, price, stock) VALUES (?, ?, ?) RETURNING id";
        pstmt = conn.prepareStatement(sql);
        pstmt.setString(1, name);
        pstmt.setDouble(2, price);
        pstmt.setInt(3, stock);

        // executeUpdateではなくexecuteを使う
        boolean isResultSet = pstmt.execute();

        // RETURNING句の結果セットを取得
        if (isResultSet) {
            rs = pstmt.getResultSet();
            if (rs.next()) {
                generatedId = rs.getInt("id"); // カラム名またはインデックスで取得
                System.out.println("製品を追加しました。ID: " + generatedId);
            }
        } else {
             // RETURNING句がない場合や、RETURNING句があっても結果セットが空の場合
             // execute()がfalseを返す（更新件数はpstmt.getUpdateCount()で取得できる）
             System.out.println("製品の追加は行われましたが、IDは返されませんでした。");
        }

        conn.commit(); // AUTOCOMMITがfalseの場合

    } catch (SQLException e) {
        e.printStackTrace();
        if (conn != null) {
            try {
                conn.rollback();
            } catch (SQLException ex) {
                ex.printStackTrace();
            }
        }
    } finally {
        try {
            if (rs != null) rs.close();
            if (pstmt != null) pstmt.close();
            if (conn != null) conn.close();
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
    return generatedId;
}

public static void main(String[] args) {
    ProductDao dao = new ProductDao();
    dao.addProduct("Keyboard", 75.00, 50);
}

}
“`

Java/JDBCでは、execute()メソッドを使って、RETURNING句を含むSQL文を実行します。execute()は、結果がResultSet（SELECT文の結果のようなもの）の場合はtrueを、更新件数だけの場合はfalseを返します。RETURNING句を使う場合はtrueが返されると期待し、getResultSet()で結果セットを取得し、ResultSetからデータを取り出します。これはSELECT文の結果を扱うのと同様の方法です。

ORM (Object-Relational Mapper) での扱い

多くのORMライブラリ（例: PythonのSQLAlchemy, JavaのHibernate, RubyのActive Recordなど）は、内部的にRETURNING句を活用して、オブジェクトの保存や更新後に自動生成されたIDなどを効率的に取得しています。

例えば、SQLAlchemyでは、新しいオブジェクトをセッションに追加してコミットすると、そのオブジェクトの主キー属性にデータベースで割り当てられたIDが自動的にセットされます。これはSQLAlchemyが内部でINSERT ... RETURNING idのようなクエリを実行しているためです。開発者が直接RETURNING句を含むSQLを書く必要がない場合でも、ORMの裏側でRETURNING句が使われていることはよくあります。

“`python

SQLAlchemy の例

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.declarative import declarative_base

データベース接続設定

DATABASE_URL = “postgresql://myuser:mypass@localhost:5432/mydatabase”
engine = create_engine(DATABASE_URL)

モデル定義

Base = declarative_base()

class Product(Base):
tablename = ‘products’
id = Column(Integer, primary_key=True) # SERIAL型に対応
name = Column(String)
price = Column(Integer) # 例としてInteger
stock = Column(Integer)

テーブル作成（すでにある場合は不要）

Base.metadata.create_all(engine)

セッション作成

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

製品追加

def create_product(name, price, stock):
db = SessionLocal()
try:
new_product = Product(name=name, price=price, stock=stock)
db.add(new_product)
db.commit() # コミット時にINSERTが実行され、IDがnew_productオブジェクトにセットされる
db.refresh(new_product) # 必要に応じて最新の状態をリロード

    print(f"製品 '{new_product.name}' を追加しました。ID: {new_product.id}")
    return new_product

except Exception as e:
    db.rollback()
    print(f"エラー: {e}")
    return None
finally:
    db.close()

関数呼び出し

create_product(“Monitor”, 300, 30)
“`

このSQLAlchemyの例のように、ORMを使う場合は、通常、ORMのメソッド（add(), commit()など）を呼び出すだけで、内部で効率的なRETURNING句を使った処理が行われます。これは、ORMの大きなメリットの一つです。しかし、ORMでは表現できない複雑なRETURNING句の使い方（例えば、RETURNING句で複雑な式を使う場合や、特定のOLD/NEWの組み合わせを取得する場合など）をしたい場合は、直接SQLを書く必要があるかもしれません。

結論として、アプリケーション層でRETURNING句を使う際は、使用しているプログラミング言語のデータベースドライバやORMのドキュメントを参照し、RETURNING句の結果セットをどのように取得・処理するのかを確認することが重要です。ほとんどの場合、SELECT文の結果を扱うのと同様の方法で対応できます。

RETURNING句の注意点とよくある間違い

RETURNING句は非常に便利ですが、使う上でいくつか注意すべき点や、初心者が陥りやすい間違いがあります。これらを理解しておくことで、予期せぬ問題を防ぐことができます。

SELECT文では使えない: RETURNING句は、データを変更するINSERT, UPDATE, DELETE文でのみ使用可能です。単にデータを検索するSELECT文にRETURNING句を付けても構文エラーになります。SELECT文で結果を取得するには、通常通りSELECT column1, column2, ... FROM table_name WHERE ... を使用します。
結果は複数行になる可能性がある: RETURNING句は、操作によって影響を受けた全ての行に対して実行されます。
- INSERT ... VALUES (...) のように単一の行を挿入する場合、RETURNINGは通常1行の結果を返します。
- INSERT ... SELECT ... のように複数行を挿入する場合、RETURNINGは挿入された全ての行の結果を返します。
- UPDATE ... WHERE ... や DELETE ... WHERE ... で条件に一致する行が複数ある場合、RETURNINGは一致した全ての行の結果を返します。
アプリケーションコードでRETURNING句の結果を取得する際は、常に結果が複数行になる可能性があることを考慮し、ループなどで適切に処理できるようにしておくべきです。（ただし、主キーを指定したUPDATE/DELETEのように、1行しか対象にならないことが保証されている場合は別です。）fetchone()のような単一行取得メソッドを使う場合は、結果が複数行あった場合に最初の1行しか取得できない、あるいはエラーになる可能性があることに注意が必要です。
トランザクション管理の重要性: RETURNING句を含むINSERT, UPDATE, DELETE文は、適切にトランザクション管理を行う必要があります。文の実行が成功したらコミットし、失敗したらロールバックすることが基本です。RETURNING句で結果を取得できたとしても、トランザクションをコミットしない限り、そのデータ変更は永続化されません。
OLDとNEWの使い分け: UPDATE文でOLD.とNEW.プレフィックスを使用する際は、それぞれの意味（更新前と更新後）を正しく理解しておく必要があります。INSERT文ではOLDは使えず、DELETE文ではNEWは使えません。プレフィックスなしでカラム名を指定した場合、INSERTではNEWの値（挿入された値）、DELETEではOLDの値（削除された値）、UPDATEではNEWの値（更新された値）が取得されます。
エラーハンドリング: INSERT, UPDATE, DELETE文の実行中に、制約違反（NOT NULL違反、ユニーク制約違反、外部キー制約違反など）やその他のエラーが発生する可能性があります。この場合、文全体が失敗し、RETURNING句の結果は返されません。アプリケーションコードでは、これらのエラーを適切にキャッチし、ロールバックなどの処理を行う必要があります。RETURNING句でエラー情報は返ってこないので、エラー自体は通常のSQLエラーハンドリングメカニズム（例外など）で処理します。
パフォーマンス影響の過小評価/過大評価: RETURNING句は効率的ですが、前述の通り、取得するデータ量や式によってはパフォーマンスに影響を与える可能性があります。「常にRETURNING *を使う」「RETURNING句の中で重たい処理を行う」といった使い方は避けるべきです。逆に、「RETURNING句を使うと遅くなる」という誤解も持たないようにしましょう。多くの場合、別のSELECTよりも高速です。
ドライバ/ORMの対応: 使用しているデータベースドライバやORMがRETURNING句をどのようにサポートしているかを確認することが重要です。古いバージョンのドライバや、RETURNING句を明示的にサポートしていない汎用的なデータベースライブラリの場合、期待通りに結果を取得できない可能性があります。

これらの注意点を頭に入れておくことで、RETURNING句をより安全かつ効果的に利用することができます。特に複数行の結果を処理するロジックと、堅牢なエラーハンドリングは、実アプリケーション開発において不可欠です。

応用例と発展的な使い方

RETURNING句の基本を押さえた上で、より実用的で応用的な使い方を見てみましょう。

1. キューシステムの実装

UPDATE ... RETURNING は、データベースを簡易的なキューシステムとして利用する際に非常に強力です。例えば、「処理待ち」の状態にあるタスクを取得し、同時にそのタスクの状態を「処理中」に変更する、というアトミックな操作を1つのクエリで行えます。

“`sql
— tasks テーブル (id, status, payload, processed_at)
— status: ‘pending’, ‘processing’, ‘completed’, ‘failed’

— 処理待ちのタスクを1件取得し、状態をprocessingに変更
UPDATE tasks
SET status = ‘processing’, processed_at = NOW()
WHERE id = (
SELECT id
FROM tasks
WHERE status = ‘pending’
ORDER BY created_at ASC — 古いタスクから処理
FOR UPDATE SKIP LOCKED — 他のセッションがロックした行はスキップ
LIMIT 1
)
RETURNING id, payload; — 処理を開始するタスクのIDと内容を取得
“`

このクエリは、以下の処理をアトミックに行います。

SELECT ... FOR UPDATE SKIP LOCKED LIMIT 1 で、status = 'pending' のタスクの中から最も古いものを1件選び、他のセッションが同じ行を選ばないようにロックをかけます（SKIP LOCKEDで他のセッションがロック中の行は無視します）。
選ばれたタスクのstatusを'processing'に、processed_atを現在時刻に更新します。
更新されたタスクのidとpayload（タスクの内容）を返します。

この1つのクエリを実行するだけで、「処理待ちのタスクを取得し、それを他の処理者が取得できないようにロックしつつ、処理中の状態にする」という一連の操作が完了します。アプリケーション側では、返されたタスク情報を使って実際の処理を行い、処理が完了したらstatusを'completed'などに再度UPDATEします。これは、分散環境で複数のワーカープロセスがキューから安全にタスクを取得する際に非常に有効なパターンです。

2. 変更内容を即座にUIに反映

ウェブアプリケーションなどで、ユーザーがデータを更新した際に、データベースからの最新の情報を取得してUIに反映したい場合があります。UPDATE ... RETURNING * や UPDATE ... RETURNING NEW.column1, ... を使うことで、更新後のデータ全体や、必要なカラムだけを効率的に取得し、クライアントに返すことができます。

sql -- 製品情報を更新し、更新後の名前と価格を返すAPIエンドポイントの処理イメージ -- (実際のSQL実行部分のみ抜粋) UPDATE products SET name = 'Updated Laptop', price = 1350.00 WHERE id = 101 RETURNING id, name, price;

このクエリの結果（ID 101の製品の新しい名前と価格）をJSONなどでクライアントに返すことで、ページ全体をリロードすることなく、UIの該当部分だけを最新の情報に更新できます。

3. 複雑なデータ生成と挿入

外部システムから受け取ったデータを整形したり、複数の情報源を組み合わせたりして、新しいデータを生成し、テーブルに挿入する際にRETURNING句を活用できます。

例えば、注文データを挿入する際に、注文の合計金額を計算して保存し、挿入された注文のIDと計算された合計金額を同時に取得したい場合。

sql -- order_items テーブルから、新しく作成する注文に関連する品目の合計金額を計算 WITH order_total AS ( SELECT SUM(price * quantity) AS total_amount FROM order_items WHERE order_id IS NULL AND session_id = '...' -- 例: まだ注文に紐づいていない、特定のセッションの品目 ) -- orders テーブルに新しい注文を挿入し、合計金額を設定 INSERT INTO orders (user_id, order_date, total_amount) SELECT 123, NOW(), total_amount FROM order_total -- WITH句で計算したtotal_amountを挿入 RETURNING order_id, total_amount; -- 挿入された注文のIDと合計金額を取得

この例では、まずorder_itemsテーブルから関連する品目の合計金額を計算し、その結果をorder_total CTEとしています。次に、そのorder_total CTEから合計金額を取得してordersテーブルに挿入しています。最後に、そのINSERT文に対してRETURNING句を使用し、新しく生成されたorder_idと、挿入したtotal_amountを返しています。

このような応用例からもわかるように、RETURNING句は単にIDを取得するだけでなく、UPDATEやDELETEといったデータ変更操作をトリガーとして、様々な処理の結果や関連情報を効率的に取得するための汎用的なメカニズムとして活用できます。特に、データベースの機能を最大限に活用したい場合や、クライアントとサーバー間のやり取りを最適化したい場合に、その威力を発揮します。

まとめ：RETURNING句を使いこなそう！

PostgreSQLのRETURNING句は、INSERT, UPDATE, DELETEといったデータを変更するSQL文の実行と同時に、その操作によって影響を受けた行の情報を効率的かつ安全に取得するための非常に強力な機能です。

この記事では、以下の内容を詳しく解説しました。

RETURNING句の基本構文: INSERT, UPDATE, DELETE文の最後にRETURNING column1, column2, ... と付け加えることで使用できます。RETURNING * で全カラムを取得できます。UPDATEではOLD.とNEW.プレフィックスを使って更新前後の値を区別できます。
RETURNING句を使う理由とメリット:
- 効率性: データベースとの通信ラウンドトリップを減らし、処理を高速化します。
- 正確性とアトミック性: 操作と結果取得を単一のクエリで行うため、同時実行環境でのデータ不整合を防ぎます。特に自動生成IDの取得において最も安全な方法です。
- コードの簡潔化: アプリケーションコードから複数のSQL文とその処理ロジックを減らし、読みやすく保守しやすいコードになります。
- 柔軟な情報取得: UPDATEやDELETEで変更前後のデータを確認できます。
様々なデータ型の扱い: 数値、文字列、日付、JSON、配列など、PostgreSQLがサポートする多様なデータ型をRETURNING句で取得できます。アプリケーション側での適切な型マッピングが重要です。
式を用いた情報取得: カラム名だけでなく、算術演算、関数呼び出し、条件式など、様々な式の結果をRETURNING句で取得できます。これにより、データベース側で計算や整形を行った結果を直接利用できます。
シーケンスと自動採番ID: SERIALやIDENTITY列で自動生成されるIDを取得する際に、RETURNING句が最も推奨される安全な方法である理由を説明しました。lastval()などの代替方法の問題点も解説しました。
他の機能との連携: WITH句と組み合わせることで複雑なデータ操作を行い、その結果を取得できます。トリガーと組み合わせて変更前後の状態を確認することも可能です。
パフォーマンスに関する考慮事項: RETURNING句自体は効率的ですが、取得するデータ量や式によってはパフォーマンスに影響する可能性があるため、必要なカラムのみを取得するなどの工夫が有効です。
アプリケーション層での利用: 主要なプログラミング言語のデータベースドライバ（Python/psycopg2, Node.js/node-postgres, Java/JDBCなど）やORMでのRETURNING句の結果の取得方法を紹介しました。
注意点とよくある間違い: SELECT文では使えないこと、複数行の結果が返される可能性があること、トランザクション管理、エラーハンドリングなどの注意点を説明しました。
応用例: キューシステムの実装や、UI更新のためのデータ取得など、実用的な応用例を紹介しました。

PostgreSQLを扱う上で、RETURNING句は非常に強力で応用範囲の広い機能です。特に、自動生成される主キーの取得、データの変更前後の状態確認、そして単一のクエリで操作と結果取得をアトミックに行いたいというニーズがある場面では、RETURNING句はほぼ必須と言えるでしょう。

初心者の方は、まずはINSERT ... RETURNING id といった、自動生成IDの取得から使い始めてみるのがおすすめです。慣れてきたら、UPDATE/DELETE ... RETURNING * や、式を使った取得など、徐々に応用範囲を広げてみてください。RETURNING句を積極的に活用することで、より効率的で安全、そして保守しやすいデータベース操作を実現できるようになります。

このガイドが、皆さんがPostgreSQLのRETURNING句を理解し、自信を持って日々の開発に活用するための一助となれば幸いです。Happy Coding!

【初心者向け】PostgreSQL RETURNING句の入門ガイド

はじめに：なぜPostgreSQLのRETURNING句を学ぶべきなのか？

RETURNING句の基本的な構文と使い方

1. INSERT文でのRETURNING句

2. UPDATE文でのRETURNING句

3. DELETE文でのRETURNING句

まとめ：基本構文

なぜRETURNING句を使うのか？ メリットの詳細

1. 圧倒的な効率性（ネットワークとデータベース負荷の軽減）

2. データの正確性とアトミック性（同時実行環境での安全性）

3. コードの簡潔化と保守性の向上

Python + psycopg2 の例 (RETURNINGを使わない場合)

Python + psycopg2 の例 (RETURNINGを使う場合)

4. UPDATE/DELETE文での柔軟な情報取得（変更前後の状態確認）

5. トランザクションとの親和性

様々なデータ型のRETURNING句での扱い

代表的なデータ型の扱い

Python + psycopg2 + DictCursor の例

DictCursorを使用すると、結果を辞書形式で取得できる

RETURNING句での式の利用

1. 算術演算

2. 文字列操作や関数

3. 日付/時刻関数

4. 条件式 (CASE WHEN)

5. OLD/NEWと式の組み合わせ

RETURNING句とシーケンス（自動採番IDの取得）

従来のID取得方法の問題点

RETURNING句による安全なID取得

IDENTITY列との組み合わせ

まとめ：シーケンスとRETURNING

RETURNING句と他の機能との連携

1. RETURNING句とWITH句 (Common Table Expressions – CTE)

2. RETURNING句とトリガー (Triggers)

パフォーマンスに関する考慮事項

アプリケーション層での利用例

Python + psycopg2

関数呼び出し

Node.js + node-postgres

Java + JDBC

ORM (Object-Relational Mapper) での扱い

SQLAlchemy の例

データベース接続設定

モデル定義

テーブル作成（すでにある場合は不要）

Base.metadata.create_all(engine)

セッション作成

製品追加

関数呼び出し

RETURNING句の注意点とよくある間違い

応用例と発展的な使い方

1. キューシステムの実装

2. 変更内容を即座にUIに反映

3. 複雑なデータ生成と挿入

まとめ：RETURNING句を使いこなそう！

コメントする 返信をキャンセル

なぜRETURNING句を使うのか？メリットの詳細

コメントする返信をキャンセル