Soft Deletes
A soft delete marks a row as deleted instead of removing it. The row stays in the table with a date in its deleted_at column, every normal query leaves it out, and you can bring it back with restore(). A force delete removes the row for good.
Use soft deletes for anything a user might delete by mistake (posts, customers, invoices), or anything you must keep for a while for legal or audit reasons.
Turning it on
Section titled “Turning it on”Add t.softDeletes() to the table’s migration. That creates a nullable deleted_at timestamp column:
import { migration } from '@strutvane/framework/schema'
export default migration({ up(schema) { schema.create('posts', (t) => { t.id() t.string('title', 200) t.timestamps() t.softDeletes() }) }, down(schema) { schema.dropIfExists('posts') },})Run node strut migrate. The model needs no change.
For an existing table, add it in a new migration:
import { migration } from '@strutvane/framework/schema'
export default migration({ up(schema) { schema.table('posts', (t) => t.softDeletes()) }, down(schema) { schema.table('posts', (t) => t.dropSoftDeletes()) },})Deleting, checking and restoring
Section titled “Deleting, checking and restoring”const post = await Post.findOrFail(1)
await post.delete() // sets deleted_at; the row staysconsole.log(post.trashed()) // → trueconsole.log(await Post.find(1)) // → undefined: hidden from normal queries
await post.restore() // clears deleted_atconsole.log(await Post.find(1)) // → the post againSeeing deleted rows
Section titled “Seeing deleted rows”| Query | Returns |
|---|---|
Post.query()… |
only rows that aren’t deleted (the default) |
Post.withTrashed()… |
deleted and not-deleted rows |
Post.onlyTrashed()… |
only deleted rows (a “bin” view) |
await Post.withTrashed().find(1) // finds it even when deletedconst bin = await Post.onlyTrashed().latest('deleted_at').get()console.log(bin.map((post) => post.title))// → [ 'Ephemeral' ]They work on Post.query() too: Post.query().withTrashed().where('title', 'Ephemeral').first().
Deleting for good
Section titled “Deleting for good”const post = await Post.withTrashed().findOrFail(1)await post.forceDelete() // DELETE FROM posts WHERE id = ?console.log(await Post.withTrashed().find(1)) // → undefinedOn a table without deleted_at, delete() already removes the row for good.
Relationships respect soft deletes
Section titled “Relationships respect soft deletes”Deleted rows are left out everywhere a query reaches them: lists, find(), counts, eager-loaded relationships and whereHas().
const ada = await User.query().where('name', 'Ada').firstOrFail()for (const post of await ada.posts().get()) await post.delete()
const users = await User.query().withCount('posts').orderBy('name').get()console.log(users.map((user) => [user.name, user.posts_count]))// → [ [ 'Ada', 0 ], [ 'Grace', 2 ], [ 'Linus', 2 ] ]
await User.query().whereHas('posts').count() // Ada no longer counts as "has posts"Soft-deleted rows keep their slug
Section titled “Soft-deleted rows keep their slug”A deleted post still owns its slug (the unique index covers it), so restoring it can never clash with a newer post. A new post with the same title gets the next number, like ephemeral-2. See Slugs.
In the generated screens
Section titled “In the generated screens”The admin list hides deleted rows by default and offers a “Trashed” filter (without / with / only), a Restore action and, when allowed, Delete permanently. See Resources.
Emptying the bin
Section titled “Emptying the bin”Pruning means removing, on a schedule, rows that were soft-deleted long ago. Until the built-in version arrives, write it as a job that runs every night:
import { transaction } from '@strutvane/framework'import { Post } from '../models/post.ts'
/** Removes posts that have been in the bin for more than 30 days. */export async function prunePosts(): Promise<number> { const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) const old = await Post.onlyTrashed().where('deleted_at', '<', cutoff).limit(500).get() await transaction(async () => { for (const post of old) await post.forceDelete() }) return old.length}What you’ll see: the function returns how many posts it removed, at most 500 per run, so one run never locks the table for long.
In the generated API
Section titled “In the generated API”Every soft-deleting resource in the generated API offers the same three choices to clients:
GET /api/posts live posts only (the default)GET /api/posts?filter[trashed]=with live and deleted postsGET /api/posts?filter[trashed]=only deleted posts onlyPOST /api/posts/7/restore bring post 7 backWhat you’ll see for the restore: 200 with the post, its deleted_at back to null. Like every action, it’s checked against the post’s policy first, so only users allowed to restore can.
Common mistakes
Section titled “Common mistakes”Restoring a row on a table without soft deletes
Section titled “Restoring a row on a table without soft deletes”OrmUsageError: "tags" has no deleted_at column, so there is nothing to restore. Add t.softDeletes() in a migration to enable it.Fix: add t.softDeletes() in a new migration and run node strut migrate. Rows deleted before that are already gone.
“No row … may be soft-deleted” when you know the row exists
Section titled ““No row … may be soft-deleted” when you know the row exists”ModelNotFoundError: No row in "posts" with key 1. It may not exist, may be soft-deleted, or may belong to another tenant.Why: normal queries skip deleted rows, so findOrFail(1) can’t see it.
Fix: to work with a deleted row (to restore it, for example), start with withTrashed():
const post = await Post.withTrashed().findOrFail(1)await post.restore()Deleting a model that was never saved
Section titled “Deleting a model that was never saved”OrmUsageError: Can't delete() a "posts" row that was never saved. Call save() first.Fix: there’s nothing to delete yet: drop the object, or save() it first.
A unique value is “taken” by a deleted row
Section titled “A unique value is “taken” by a deleted row”Why: deleted rows still count for unique indexes, so restoring them stays safe. A new row can’t reuse a deleted row’s unique value (an email, for example).
Fix: restore the old row instead of creating a new one, or force-delete it first if it should really go.
Next steps
Section titled “Next steps”- Scopes: soft deletes are one of the conditions added automatically.
- Slugs: why deleted rows keep their slug.
- Transactions: delete several related rows all or nothing.