Skip to content

ADR-0010: Soft delete is a nullable delete_time column, in AIP-164's shape

Status: accepted (2026-10-04) · Scope: soft delete in both ORM packages and both HTTP stacks

Decision

A resource that offers soft delete carries a nullable delete_time timestamp, NULL while the resource is live. It is the only soft-delete state: there is no deleted flag and no status value for it. The column is independent of status.

On the wire the timestamp is the read-only deleteTime of AIP-164, and DELETE, :undelete and showDeleted follow that AIP. Visibility is decided by the view or the query, where the action is known. No default manager or session hook hides deleted rows.

Consequences

deleteTime is a stored fact, so it survives later writes, including the write that undeletes. A nullable timestamp serves the common filter, delete_time IS NULL, with an ordinary index. It matches the column that django-safedelete (deleted) and sqlalchemy-easy-softdelete (deleted_at) use.

Every query that should hide deleted rows must say so, through .live() on Django or live() on SQLAlchemy. A query that forgets returns deleted rows. Django's existing Status.Deleted value does not mean soft-deleted, and whether to remove it stays with the model-vocabulary idea.

Influences

This decision shapes F12.2, which holds the wire rules and the per-package design. It replaces the status-based soft delete proposed in the model-vocabulary idea.

Alternatives considered

  • Status-based soft delete (status = DELETED, no timestamp column). deleteTime cannot come from a status. Deriving it from update_time breaks on the first write after the delete, and :undelete is such a write. It also mixes lifecycle state with retention.
  • A boolean is_deleted flag. It records neither when nor by whom, and gives AIP-164 no deleteTime.
  • A default manager or global session hook that hides deleted rows. AIP-164 says a get returns the deleted resource. A hidden row also breaks related-object lookups and the Django admin in ways that are hard to see.

Background

Decided by the owner's request on 2026-10-04, when F12.2 was scheduled ahead of the model-vocabulary idea. The idea had said that whichever was taken up first would settle the other.