Return updated data
An API updates a record and needs the new identifier or fields without issuing a second SELECT.
Drizzle ORM · Module
.returning
.returning() lets PostgreSQL update statements return affected rows or a selected projection immediately. It supports named result fields and, with update joins, can return columns from joined tables.
How it works
.returning() adds a PostgreSQL RETURNING clause to an update and yields the requested fields from every row that was changed. Pass a projection object to control the returned shape; the documented result is an array, even when the projection contains one column.
Syntax
db.update(table).set(values).where(condition).returning(fields?)Parameters
| Name | Type | Description |
|---|---|---|
fields | projection object | An optional object mapping result keys to table columns to return. |
Returns
An array of objects containing the selected returned fields; the documented single-ID example is typed as { updatedId: number | null }[].
Key points
- Use
.returning()when an update should immediately yield the affected PostgreSQL rows. - A projection object lets you assign application-facing names to returned columns.
- The documented inferred result is an array of objects, with the selected identifier represented as a nullable number.
- PostgreSQL update queries can return values from tables joined through
.from().
Common mistakes
- This documented pattern is PostgreSQL-specific; do not assume every Drizzle dialect supports
.returning()identically. - With PostgreSQL update joins, returned fields may include columns from tables supplied through
.from().
Example: Return updated rows
const updatedUsers = await db
.update(users)
.set({ name: "Mr. Dan" })
.where(eq(users.name, "Dan"))
.returning({
updatedId: users.id,
updatedName: users.name,
});Updates matching PostgreSQL rows and returns the selected columns from each affected row.
When to use it
Return joined-table fields
A PostgreSQL update uses .from() and needs values from both the target and joined tables.
Interview questions
QWhat does .returning() do after an update?
.returning() appends a PostgreSQL RETURNING clause to an update. It returns an array of objects containing the fields selected in its projection.
Follow-up: How do you return only an identifier? Pass a projection such as { updatedId: users.id }, which produces objects containing that selected field.
QHow can you control the returned shape?
Provide an object mapping output names to table columns, for example { updatedId: users.id }. This gives the result a focused, typed shape instead of returning every column.
Follow-up: Can the projection contain columns from another table? In PostgreSQL, yes, when that table is included with .from().
QCan an update return fields from a joined table?
PostgreSQL allows an update to use .from() for a joined table and then return columns from both the updated table and the joined table. The documented example returns users.id and cities.name.
Follow-up: What SQL concept does this correspond to? It corresponds to an UPDATE ... FROM ... RETURNING ... statement.
Related
updatesetwherefromeq