Soft delete

better-drizzle/soft-delete extends the built-in methods with typed soft-delete controls, default visibility filtering, and restore helpers.

Install

npm install better-drizzle

pnpm add better-drizzle

yarn add better-drizzle

bun add better-drizzle

Usage

import { better } from 'better-drizzle';
import { softDelete } from 'better-drizzle/soft-delete';

const client = better(db, {
	plugins: [
		softDelete({
			column: 'deletedAt',
			deletedByColumn: 'deletedById',
			defaults: {
				mode: 'soft',
				visibility: 'without',
			},
		}),
	],
});

Options

Every option is optional. Column names are the property keys in your Drizzle table definition, not the database column names.

What is filtered

The reads, updates, and deletes in the first rows accept deleted: 'without' | 'with' | 'only'. It controls the root rows only; nested reads always hide deleted rows. A write whose where is empty stays a no-op: the plugin never turns deleteMany({}) into "soft delete everything".

await client.users.findMany(); // visible rows only
await client.users.findMany({ deleted: 'with' }); // include deleted
await client.users.findMany({ deleted: 'only' }); // only deleted
await client.users.count({ deleted: 'with' });

Protected columns

Ordinary writes ignore caller-provided deletedAt and deletedById values, or the configured column and deletedByColumn. This applies to create, createMany, update, updateMany, updateEach, upsert, and upsertMany. The plugin removes those fields from updateEach resolvers and from every upsertMany update shape: 'all', a column list, an object, or a callback result. Expanding 'all' also preserves the conflict target.

Upserts can update other fields on a deleted row, but keep its deletion timestamp and author. Use delete() to mark a row as deleted and restore() to clear those fields. For trusted imports that need to set them directly, use $withoutPlugins().

Deleting and restoring

// Soft delete (default)
await client.users.delete({ where: { id: 1 } });

// Record who deleted it (when deletedByColumn exists)
await client.users.delete({ where: { id: 1 }, deletedBy: 'admin_42' });

// Soft delete many rows; already deleted rows keep their timestamp
await client.users.deleteMany({ where: { active: false } });

// Force a real, physical delete
await client.users.delete({ where: { id: 1 }, mode: 'hard' });

// Purge rows that were soft deleted
await client.users.deleteMany({ where: { id: { in: ids } }, mode: 'hard', deleted: 'only' });

// Restore
await client.users.restore({ where: { id: 1 } });
await client.users.restoreById(1);

A soft delete() runs an update of the same where limited to live rows, then returns the updated row (or null), so it still has .throw(). A soft deleteMany() runs an updateMany and returns { count, data? }: PostgreSQL and SQLite include the marked rows (or scalar select fields), while MySQL returns only the count. Empty results omit data. Deleting an already deleted row finds nothing and keeps the original timestamp.

Behavior details

• The timestamp is an ISO 8601 string (new Date().toISOString()) when the column's Drizzle data type is string, such as a SQLite text column. Otherwise it is a Date.
• deletedBy is written only when the call passes it and the table has deletedByColumn.
• restore() and restoreById() exist only on tables with column. They set column (and deletedByColumn, when present) to null through the normal update pipeline with deleted: 'with'. Cache invalidation, timestamps, rules, and client beforeUpdate / afterUpdate hooks run. Both helpers accept select, include, and meta.
• restoreById(id) matches the table's single primary key column, regardless of its name. It throws INVALID_ARGS for tables with composite keys or no primary key; use restore({ where }) for those tables.
• A restore keeps model scopes, so a tenant-scoped client only restores that tenant's rows. A soft delete uses an inner $withoutPlugins({ keepScopes: true }).update(...), which keeps scopes and client update hooks but skips other plugins; its update hooks run before the delete hooks.
• $withoutPlugins() (without keepScopes) drops the soft-delete filter with every other scope, so it reads deleted rows at every level and deletes physically.
• mode: 'hard' falls back to the built-in physical delete. It matches deleted and live rows alike unless the call passes deleted.

Where it fits best

• audit-sensitive systems
• admin tools where deleted rows must remain inspectable
• apps where "delete" should default to reversible