Rust Axum API

Scaffold production-ready HTTP services in Rust using Axum, Tokio, and sqlx. This skill generates a working project with typed handlers, tower middleware wired up, an async Postgres pool, and a multi-stage Dockerfile that produces a tiny statically-linked image. It's aimed at developers who want the performance and type-safety of Rust for backend services without spending a day assembling boilerplate from blog posts.

When to use it

• Starting a new JSON API or microservice and you want sqlx + Axum set up correctly the first time.
• Adding routes to an existing Axum app and you want consistent extractor/handler signatures.
• You need a small container image for cost-sensitive deploys (Fly.io, Cloud Run, a cheap VPS).
• Replacing a Node/Python service where p99 latency or memory footprint matters.

What it does

The skill lays down a Cargo.toml with axum, tokio (with the macros and rt-multi-thread features), sqlx (runtime-tokio-rustls, postgres, macros), tower, tower-http, and serde. It generates:

• A Router built with .route("/path", get(handler)) and merged sub-routers.
• Handlers using real extractors — Path<T>, Query<T>, Json<T>, and State<AppState> — returning Result<Json<T>, AppError> where AppError implements IntoResponse.
• A shared PgPool created via PgPoolOptions::new().connect(&url), stored in State and cloned cheaply per request.
• Compile-time-checked queries with the sqlx::query! / query_as! macros (backed by sqlx-cli and a .sqlx offline cache).
• tower-http layers: TraceLayer, CorsLayer, and timeout/compression as needed.
• A migrations/ folder runnable with sqlx migrate run, and a distroless/scratch Dockerfile.

Usage

curl -fsSL --create-dirs -o ~/.claude/skills/rust-axum-api/SKILL.md https://claudeskil.com/skills/rust-axum-api/SKILL.md

# then, in your project
cargo sqlx prepare          # build the offline query cache
cargo run                   # serves on 0.0.0.0:3000
docker build -t my-api .    # ~20MB final image

A generated handler looks like:

async fn get_user(
    State(pool): State<PgPool>,
    Path(id): Path<i64>,
) -> Result<Json<User>, AppError> {
    let user = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
        .fetch_one(&pool)
        .await?;
    Ok(Json(user))
}

Tips & gotchas

• query! macros hit the database at compile time. Set DATABASE_URL or commit the .sqlx cache (cargo sqlx prepare) so CI/Docker builds don't need a live DB.
• Extractor order matters: body-consuming extractors like Json must be the last argument in a handler.
• For the tiny image, build with the x86_64-unknown-linux-musl target so the binary runs on scratch/distroless without glibc.
• Add TraceLayer last in your layer stack so it wraps everything beneath it.

FAQ

Does it use SeaORM or Diesel? No — it uses sqlx with raw, compile-checked SQL. You write SQL, sqlx verifies it against your schema.

How is the image only ~20MB? A musl static build copies a single binary into a scratch base; there's no runtime, interpreter, or OS layer.

Can I add auth/middleware? Yes — write a tower layer or an extractor (e.g. a FromRequestParts impl for a Claims type) and attach it with .layer() or per-route.