database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-08-28 18:48:04 +03:00
Code Activity

Add OLD/NEW support to RETURNING in DML queries.

Browse Source 
This allows the RETURNING list of INSERT/UPDATE/DELETE/MERGE queries
to explicitly return old and new values by using the special aliases
"old" and "new", which are automatically added to the query (if not
already defined) while parsing its RETURNING list, allowing things
like:

  RETURNING old.colname, new.colname, ...

  RETURNING old.*, new.*

Additionally, a new syntax is supported, allowing the names "old" and
"new" to be changed to user-supplied alias names, e.g.:

  RETURNING WITH (OLD AS o, NEW AS n) o.colname, n.colname, ...

This is useful when the names "old" and "new" are already defined,
such as inside trigger functions, allowing backwards compatibility to
be maintained -- the interpretation of any existing queries that
happen to already refer to relations called "old" or "new", or use
those as aliases for other relations, is not changed.

For an INSERT, old values will generally be NULL, and for a DELETE,
new values will generally be NULL, but that may change for an INSERT
with an ON CONFLICT ... DO UPDATE clause, or if a query rewrite rule
changes the command type. Therefore, we put no restrictions on the use
of old and new in any DML queries.

Dean Rasheed, reviewed by Jian He and Jeff Davis.

Discussion: https://postgr.es/m/CAEZATCWx0J0-v=Qjc6gXzR=KtsdvAE7Ow=D=mu50AgOe+pvisQ@mail.gmail.com
This commit is contained in:
Dean Rasheed
2025-01-16 14:57:35 +00:00
parent 7407b2d48c
commit 80feb727c8
61 changed files with 2910 additions and 390 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
doc/src/sgml/ref/delete.sgml
View File

@@ -25,7 +25,8 @@ PostgreSQL documentation
DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
[ USING <replaceable class="parameter">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> | WHERE CURRENT OF <replaceable class="parameter">cursor_name</replaceable> ]
[ RETURNING { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
[ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
{ * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
</synopsis>
</refsynopsisdiv>
@@ -160,6 +161,26 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ *
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_alias</replaceable></term>
<listitem>
<para>
An optional substitute name for <literal>OLD</literal> or
<literal>NEW</literal> rows in the <literal>RETURNING</literal> list.
</para>
<para>
By default, old values from the target table can be returned by writing
<literal>OLD.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>OLD.*</literal>, and new values can be returned by writing
<literal>NEW.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>NEW.*</literal>. When an alias is provided, these names are
hidden and the old or new rows must be referred to using the alias.
For example <literal>RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_expression</replaceable></term>
<listitem>
@@ -170,6 +191,23 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ *
or table(s) listed in <literal>USING</literal>.
Write <literal>*</literal> to return all columns.
</para>
<para>
A column name or <literal>*</literal> may be qualified using
<literal>OLD</literal> or <literal>NEW</literal>, or the corresponding
<replaceable class="parameter">output_alias</replaceable> for
<literal>OLD</literal> or <literal>NEW</literal>, to cause old or new
values to be returned. An unqualified column name, or
<literal>*</literal>, or a column name or <literal>*</literal> qualified
using the target table name or alias will return old values.
</para>
<para>
For a simple <command>DELETE</command>, all new values will be
<literal>NULL</literal>. However, if an <literal>ON DELETE</literal>
rule causes an <command>INSERT</command> or <command>UPDATE</command>
to be executed instead, the new values may be non-<literal>NULL</literal>.
</para>
</listitem>
</varlistentry>

54
doc/src/sgml/ref/insert.sgml
View File

@@ -26,7 +26,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
[ OVERRIDING { SYSTEM | USER } VALUE ]
{ DEFAULT VALUES | VALUES ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) [, ...] | <replaceable class="parameter">query</replaceable> }
[ ON CONFLICT [ <replaceable class="parameter">conflict_target</replaceable> ] <replaceable class="parameter">conflict_action</replaceable> ]
[ RETURNING { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
[ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
{ * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
<phrase>where <replaceable class="parameter">conflict_target</replaceable> can be one of:</phrase>
@@ -293,6 +294,26 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_alias</replaceable></term>
<listitem>
<para>
An optional substitute name for <literal>OLD</literal> or
<literal>NEW</literal> rows in the <literal>RETURNING</literal> list.
</para>
<para>
By default, old values from the target table can be returned by writing
<literal>OLD.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>OLD.*</literal>, and new values can be returned by writing
<literal>NEW.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>NEW.*</literal>. When an alias is provided, these names are
hidden and the old or new rows must be referred to using the alias.
For example <literal>RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_expression</replaceable></term>
<listitem>
@@ -305,6 +326,23 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
<literal>*</literal> to return all columns of the inserted or updated
row(s).
</para>
<para>
A column name or <literal>*</literal> may be qualified using
<literal>OLD</literal> or <literal>NEW</literal>, or the corresponding
<replaceable class="parameter">output_alias</replaceable> for
<literal>OLD</literal> or <literal>NEW</literal>, to cause old or new
values to be returned. An unqualified column name, or
<literal>*</literal>, or a column name or <literal>*</literal>
qualified using the target table name or alias will return new values.
</para>
<para>
For a simple <command>INSERT</command>, all old values will be
<literal>NULL</literal>. However, for an <command>INSERT</command>
with an <literal>ON CONFLICT DO UPDATE</literal> clause, the old
values may be non-<literal>NULL</literal>.
</para>
</listitem>
</varlistentry>
@@ -711,6 +749,20 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
INSERT INTO distributors (did, dname)
VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;
</programlisting>
</para>
<para>
Insert or update new distributors as above, returning information
about any existing values that were updated, together with the new data
inserted. Note that the returned values for <literal>old_did</literal>
and <literal>old_dname</literal> will be <literal>NULL</literal> for
non-conflicting rows:
<programlisting>
INSERT INTO distributors (did, dname)
VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname
RETURNING old.did AS old_did, old.dname AS old_dname,
new.did AS new_did, new.dname AS new_dname;
</programlisting>
</para>
<para>

35
doc/src/sgml/ref/merge.sgml
View File

@@ -25,7 +25,8 @@ PostgreSQL documentation
MERGE INTO [ ONLY ] <replaceable class="parameter">target_table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">target_alias</replaceable> ]
USING <replaceable class="parameter">data_source</replaceable> ON <replaceable class="parameter">join_condition</replaceable>
<replaceable class="parameter">when_clause</replaceable> [...]
[ RETURNING { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
[ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
{ * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
<phrase>where <replaceable class="parameter">data_source</replaceable> is:</phrase>
@@ -499,6 +500,25 @@ DELETE
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_alias</replaceable></term>
<listitem>
<para>
An optional substitute name for <literal>OLD</literal> or
<literal>NEW</literal> rows in the <literal>RETURNING</literal> list.
</para>
<para>
By default, old values from the target table can be returned by writing
<literal>OLD.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>OLD.*</literal>, and new values can be returned by writing
<literal>NEW.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>NEW.*</literal>. When an alias is provided, these names are
hidden and the old or new rows must be referred to using the alias.
For example <literal>RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_expression</replaceable></term>
<listitem>
@@ -517,6 +537,17 @@ DELETE
qualifying the <literal>*</literal> with the name or alias of the source
or target table.
</para>
<para>
A column name or <literal>*</literal> may also be qualified using
<literal>OLD</literal> or <literal>NEW</literal>, or the corresponding
<replaceable class="parameter">output_alias</replaceable> for
<literal>OLD</literal> or <literal>NEW</literal>, to cause old or new
values from the target table to be returned. An unqualified column
name from the target table, or a column name or <literal>*</literal>
qualified using the target table name or alias will return new values
for <literal>INSERT</literal> and <literal>UPDATE</literal> actions, and
old values for <literal>DELETE</literal> actions.
</para>
</listitem>
</varlistentry>
@@ -722,7 +753,7 @@ WHEN MATCHED AND w.stock + s.stock_delta > 0 THEN
UPDATE SET stock = w.stock + s.stock_delta
WHEN MATCHED THEN
DELETE
RETURNING merge_action(), w.*;
RETURNING merge_action(), w.winename, old.stock AS old_stock, new.stock AS new_stock;
</programlisting>
The <literal>wine_stock_changes</literal> table might be, for example, a

38
doc/src/sgml/ref/update.sgml
View File

@@ -29,7 +29,8 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
} [, ...]
[ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> | WHERE CURRENT OF <replaceable class="parameter">cursor_name</replaceable> ]
[ RETURNING { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
[ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
{ * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
</synopsis>
</refsynopsisdiv>
@@ -211,6 +212,26 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_alias</replaceable></term>
<listitem>
<para>
An optional substitute name for <literal>OLD</literal> or
<literal>NEW</literal> rows in the <literal>RETURNING</literal> list.
</para>
<para>
By default, old values from the target table can be returned by writing
<literal>OLD.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>OLD.*</literal>, and new values can be returned by writing
<literal>NEW.<replaceable class="parameter">column_name</replaceable></literal>
or <literal>NEW.*</literal>. When an alias is provided, these names are
hidden and the old or new rows must be referred to using the alias.
For example <literal>RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">output_expression</replaceable></term>
<listitem>
@@ -221,6 +242,16 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
or table(s) listed in <literal>FROM</literal>.
Write <literal>*</literal> to return all columns.
</para>
<para>
A column name or <literal>*</literal> may be qualified using
<literal>OLD</literal> or <literal>NEW</literal>, or the corresponding
<replaceable class="parameter">output_alias</replaceable> for
<literal>OLD</literal> or <literal>NEW</literal>, to cause old or new
values to be returned. An unqualified column name, or
<literal>*</literal>, or a column name or <literal>*</literal> qualified
using the target table name or alias will return new values.
</para>
</listitem>
</varlistentry>
@@ -348,12 +379,13 @@ UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
</para>
<para>
Perform the same operation and return the updated entries:
Perform the same operation and return the updated entries, and the old
precipitation value:
<programlisting>
UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
WHERE city = 'San Francisco' AND date = '2003-07-03'
RETURNING temp_lo, temp_hi, prcp;
RETURNING temp_lo, temp_hi, prcp, old.prcp AS old_prcp;
</programlisting>
</para>