---
id: sqlalchemy-easy-softdelete
version: "0.9.1"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# sqlalchemy-easy-softdelete — Easily add soft-deletion to your SQLAlchemy Models.

License: permissive · Maintenance: active · Downloads: 174.4K/mo

## What it is and what it does

sqlalchemy-easy-softdelete is a mixin generator that adds soft-deletion semantics to SQLAlchemy models without requiring schema changes or explicit WHERE clauses in every query. Instead of deleting records, you mark them with a timestamp (by default `deleted_at`), and the library installs a query hook that automatically filters out soft-deleted rows from all SELECT statements—both in direct queries and through model relationships. You generate a customized mixin class, apply it to your models, and gain `.delete()` and `.undelete()` methods plus automatic query rewriting.

The mixin is fully configurable: you can choose the field name, its type, whether to include delete/undelete methods, and which tables the hook should ignore. This approach preserves audit trails and referential integrity while keeping deleted data invisible by default—queries return only active records unless you explicitly pass `include_deleted=True` to override the filter.

Use it for:

- Implement audit trails in business applications where deleted records must remain in the database for compliance or recovery.
- Build multi-tenant systems where soft-deleted data must be excluded from user-facing queries but retained for administrative review.
- Add undo/restore functionality to applications without requiring complex transaction rollback or backup restoration.
- Maintain referential integrity in systems where cascading hard deletes would break historical reporting or linked records.
- Simplify query logic by removing the need to manually add `WHERE deleted_at IS NULL` conditions throughout the codebase.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds soft-deletion support to SQLAlchemy models with automatic query filtering and customizable mixin generation.

Yes. The package is actively maintained, has no known vulnerabilities, carries a permissive license, and solves a common ORM problem with minimal friction. The single dependency on sqlalchemy and low install overhead make it a safe addition. Use it if your application needs soft-deletion semantics; skip it if you never need to preserve deleted records or audit trails.

## Install

pip install sqlalchemy-easy-softdelete
uv add sqlalchemy-easy-softdelete
poetry add sqlalchemy-easy-softdelete

## Installing sqlalchemy-easy-softdelete

Before you install: Low install friction; single dependency on sqlalchemy. Actively maintained with recent releases and a stable codebase marked as Production/Stable.

License in practice: BSD-3-Clause permissive license allows commercial and private use with minimal restrictions.

Quickstart:

pip install sqlalchemy-easy-softdelete

from sqlalchemy_easy_softdelete.mixin import generate_soft_delete_mixin_class
from sqlalchemy.orm import declarative_base
from sqlalchemy import Column, Integer

class SoftDeleteMixin(generate_soft_delete_mixin_class()):
    pass

Base = declarative_base()

class Fruit(Base, SoftDeleteMixin):
    __tablename__ = "fruit"
    id = Column(Integer, primary_key=True)

# Soft-delete: session.query(Fruit).all() excludes deleted rows
fruit.delete()
# Include deleted: session.query(Fruit).execution_options(include_deleted=True).all()

Requires Python 3.10 or later; SQLAlchemy must be installed separately.

Verify before relying:

- Whether the automatic query rewriting works correctly with all SQLAlchemy relationship types and lazy-loading strategies.
- Performance impact of the hook on large-scale queries or complex relationship chains.
- Compatibility with SQLAlchemy's async session and asyncio workflows.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 174.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sqlalchemy soft delete, soft deletion mixin, logical delete sqlalchemy, exclude deleted records automatically, soft-delete hook, sqlalchemy deleted_at field, automatic query filtering deleted, soft-delete, audit-trail, orm-pattern

[View on SkillFed](https://skillfed.io/packages/sqlalchemy-easy-softdelete) · [View on PyPI](https://pypi.org/project/sqlalchemy-easy-softdelete/)