Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Soft Deletes

View as Markdownllms.txt

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.

Add t.softDeletes() to the table’s migration. That creates a nullable deleted_at timestamp column:

database/migrations/2026_11_14_093000_create_posts_table.ts
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:

database/migrations/2026_11_15_080000_add_soft_deletes_to_posts_table.ts
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())
},
})
const post = await Post.findOrFail(1)
await post.delete() // sets deleted_at; the row stays
console.log(post.trashed()) // → true
console.log(await Post.find(1)) // → undefined: hidden from normal queries
await post.restore() // clears deleted_at
console.log(await Post.find(1)) // → the post again
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 deleted
const 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().

const post = await Post.withTrashed().findOrFail(1)
await post.forceDelete() // DELETE FROM posts WHERE id = ?
console.log(await Post.withTrashed().find(1)) // → undefined

On a table without deleted_at, delete() already removes the row for good.

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"

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.

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.

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:

app/jobs/prune-posts.ts
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.

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 posts
GET /api/posts?filter[trashed]=only deleted posts only
POST /api/posts/7/restore bring post 7 back

What 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.

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()
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.

  • 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.