All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading