# Add Graceful Shutdown to an Axum API

Yes. An agent makes your Axum server stop on SIGTERM, finish in-flight requests, close the SQLx pool, and opens a PR with a test that proves it.

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

## What the agent does

The agent starts by finding where the server is started and what it holds open. In an API shaped like launchbadge/realworld-axum-sqlx, `Cargo.toml` pins `axum` 0.3.4, `tokio` 1.14 with only the `macros` and `rt-multi-thread` features, `sqlx` 0.5 on Postgres and `env_logger` for output. `src/main.rs` parses `Config` with clap, builds a `PgPoolOptions` pool with `max_connections(50)`, runs the embedded migrations with `sqlx::migrate!()` and calls `http::serve(config, db)`. In `src/http/mod.rs`, `serve` wraps `api_router()` in a `ServiceBuilder` with an `AddExtensionLayer` carrying `ApiContext` and a `TraceLayer`, then calls `axum::Server::bind` on `0.0.0.0:8080` and awaits `.serve(app.into_make_service())`. Nothing listens for a signal: a `SIGTERM` from Docker or Kubernetes kills the process mid-request, and the pool's connections are dropped without being closed.

The fix stays inside the versions the lockfile already has. `axum::Server` in 0.3 is hyper 0.14's `Server`, which has `with_graceful_shutdown`, so no crate moves. The agent adds the `signal` feature to `tokio` in `Cargo.toml`, writes a `shutdown_signal` future in `src/http/mod.rs` that waits on `tokio::signal::ctrl_c()` and, under `cfg(unix)`, on `SignalKind::terminate()` through `tokio::select!`, and passes it to `.with_graceful_shutdown(shutdown_signal())`. hyper then stops accepting connections, lets requests already being handled finish and resolves the future. `serve` keeps a clone of the `PgPool` outside the `ApiContext` so that, once the server future returns, it calls `db.close().await` and logs the shutdown through the `log` facade `env_logger` already prints.

Because the crate exposes `config` and `http` from `src/lib.rs` and builds one binary, the proof is an integration test in `tests/graceful_shutdown.rs` that drives the real executable through `env!("CARGO_BIN_EXE_realworld-axum-sqlx")`. It starts the server with the `DATABASE_URL` and `HMAC_KEY` the workflow already exports, polls `GET /api/tags` until it answers, sends `SIGTERM` with `kill` on the child's pid, and asserts that the process exits with status 0 within a bounded wait rather than being killed, and that a new connection is refused afterwards. On Windows the test is skipped with `cfg(unix)`, matching the signal branch.

Before pushing, the agent runs the same steps as `.github/workflows/rust.yml`: `sqlx db setup` against the Postgres service, `cargo build --verbose`, `cargo test --verbose`, then `cargo run` in the background and the Realworld Postman collection from the `abonander/realworld` checkout the workflow pins. It also runs `cargo fmt --check` and `cargo clippy`, and adds a short section to `README.md` on how the binary stops.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add graceful shutdown to this Axum API and open a pull request. Read Cargo.toml, Cargo.lock, src/main.rs, src/lib.rs, src/http/mod.rs, .env.sample and .github/workflows/rust.yml first; do not upgrade axum, hyper, tokio or sqlx. Add the signal feature to tokio. In src/http/mod.rs write an async shutdown_signal that completes on ctrl_c and, on unix, on SIGTERM, and pass it to the server with with_graceful_shutdown. Keep a clone of the PgPool outside ApiContext and close it after the server future returns, logging the shutdown with the log crate. Add tests/graceful_shutdown.rs: start the built binary with the DATABASE_URL and HMAC_KEY from the environment, wait until GET /api/tags answers, send SIGTERM to the child, and assert it exits with status 0 within a bounded wait and that a new connection is then refused; gate the test on unix. Run sqlx db setup, cargo build --verbose, cargo test --verbose, cargo fmt --check and cargo clippy, then run the server and the Realworld Postman collection the workflow uses, and paste the output in the pull request description. Document how the server stops in README.md. Do not change any route, extractor or migration.",
  "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

