Menu

RETURNING в PostgreSQL для INSERT, UPDATE и DELETE

RETURNING заставляет INSERT, UPDATE, DELETE и MERGE возвращать изменённые строки: сгенерированные id, новые значения, удалённые строки и то, какое действие выполнил MERGE.

На этой странице есть исполняемые редакторы: меняйте, запускайте и сразу видите результат.

RETURNING заставляет оператор, изменяющий данные, возвращать строки, как SELECT. Добавьте его в конец INSERT, UPDATE, DELETE или (с PostgreSQL 17) MERGE, а после него перечислите нужные столбцы или выражения: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.

Обе новые строки возвращаются с id, которые сгенерировал PostgreSQL, и с plan, заполненным значением по умолчанию, без второго запроса.

id вставленной строки

RETURNING id это стандартный способ получить сгенерированный ключ. Он показывает строку такой, какой она сохранена, поэтому работает для столбцов identity, serial, значений UUID по умолчанию и значений, выставленных триггером BEFORE. Многострочный VALUES или INSERT ... SELECT возвращает по одной строке на каждую вставленную.

Драйверы читают его как результат любого запроса: cursor.fetchone() в Python с psycopg, result.rows в Node.js с pg. RETURNING * удобен, пока вы экспериментируете; в коде приложения перечисляйте столбцы, чтобы результат не менялся при изменении таблицы.

Что изменил UPDATE

В UPDATE конструкция RETURNING показывает строки после изменения, и только те, что подошли под WHERE:

Возвращаются две строки: Book за 16.5 и Lamp за 33. Pen не затронута, поэтому её нет в результате.

В PostgreSQL 17 RETURNING видит только новые значения. В PostgreSQL 18 добавлены old и new (RETURNING old.price, new.price). В 17 соедините таблицу с заблокированной копией самой себя:

Каждая строка возвращается с ценой до и после: 10 и 15, 20 и 25.

Строки, которые удалил DELETE

DELETE ... RETURNING отдаёт удалённые строки: для журнала, для отмены или для очереди задач, где обработчик удаляет задачу и получает её данные. Внутри запроса WITH возвращённые строки передаются следующему оператору, и так строки переносятся между таблицами одним оператором:

Задачи 1 и 3 уходят из tasks и появляются в done_tasks. Это один оператор, поэтому ни одна другая сессия не увидит их сразу в обеих таблицах или ни в одной.

Какое действие выполнил MERGE

С PostgreSQL 17 MERGE принимает RETURNING, а функция merge_action() возвращает INSERT, UPDATE или DELETE для каждой строки:

A-100 обновлена до 7, а C-300 вставлена со значением 4. Для вставки или обновления по ключу при одновременной записи лучше подходит upsert с ON CONFLICT, который тоже поддерживает RETURNING.

Что можно писать в RETURNING

Всё, что допустимо в списке SELECT: столбцы, *, выражения, вызовы функций и псевдонимы (RETURNING price * qty AS total), кроме агрегатных функций. Чтобы посчитать или просуммировать возвращённые строки, оберните оператор в запрос WITH и агрегируйте во внешнем SELECT.

Строки, пропущенные из-за ON CONFLICT DO NOTHING или триггера BEFORE, вернувшего NULL, не возвращаются.

Часто задаваемые вопросы

Как получить id только что вставленной строки в PostgreSQL?

Добавьте RETURNING id к INSERT. Он вернёт сгенерированное значение для каждой вставленной строки за тот же запрос к серверу. Это надёжнее, чем SELECT max(id), и работает для столбцов identity, serial и значений по умолчанию вроде gen_random_uuid().

RETURNING быстрее отдельного SELECT?

Обычно да. Он экономит второй оператор и второй запрос к серверу и возвращает ровно те строки, которые затронул оператор, без окна, в котором другая сессия могла бы их изменить.

Поддерживает ли MySQL RETURNING?

В MySQL нет RETURNING; вместо него после вставки читают LAST_INSERT_ID(). SQLite поддерживает RETURNING с версии 3.35.

Иллюстрация языков программирования Coddy

Учитесь программировать с Coddy

Начать