Filtered deletion
Remove records matching a predicate, such as users with a particular name or identifier.
Drizzle ORM · Module
db.delete
Drizzle’s delete builder removes rows from a table, optionally restricting them with conditions. PostgreSQL can return full deleted rows or selected fields with .returning().
How it works
Call db.delete(table) to construct a DELETE query, then add .where() to restrict which rows are removed. PostgreSQL supports .returning() to retrieve deleted rows or a selected projection; the builder also supports dialect-specific clauses such as .limit() and .orderBy() where documented.
Syntax
db.delete(table).where(condition).returning()Parameters
| Name | Type | Description |
|---|---|---|
table | Table | The Drizzle table object whose rows are targeted by the DELETE statement. |
where | SQL<boolean> | A Drizzle SQL condition restricting which rows are deleted. |
Returns
A dialect-specific delete query builder; execution resolves to deleted-row data when a supported returning clause is used, otherwise it resolves according to the database driver’s delete result.
Key points
- Use
db.delete(table)when the intent is to remove every row from the target table. - Chain
.where()with Drizzle predicates such aseq()to select rows for deletion. - On supported dialects,
.limit(number)caps how many matching rows the delete can affect. - On supported dialects,
.orderBy()specifies sorting fields for the delete operation. - PostgreSQL delete queries can use
.returning()to obtain deleted rows.
Common mistakes
- Calling
db.delete(table)without a condition removes every row in that table. .returning()is documented for PostgreSQL; do not assume every database dialect supports it.
Example: Delete filtered rows and return selected fields
import { eq } from 'drizzle-orm';
import { drizzle } from 'drizzle-orm/node-postgres';
import { users } from './schema';
const db = drizzle(process.env.DATABASE_URL!);
const deletedUsers = await db
.delete(users)
.where(eq(users.name, 'Dan'))
.returning({ deletedId: users.id });
console.log(deletedUsers);Deletes matching users and returns only their identifiers.
When to use it
Full-table cleanup
Purge an entire table when clearing its contents is intentional.
Delete with returned data
Capture deleted PostgreSQL rows or selected identifiers for auditing or follow-up work.
Controlled batch deletion
Bound or order deletions where the selected SQL dialect supports those clauses.
Interview questions
QHow do you delete only selected rows with Drizzle?
db.delete(users) creates a delete query targeting the users table. Adding .where(eq(users.id, 1)) limits the deletion to rows whose identifier is 1.
Follow-up: How can the deleted data be captured in PostgreSQL? Add .returning() for full rows or pass an object such as { deletedId: users.id } for a partial result.
QHow can a delete query return deleted records?
Use .returning() after the filter to retrieve deleted rows in PostgreSQL. A projection passed to .returning() controls which deleted columns are returned.
Follow-up: What shape does a partial projection produce? For { deletedId: users.id }, the result contains objects with a deletedId property for the deleted rows.
QWhich additional clauses can be chained onto a delete query?
The delete builder can add .limit() to constrain the number of rows and .orderBy() to control deletion order in dialects whose documentation supports those clauses. Both are chained after the optional filter.
Follow-up: How would you limit deletion to two matching users? Use .where(eq(users.name, 'Dan')).limit(2).
Related
where()returning()limit()orderBy()eq()with()