Soft Delete | Bootspring Docs

Patterns for implementing soft delete with Prisma.

Overview#

Soft delete preserves data by marking records as deleted rather than removing them:

Data recovery capability
Audit trail preservation
Compliance requirements
Referential integrity

Prerequisites:

Prisma ORM setup
deletedAt column in relevant tables

Implementation#

Schema Setup#

// prisma/schema.prisma
model Document {
  id        String    @id @default(cuid())
  title     String
  content   String?
  deletedAt DateTime? // Soft delete marker
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt

  @@index([deletedAt])
}

Prisma Client Extension#

// lib/db.ts
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient().$extends({
  query: {
    document: {
      async findMany({ args, query }) {
        args.where = { ...args.where, deletedAt: null }
        return query(args)
      },
      async findFirst({ args, query }) {
        args.where = { ...args.where, deletedAt: null }
        return query(args)
      },
      async findUnique({ args, query }) {
        // findUnique doesn't support compound where, use findFirst
        return query(args)
      },
      async delete({ args }) {
        return prisma.document.update({
          where: args.where,
          data: { deletedAt: new Date() }
        })
      },
      async deleteMany({ args }) {
        return prisma.document.updateMany({
          where: args.where,
          data: { deletedAt: new Date() }
        })
      }
    }
  }
})

export { prisma }

Manual Soft Delete#

// lib/documents.ts
import { prisma } from '@/lib/db'

export async function softDelete(id: string) {
  return prisma.document.update({
    where: { id },
    data: { deletedAt: new Date() }
  })
}

export async function restore(id: string) {
  return prisma.document.update({
    where: { id },
    data: { deletedAt: null }
  })
}

export async function hardDelete(id: string) {
  return prisma.document.delete({
    where: { id }
  })
}

Query Helpers#

// lib/documents.ts
// Only active (non-deleted)
export async function findActive() {
  return prisma.document.findMany({
    where: { deletedAt: null }
  })
}

// Only deleted
export async function findDeleted() {
  return prisma.document.findMany({
    where: { deletedAt: { not: null } }
  })
}

// Include deleted (for admin)
export async function findAll() {
  return prisma.document.findMany()
}

// With deleted flag
export async function findWithDeletedFlag(id: string) {
  const doc = await prisma.document.findUnique({
    where: { id }
  })

  return doc ? { ...doc, isDeleted: !!doc.deletedAt } : null
}

Cascade Soft Delete#

// lib/documents.ts
export async function softDeleteWithRelations(userId: string) {
  const now = new Date()

  return prisma.$transaction([
    // Soft delete user
    prisma.user.update({
      where: { id: userId },
      data: { deletedAt: now }
    }),
    // Soft delete user's posts
    prisma.post.updateMany({
      where: { authorId: userId },
      data: { deletedAt: now }
    }),
    // Soft delete user's comments
    prisma.comment.updateMany({
      where: { authorId: userId },
      data: { deletedAt: now }
    })
  ])
}

Middleware Approach#

// lib/db.ts
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

// Add soft delete middleware
prisma.$use(async (params, next) => {
  // Models with soft delete
  const softDeleteModels = ['User', 'Post', 'Comment']

  if (softDeleteModels.includes(params.model || '')) {
    // Override delete to soft delete
    if (params.action === 'delete') {
      params.action = 'update'
      params.args.data = { deletedAt: new Date() }
    }

    if (params.action === 'deleteMany') {
      params.action = 'updateMany'
      params.args.data = { deletedAt: new Date() }
    }

    // Filter out soft-deleted records
    if (['findUnique', 'findFirst', 'findMany'].includes(params.action)) {
      if (!params.args.where) {
        params.args.where = {}
      }
      if (params.args.where.deletedAt === undefined) {
        params.args.where.deletedAt = null
      }
    }
  }

  return next(params)
})

export { prisma }

Restore Functionality#

// lib/documents.ts
export async function restoreWithRelations(userId: string) {
  // Get the deletion timestamp
  const user = await prisma.user.findUnique({
    where: { id: userId }
  })

  if (!user?.deletedAt) {
    throw new Error('User is not deleted')
  }

  const deletedAt = user.deletedAt

  return prisma.$transaction([
    // Restore user
    prisma.user.update({
      where: { id: userId },
      data: { deletedAt: null }
    }),
    // Restore posts deleted at the same time
    prisma.post.updateMany({
      where: {
        authorId: userId,
        deletedAt: deletedAt
      },
      data: { deletedAt: null }
    }),
    // Restore comments deleted at the same time
    prisma.comment.updateMany({
      where: {
        authorId: userId,
        deletedAt: deletedAt
      },
      data: { deletedAt: null }
    })
  ])
}

Trash View#

// app/admin/trash/page.tsx
import { findDeleted, restore, hardDelete } from '@/lib/documents'
import { formatDistanceToNow } from 'date-fns'

export default async function TrashPage() {
  const deletedItems = await findDeleted()

  return (
    <div className="space-y-4">
      <h1 className="text-2xl font-bold">Trash</h1>

      {deletedItems.map(item => (
        <div key={item.id} className="flex items-center justify-between border p-4 rounded">
          <div>
            <h3 className="font-medium">{item.title}</h3>
            <p className="text-sm text-gray-500">
              Deleted {formatDistanceToNow(item.deletedAt!, { addSuffix: true })}
            </p>
          </div>

          <div className="flex gap-2">
            <form action={async () => {
              'use server'
              await restore(item.id)
            }}>
              <button className="text-blue-600">Restore</button>
            </form>

            <form action={async () => {
              'use server'
              await hardDelete(item.id)
            }}>
              <button className="text-red-600">Delete Forever</button>
            </form>
          </div>
        </div>
      ))}
    </div>
  )
}

Cleanup Job#

// scripts/cleanup-deleted.ts
import { prisma } from '@/lib/db'

const RETENTION_DAYS = 30

async function cleanup() {
  const cutoffDate = new Date()
  cutoffDate.setDate(cutoffDate.getDate() - RETENTION_DAYS)

  // Hard delete old soft-deleted records
  const result = await prisma.document.deleteMany({
    where: {
      deletedAt: {
        not: null,
        lt: cutoffDate
      }
    }
  })

  console.log(`Permanently deleted ${result.count} records`)
}

cleanup()
  .catch(console.error)
  .finally(() => prisma.$disconnect())

Best Practices#

Add index on deletedAt - Improves query performance
Use transactions for cascades - Ensure consistency
Set retention policies - Don't keep deleted data forever
Provide admin restore UI - Allow data recovery
Document the behavior - Make soft delete explicit

Prisma - Prisma setup and basics
Transactions - Transaction handling
Migrations - Adding deletedAt column