reference
Insert Returning in SQL
Use insert returning when the query intent matches its syntax, row-grain behavior, and PostgreSQL edge cases. This reference gives a minimal example, realistic example, output, mistakes, and next lessons.
Syntax signature
Insert returning solves a specific SQL task. Use it only when its row behavior matches the output contract.
Syntax signature: statement RETURNING columns
BEGIN; UPDATE records SET reviewed = TRUE WHERE record_id = 1 RETURNING record_id; ROLLBACK;What it does and when to use it
Use insert returning when the query task needs this construct's specific row behavior, not because a keyword looks familiar.
Choose it only after naming the input grain, output grain, and whether filtering, grouping, ordering, or mutation semantics happen before or after the construct.
Plan about 10 minutes to read the syntax, compare the examples, and follow the related lesson link before practicing in the app.
Minimal example
The minimal example shows the smallest useful shape before dataset-specific details are added.
BEGIN; UPDATE records SET reviewed = TRUE WHERE record_id = 1 RETURNING record_id; ROLLBACK;Realistic example and output
This example is small enough to audit by eye and mirrors the style used by the SQL Trail checker.
BEGIN; UPDATE tickets SET status = 'reviewed' WHERE ticket_id = 101 RETURNING ticket_id, status; ROLLBACK;| evidence | meaning |
|---|---|
| grain | one row per requested entity |
| edge case | nulls, ties, or duplicates stay explicit |
Behavior notes
Null behavior: decide whether insert returning keeps, removes, groups, compares, or ignores NULL values before trusting the visible output.
Type behavior: check whether insert returning preserves the expected data type or needs an explicit cast in PostgreSQL.
Ordering behavior: add deterministic ORDER BY or tie-breaker columns whenever insert returning can otherwise produce unstable presentation.
Cardinality behavior: confirm whether insert returning preserves one row per input, multiplies rows, collapses rows, or returns one row per group.
PostgreSQL-specific notes are linked to authoritative PostgreSQL documentation when syntax or semantics are dialect-specific.
Common errors and related resources
Learners often use insert returning correctly on the visible rows but miss null policy, tie handling, or the difference between filtering before and after aggregation.
When a PostgreSQL behavior is dialect-specific, SQL Trail links to the official documentation instead of inventing portability claims.