# Add Soft Delete to a Litestar App

Yes. An agent adds a deleted_at column to your Litestar models, an Alembic migration, a repository filter that hides deleted rows, and a restore route, with tests.

[Run this on Rush](https://cloud.getrush.ai/run/add-soft-delete/litestar/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the models, the services and the routes that delete. In an app laid out like litestar-org/litestar-fullstack, the models under `src/py/app/db/models/` extend advanced-alchemy's `UUIDv7AuditBase`, which already gives each table `created_at` and `updated_at`; `User` in `_user.py` maps to `user_account` with `is_active`, `is_verified` and `is_superuser` flags, and `Team` in `_team.py` adds `SlugKey`. Each domain service, such as `UserService` in `domain/accounts/services/_user.py`, is a `SQLAlchemyAsyncRepositoryService` with an inner `Repo` class, and the controllers call `users_service.delete(user_id)` from `DeleteUser` in `domain/accounts/controllers/_user.py` and `teams_service.delete(team_id)` from `DeleteTeam`, guarded by `requires_team_ownership`. Migrations live in `src/py/app/db/migrations/` with their own `alembic.ini`, the first being `2026-01-04_initial_dc54b25d8b6c.py`, and the `app database` CLI group applies them.

It adds a `SoftDeleteMixin` beside the base classes with a nullable `deleted_at` timestamp column, mixes it into `User` and `Team`, and writes one migration that adds the column to `user_account` and `team` with an index, so the filter in the next step does not scan the table. The migration is written by hand in the style of the initial one rather than autogenerated, so that the batch-mode blocks and naming conventions the project uses are kept.

In each affected service's `Repo`, the base statement gains `where(deleted_at IS NULL)`, so `get`, `list`, `exists` and `count` stop returning deleted rows without any controller changing. `delete` is overridden to set `deleted_at` and, for users, `is_active` to false, which `UserService.authenticate` already refuses, so a deleted user cannot sign in even with a valid refresh token. A `restore` method clears the timestamp, and the agent adds a `POST /{user_id:uuid}/restore` route beside `DeleteUser` for superusers and the matching team route under the ownership guard. The unique index on `user_account.email` is left alone, and the pull request names the consequence: a deleted address cannot register again until the row is restored or purged.

Tests follow the project's own layout. Under `src/py/tests/integration/accounts/` the agent adds cases that delete a user through the route, read it back and get 404, list users and see it absent, sign in and get refused, then restore and see all three reversed; a unit test checks the mixin on a plain session. It runs `uv sync --all-groups`, `uv run pre-commit run --all-files` for ruff, codespell and the standard hooks, `make type-check` for mypy and pyright, and `uv run pytest src/py/tests` against the PostgreSQL that `pytest-databases` starts, before opening the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add soft delete to this Litestar app for the user and team models. Read the model files under the db models package, the services and controllers under each domain package, the Alembic migrations directory and its first migration, the database settings and the test fixtures first. Add a mixin with a nullable indexed deleted_at timestamp, apply it to the user and team models, and write one hand-written migration in the style of the existing one. In each affected service's repository, filter deleted rows out of the base statement so get, list, exists and count skip them; override delete to set deleted_at, and for users also clear the active flag; add a restore method and a restore route next to each delete route under the same guards. Leave unique constraints as they are and state the consequence for re-registration in the pull request. Add integration tests for delete, read, list, sign-in refusal and restore in the existing tests layout. Run the project's pre-commit hooks, its type-check make target and the full pytest suite, and open a pull request that lists every file changed and the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes the models package to add the mixin and apply it to `User` and `Team`, adds one migration under `db/migrations/versions/`, changes the user and team services and controllers, and adds tests under `src/py/tests/integration/`. Its description lists the files, the new routes with their guards, the pre-commit, type-check and pytest summaries from the sandbox, and the note about the email unique index.

Once merged and `app database upgrade` has run, a delete through the API marks the row and hides it from every read, and the restore route brings it back with its history intact; the audit log table the project keeps is untouched by either.

Before merging, a reviewer checks the migration against the production database for the cost of adding an indexed column to `user_account`, decides whether a scheduled purge of long-deleted rows is wanted, and confirms that admin listings which should include deleted users pass an explicit filter rather than relying on the default.

## Run it on every Linear issue labelled soft-delete

A team that tracks this work in Linear adds an automation to the Project with a `linear` trigger on issues labelled `soft-delete` and this prompt; each labelled issue starts one run, and the trigger adds the issue after the prompt, so the issue's own text names the models to cover. The run opens a pull request and links it on the issue.

An automation run has its own `max_runs_per_hour` cap, and a label applied to more issues than the cap allows in one hour gets the extra fires skipped with `rate_limited`, not queued, so raise the cap or label in smaller batches. Each run works in its own sandbox with its own PostgreSQL, so two issues touching different models never share a database.

## Why run it on Rush?

Soft delete touches a model, a migration, every read path and the sign-in check at once, and it is easy to leave one path returning deleted rows. The agent changes the repository base statement so every read inherits the filter, proves it with the project's own integration tests against a real PostgreSQL, and runs the same pre-commit hooks CI runs, all in its own sandbox.

The test run, the migration file and the type-checker output stay with the run, so the reviewer reads a pull request whose claims are already checked. A team adding the same behaviour to several services starts one run per repository at the same time.

## Frequently asked questions

### Will existing delete calls keep working?

Yes. The controllers still call the service's `delete`, which now marks the row instead of removing it. Nothing in the API shape changes; the restore routes are additions.

### Why filter in the repository rather than in each controller?

Every service reads through its `Repo`, so adding the condition to its base statement covers `get`, `list`, `exists` and `count` at once, and a route added later inherits it. A controller that needs deleted rows, such as an admin listing, asks for them explicitly.

### What about the unique email constraint?

It stays. A soft-deleted user keeps the address, so registering it again is refused until the row is restored or purged. The pull request states this so the team can decide whether to add a purge job or a partial unique index later.

### Does the migration run automatically?

No. It is a file under the migrations directory, and `app database upgrade` applies it, as the README describes for the existing migrations. The agent runs it against the test database in its sandbox to prove it applies cleanly.

### Can a deleted user still use a refresh token?

No. Delete clears `is_active`, and the existing `authenticate` and token paths already refuse an inactive user, so the agent adds a test for that refusal rather than new logic.

## More Litestar jobs

- [Add Structured Logging to a Litestar App](https://getrush.ai/run/add-structured-logging/litestar/)
- [Add WebSockets to a Litestar App](https://getrush.ai/run/add-websockets/litestar/)
- [Upgrade Python Dependencies Weekly for a Litestar App](https://getrush.ai/run/upgrade-python-dependencies/litestar/)

## The same job on other stacks

- [Add Soft Delete to a Mongoose Model](https://getrush.ai/run/add-soft-delete/mongoose/)
- [Add Soft Delete to a Prisma Schema](https://getrush.ai/run/add-soft-delete/prisma/)
- [Add Soft Delete to a Quarkus Panache Entity](https://getrush.ai/run/add-soft-delete/quarkus/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
