Trash

trash sets a subject's deletedAt column instead of deleting the row, records it in trash_items, and trashes the rows that point at it in the same batch. Restoring a trash item restores its whole batch. Reading the trash needs trash.read, trashing needs trash.create and the subject's write permission, restoring needs trash.restore, and purging needs trash.manage.

better-supabase sql add trash

import { createTrash } from "better-supabase/blocks/trash";

const trash = createTrash({ transport });
const batch = await trash.trash(organizationId, "project", projectId).orThrow();
const bin = await trash.list(organizationId).orThrow();
await trash.restore(batch.id).orThrow();

Configure subjectsCopy Anchor Link

Every config.subjects entry with a deletedAt column can be trashed; title names the column the trash list shows. Per subject, unique lists the columns no live row in the organization may share when the row is restored, and children lists the subjects trashed with it.

subjects: {
  project: { table: "public.projects", idType: "uuid", title: "name", deletedAt: "deleted_at" },
  task: { table: "public.tasks", idType: "uuid", title: "title", deletedAt: "deleted_at" },
},
sql: {
  modules: {
    trash: {
      options: {
        retentionDays: 30,
        subjects: {
          project: { unique: ["slug"], children: [{ type: "task", column: "project_id" }] },
          task: {},
        },
      },
    },
  },
},

Children are trashed recursively, so a project trashes its tasks and their own children. A child that was already in the trash stays in its own batch.

Hide trashed rowsCopy Anchor Link

Filter on the deletedAt column in queries and policies (deleted_at is null). For a policy that can't see the column, better_supabase.is_trashed(subject_type, subject_id) tells whether a subject is in the trash:

create policy "projects_read" on public.projects for select to authenticated
  using (deleted_at is null and organization_id in (select better_supabase.tenant_ids_with('projects.read')));

The subject registry functions (can_subject, subject_title) already skip rows with deletedAt set.

PurgeCopy Anchor Link

purge(id) deletes a batch's rows for good, children first. purge_expired_trash() purges batches past their retention; schedule it with pg_cron or the jobs drain:

select cron.schedule('purge-trash', '15 3 * * *', 'select better_supabase.purge_expired_trash()');

Events and hooksCopy Anchor Link

The module records subject.trashed, subject.restored and subject.purged for every row, each with organizationId, subjectType, subjectId, the trash item id and the batchId, so search indexes and data lifecycle can follow them. It calls before_trash, after_trash, before_untrash and after_untrash around trash and restore.

With ReUICopy Anchor Link

A bin page renders list() in a ReUI data grid, with restore and delete-forever actions per row. count shows how many rows a batch holds, and purgeAfter when it goes for good.