Soft Deletes and Restore

When delete is soft vs hard, how restore works, and safe usage patterns.

Soft Deletes and Restore

Use this page when records should be recoverable instead of permanently removed.

When delete() is soft

delete() behaves as a soft delete when the model has a deleted_at soft-delete field in its schema.

Valid schema patterns:

deleted_at: column("softDeletes")

For PostgreSQL-focused apps, prefer the explicit timezone-aware form:

deleted_at: column("softDeletes", undefined, { useTz: true })

or:

softDeletes: mixin("SoftDeletes")

Do not define both at once.

What soft delete does

Soft delete updates deleted_at instead of permanently removing the record.

Typical service call:

const user = await User.find(1);
if (user) {
  await user.delete();
}

How restore() works

restore() clears deleted_at and makes the record visible again to normal reads.

const user = await User.find(1);
if (user) {
  await user.restore();
}

Hard delete after soft delete

Use forceDelete() only when the record should be permanently removed:

const model = new User() as User & { forceDelete?: (id: number | string) => Promise<void> };
await model.forceDelete?.(1);

After forceDelete(), do not assume restore() can recover the record.

Querying deleted records

const model = new User() as User & {
  withTrashed?: () => Promise<unknown[]>;
  onlyTrashed?: () => Promise<unknown[]>;
};

const allRows = await model.withTrashed?.();
const deletedRows = await model.onlyTrashed?.();

Recommended controller and service split

• controllers expose restore routes when recovery is part of the API
• services own restore, onlyTrashed, withTrashed, and forceDelete
• models define the schema requirement

Safe usage notes

• use soft delete for recoverable business entities
• use forceDelete only in admin or cleanup paths
• do not document restore as guaranteed after force delete
• keep restore paths covered in tests