sqlalchemy-soft-delete

A lightweight SQLAlchemy mixin that adds soft delete to any model. Instead of permanently removing rows, it sets a deleted_at timestamp — so you never lose data again.

Features

• Drop-in mixin — add SoftDeleteMixin to any model and you're done
• deleted_at timestamp — know exactly when a row was deleted
• is_deleted hybrid property — use in Python and in SQL queries
• soft_delete() / restore() — intuitive instance methods
• with_deleted() helper — bypass the filter when you need to see everything
• SQLAlchemy 2.0+ native — built on Mapped, mapped_column, and hybrid_property
• Zero dependencies beyond SQLAlchemy itself
• Fully typed — works great with mypy and IDE autocompletion

Installation

pip install sqlalchemy-soft-delete

Quick Start

Before (hard delete)

session.delete(user)  # Gone forever
session.commit()

After (soft delete)

from sqlalchemy_soft_delete import SoftDeleteMixin

class User(SoftDeleteMixin, Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]

# Soft delete — row stays in the database
user.soft_delete()
session.commit()

# Restore whenever you need
user.restore()
session.commit()

Usage

Soft deleting a row

user = session.get(User, 1)
user.soft_delete()
session.commit()

print(user.is_deleted)   # True
print(user.deleted_at)   # 2026-04-17 12:34:56+00:00

Restoring a soft-deleted row

user.restore()
session.commit()

print(user.is_deleted)   # False
print(user.deleted_at)   # None

Querying only active rows

from sqlalchemy import select

# Filter out deleted rows explicitly
stmt = select(User).where(~User.is_deleted)
active_users = session.execute(stmt).scalars().all()

Querying all rows (including deleted)

# No filter — returns everything
stmt = select(User)
all_users = session.execute(stmt).scalars().all()

Querying only deleted rows

stmt = select(User).where(User.is_deleted)
deleted_users = session.execute(stmt).scalars().all()

API Reference

SoftDeleteMixin

with_deleted(query)

Marks a legacy Query object to include soft-deleted rows via execution options.

Requirements

• Python 3.10+
• SQLAlchemy 2.0+

License

MIT License. See LICENSE for details.