---

name: axum description: | Axum 0.8+ production patterns with SQLx. Use when: building Rust APIs, async database, error handling. Do not use for: API design decisions (use api-design skill). Workflow: api-design (design) → this skill (implementation). references:

• examples.md # Transaction, testing, error handling patterns

---

Axum + SQLx

For latest axum APIs, use context7. For latest sqlx APIs, use context7.

Project Structure

Copysrc/
├── main.rs
├── config.rs
├── db.rs                # Pool setup
├── error.rs             # AppError + IntoResponse
└── features/
    └── users/
        ├── mod.rs
        ├── router.rs
        ├── handlers.rs
        ├── models.rs
        └── service.rs
migrations/
.sqlx/                   # Offline cache (COMMIT THIS)

---

Critical Patterns

State (Don't Double-Arc)

Copy// PgPool is Arc internally - NEVER wrap again
#[derive(Clone)]
pub struct AppState {
    pub db: PgPool,  // ✅ Direct
    // pub db: Arc<PgPool>,  // ❌ Double Arc
}

Rule: PgPool is already Arc. Wrapping again wastes memory.

Route Syntax (Axum 0.8+)

Copy// ❌ Old syntax (0.7 and below)
.route("/users/:id", get(get_user))

// ✅ New syntax (0.8+)
.route("/users/{id}", get(get_user))

Rule: Axum 0.8 uses {id}, not :id.

Transaction Dereference

Copylet mut tx = state.db.begin().await?;

// ❌ Won't compile
sqlx::query!(...).fetch_one(tx).await?;

// ✅ Dereference with &mut *tx
sqlx::query!(...).fetch_one(&mut *tx).await?;

tx.commit().await?;

Rule: Always use &mut *tx when passing transaction to queries.

Query Method Selection

Copy// ❌ Errors if user doesn't exist
let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
    .fetch_one(&state.db)
    .await?;

// ✅ Handle missing gracefully
let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
    .fetch_optional(&state.db)
    .await?
    .ok_or(AppError::NotFound)?;

Rule: Use fetch_optional for lookups. fetch_one only when row must exist.

---

SQLx Type Mapping

Rule: Nullable column must be Option<T>. Mismatch = runtime panic.

---

Offline Mode (CI/CD)

Copy# 1. Generate cache locally (requires DATABASE_URL)
cargo sqlx prepare

# 2. Commit .sqlx/ directory
git add .sqlx/

# 3. In CI (no database needed)
SQLX_OFFLINE=true cargo build

Rule: Always commit .sqlx/. Run cargo sqlx prepare before pushing.

---

Common Gotchas

Pool Configuration

CopyPgPoolOptions::new()
    .max_connections(10)
    .acquire_timeout(Duration::from_secs(3))  // Fail fast
    .idle_timeout(Duration::from_secs(600))
    .connect(database_url)
    .await?

Rule: Always set acquire_timeout. Silent hangs are worse than errors.

---

Quick Checklist

Syntax

• {id} for path params (not :id)
• &mut *tx for transactions

SQLx

• fetch_optional for lookups
• Nullable columns are Option<T>
• .sqlx/ committed
• cargo sqlx prepare before CI

Pool

• No double Arc on PgPool
• acquire_timeout set
• Don't hold transactions long

Errors

• AppError implements IntoResponse
• Map sqlx::Error to proper HTTP status

Security Configuration