What comes back is a pull request with the `signal` feature on `tokio` in `Cargo.toml`, the `shutdown_signal` future and the `with_graceful_shutdown` call in `src/http/mod.rs`, the pool close after the server returns, a new `tests/graceful_shutdown.rs`, and a README section. `Cargo.lock` does not change, because a feature flag on a crate already in the lockfile adds no version. The description shows the test's output and the log lines the binary prints when it receives `SIGTERM`.

The repository's `Rust` workflow runs on the pull request with its Postgres service container, so the new test runs under `cargo test --verbose` with the workflow's `DATABASE_URL`, and the Postman collection still runs against `cargo run` after it. The agent pushes one commit for the server change and one for the test and README.

A reviewer checks that the signal future covers both `ctrl_c` and `SIGTERM`, that the pool is closed after the server future and not before, that the test waits on exit status rather than sleeping a fixed time, and that `users`, `profiles` and `articles` are untouched. Then they confirm their deployment sends `SIGTERM` and waits before `SIGKILL`.

## Run it on every new Rust service

A team that runs several Axum APIs behind the same deployment starts one run per repository with `POST /o/{org}/sessions`, this prompt and the repository in `resources`. Each run reads its own `serve` function and pool setup, so a service that holds a Redis client or a background task gets those closed in the same place, and each opens its own pull request.

The key's `webhook_url` receives `run.completed` for each run it starts, with a `session_url` for the result, so a script can collect the pull request links and open them for review together.

## Why run it on Rush?

Shutdown bugs only show under a real signal against a real process, which is why they survive code review. In a Rush sandbox the agent builds the binary, starts it against Postgres, sends `SIGTERM` from the test and reads the exit status and the log output; every command and its output is kept in the run's transcript, so the pull request links to the evidence rather than describing it.

The change is checked by the repository's own gates before anyone opens it: the build, the unit tests, the new integration test and the Realworld Postman collection that `rust.yml` runs. The same request works unchanged on every Axum service the team owns, each in its own sandbox at the same time.

## Frequently asked questions

### Does axum 0.3 support graceful shutdown without an upgrade?

Yes. `axum::Server` in that release is hyper 0.14's `Server`, whose `with_graceful_shutdown` takes any future and stops accepting connections when it completes. The agent only adds the `signal` feature to `tokio`, which the lockfile already pins at 1.14, so no dependency version moves.

### What happens to requests that are running when the signal arrives?

hyper finishes the connections it is already serving and closes idle keep-alive connections, then resolves the server future. Only after that does the agent's code close the SQLx pool, so a handler in the middle of a query keeps its connection until it answers.

### Will it wait forever for a stuck request?

The server itself waits for in-flight connections to finish. Your orchestrator's termination grace period is the upper bound, after which it sends `SIGKILL`; the pull request documents that in `README.md` so the deployment's grace period is set on purpose rather than by default.

### Does the test slow down the suite?

It starts one process, waits until `GET /api/tags` answers, sends the signal and waits on the exit status, so it takes as long as one startup plus one shutdown. It is gated on unix because the `SIGTERM` branch is, and it uses the same `DATABASE_URL` the existing workflow exports.

## More Axum jobs

- [Add Health Checks to an Axum Service](https://getrush.ai/run/add-health-checks/axum/)
- [Add Input Validation to an Axum API](https://getrush.ai/run/add-input-validation/axum/)
- [Add OpenAPI Docs to an Axum API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/axum/)

## The same job on other stacks

- [Add Graceful Shutdown to a Go chi API](https://getrush.ai/run/add-graceful-shutdown/chi/)
- [Add Graceful Shutdown to an Echo App](https://getrush.ai/run/add-graceful-shutdown/echo/)
- [Add Graceful Shutdown to a Fiber App](https://getrush.ai/run/add-graceful-shutdown/fiber/)

## 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/)
