{"id":390,"date":"2026-06-27T13:02:36","date_gmt":"2026-06-27T13:02:36","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/axum-sqlx-rust-backend-setup-i-actually-use-in-production\/"},"modified":"2026-06-27T13:02:36","modified_gmt":"2026-06-27T13:02:36","slug":"axum-sqlx-rust-backend-setup-i-actually-use-in-production","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/axum-sqlx-rust-backend-setup-i-actually-use-in-production\/","title":{"rendered":"Axum + sqlx: The Rust Backend Setup I Actually Use in Production"},"content":{"rendered":"

A few months back I wrote about picking between axum, actix, and rocket<\/a>. I picked axum on the next project, then spent a weekend Googling things like “axum sqlx state extractor not working.” The official docs are fine but scattered, and most tutorials online stop at hello-world.<\/p>\n

This post is the setup I actually have in production. Not the perfect one. The one that hasn’t woken me up at 3am yet. If you’ve already picked axum and want to wire it up to Postgres without writing your own ORM, here’s what I do.<\/p>\n

I’ll show the Cargo.toml, the sqlx wiring, the bit of state plumbing that always trips people up, and the error type that finally made me stop sprinkling .unwrap()<\/code> everywhere. Real code, the kind I copy-paste into new services.<\/p>\n

Why axum, briefly<\/h2>\n

I’m not going to re-litigate the framework debate. Short version: axum is a tower service, so anything that speaks tower (timeout layers, tracing, auth middleware, rate limiting) plugs in without ceremony. Actix has its own runtime quirks I never warmed to. Rocket is fine but moves slower than I’d like. axum sits on top of tokio and hyper, both of which have years of production miles. Read the axum docs<\/a> before you write a line of code, especially the page on extractors.<\/p>\n

Picking axum was the easy part. The harder part was figuring out the rest of the stack without ending up in dependency hell.<\/p>\n

The Cargo.toml I actually start with<\/h2>\n

Here’s the dependency block I copy-paste into every new axum service. I trimmed the project-specific bits.<\/p>\n

[dependencies]\naxum = "0.7"\ntokio = { version = "1", features = ["full"] }\nsqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "uuid", "chrono", "macros", "migrate"] }\ntower = "0.5"\ntower-http = { version = "0.6", features = ["trace", "cors", "timeout"] }\ntracing = "0.1"\ntracing-subscriber = { version = "0.3", features = ["env-filter"] }\nserde = { version = "1", features = ["derive"] }\nserde_json = "1"\nanyhow = "1"\nthiserror = "2"\nuuid = { version = "1", features = ["v4", "serde"] }\nchrono = { version = "0.4", features = ["serde"] }\n<\/code><\/pre>\n
Two things worth calling out. The tokio = \"full\"<\/code> flag is lazy. It’s what I do at the start, then trim once I know which features I actually need. The sqlx<\/code> macros<\/code> feature is the one I care about most. It’s what gives you compile-time checked SQL queries against your real database schema. More on that in a second.<\/p>\n
A note on anyhow<\/code> plus thiserror<\/code>. They are not the same thing and they are not interchangeable. anyhow<\/code> is for application code where you just want the error to bubble. thiserror<\/code> is for library boundaries and your API error type. Use both. They cost almost nothing.<\/p>\n
sqlx is the actual reason I picked this stack<\/h2>\n
I’ve tried diesel. I’ve tried seaorm. Both are fine. The thing that made me stick with sqlx is that it doesn’t make me learn a query DSL. I write SQL. The macro reads the SQL at compile time, connects to a dev Postgres, and tells me if I got a column name wrong before I run anything.<\/p>\n
let user = sqlx::query_as!(\n    User,\n    "SELECT id, email, created_at FROM users WHERE id = $1",\n    user_id\n)\n.fetch_one(&pool)\n.await?;\n<\/code><\/pre>\n
If I rename email<\/code> to email_address<\/code> in the database, this code refuses to compile. Not at runtime. At compile time. That alone was worth the switch from the ORM I had been using.<\/p>\n
You do have to set DATABASE_URL<\/code> for the macros to work, and if you don’t want every CI run to hit a real Postgres, you cache the query metadata with cargo sqlx prepare<\/code>. The sqlx docs<\/a> cover this, but it’s the kind of thing nobody tells you on day one. The same docs cover the migration runner. I used to write my own runner and it was a waste of an afternoon.<\/p>\n
Pool sizing: the only sqlx config I tune<\/h2>\n
The default PgPool<\/code> settings are fine for a dev loop and disastrous in production. The defaults give you up to ten connections and no acquire timeout. The first time I deployed this stack, a slow query held the pool open and the next 200 requests piled up waiting for a free connection. The service didn’t crash. It just stopped responding, which is worse.<\/p>\n
The config I use looks like this:<\/p>\n
use sqlx::postgres::PgPoolOptions;\nuse std::time::Duration;\n\nlet pool = PgPoolOptions::new()\n    .max_connections(20)\n    .min_connections(2)\n    .acquire_timeout(Duration::from_secs(3))\n    .idle_timeout(Duration::from_secs(60 * 10))\n    .connect(&std::env::var("DATABASE_URL")?)\n    .await?;\n<\/code><\/pre>\n
max_connections<\/code> should be lower than your Postgres max_connections<\/code> setting divided by the number of service replicas. acquire_timeout<\/code> is the one nobody sets and everyone wishes they had after their first outage. If a handler can’t grab a connection in three seconds, you want it to fail fast and surface the error, not silently queue forever.<\/p>\n
State plumbing: the thing that always bites people<\/h2>\n
Sharing a database pool across handlers in axum looks simple until you hit your first lifetime error. Here’s the pattern I use.<\/p>\n
use axum::{extract::State, routing::get, Router, Json};\nuse sqlx::PgPool;\n\n#[derive(Clone)]\nstruct AppState {\n    db: PgPool,\n}\n\nasync fn list_users(\n    State(state): State<AppState>,\n) -> Result<Json<Vec<User>>, AppError> {\n    let users = sqlx::query_as!(\n        User,\n        "SELECT id, email, created_at FROM users"\n    )\n    .fetch_all(&state.db)\n    .await?;\n    Ok(Json(users))\n}\n\n#[tokio::main]\nasync fn main() -> anyhow::Result<()> {\n    let pool = PgPool::connect(&std::env::var("DATABASE_URL")?).await?;\n    let state = AppState { db: pool };\n\n    let app = Router::new()\n        .route("\/users", get(list_users))\n        .with_state(state);\n\n    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;\n    axum::serve(listener, app).await?;\n    Ok(())\n}\n<\/code><\/pre>\n
Two things I got wrong the first three times. First, AppState<\/code> has to be Clone<\/code>. PgPool<\/code> is itself an Arc<\/code> internally, so cloning is cheap. Do not put a Mutex<PgPool><\/code> in there. Second, the State<\/code> extractor in the handler has to match the type you passed to with_state<\/code>. If you have multiple sub-states, look at FromRef<\/code>. The compiler error when you get this wrong is dense and unhelpful, and that’s the bit that ate my Saturday.<\/p>\n
Error handling without the .unwrap()<\/code> graveyard<\/h2>\n
The pattern I settled on is a single AppError<\/code> enum that implements IntoResponse<\/code>. This is the thing that turned my early axum code from “Rust with sprinkled panics” into something I’d actually deploy.<\/p>\n
use axum::{\n    http::StatusCode,\n    response::{IntoResponse, Response},\n    Json,\n};\nuse serde_json::json;\nuse thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum AppError {\n    #[error("database error: {0}")]\n    Database(#[from] sqlx::Error),\n    #[error("not found")]\n    NotFound,\n    #[error(transparent)]\n    Other(#[from] anyhow::Error),\n}\n\nimpl IntoResponse for AppError {\n    fn into_response(self) -> Response {\n        let (status, message) = match &self {\n            AppError::NotFound => (\n                StatusCode::NOT_FOUND,\n                "not found".to_string(),\n            ),\n            AppError::Database(sqlx::Error::RowNotFound) => (\n                StatusCode::NOT_FOUND,\n                "not found".to_string(),\n            ),\n            _ => {\n                tracing::error!(error = ?self, "request failed");\n                (\n                    StatusCode::INTERNAL_SERVER_ERROR,\n                    "internal error".to_string(),\n                )\n            }\n        };\n        (status, Json(json!({ "error": message }))).into_response()\n    }\n}\n<\/code><\/pre>\n
Now every handler returns Result<T, AppError><\/code> and the ?<\/code> operator does the heavy lifting. The #[from] sqlx::Error<\/code> is the trick. It auto-converts pool failures, deserialization errors, the lot. Pair this with tower_http::trace::TraceLayer<\/code> and you get structured error logs without thinking about it.<\/p>\n
This pattern came from the axum examples repo<\/a>, which I should have read on day one instead of day fourteen.<\/p>\n
Middleware and tracing, in two minutes<\/h2>\n
I add three layers to almost every service: a request timeout, a tracing layer, and CORS if the service talks to a browser.<\/p>\n
use tower_http::{\n    trace::TraceLayer,\n    timeout::TimeoutLayer,\n    cors::CorsLayer,\n};\nuse std::time::Duration;\n\nlet app = Router::new()\n    .route("\/users", get(list_users))\n    .layer(TimeoutLayer::new(Duration::from_secs(10)))\n    .layer(TraceLayer::new_for_http())\n    .layer(CorsLayer::permissive()) \/\/ tighten in prod\n    .with_state(state);\n<\/code><\/pre>\n
CorsLayer::permissive<\/code> is fine for a local dev demo and a horrible idea anywhere else. Set explicit origins before you ship. I have shipped permissive CORS once. I will not be doing that again.<\/p>\n
For tracing, set RUST_LOG=info,sqlx=warn<\/code> in your environment. sqlx’s query logs at debug level are noisy enough to drown out anything useful. The EnvFilter<\/code> from tracing-subscriber<\/code> reads that variable and Just Works.<\/p>\n
Testing against a real database<\/h2>\n
I used to mock the database client. Every single time, my tests went green and production blew up on a constraint I’d forgotten to mirror in the mock. Now I run integration tests against a real Postgres in Docker.<\/p>\n
#[sqlx::test]\nasync fn list_users_returns_seeded_users(pool: PgPool) {\n    sqlx::query!("INSERT INTO users (id, email) VALUES ($1, $2)",\n        uuid::Uuid::new_v4(), "test@example.com")\n        .execute(&pool).await.unwrap();\n\n    let users = repo::list_users(&pool).await.unwrap();\n    assert_eq!(users.len(), 1);\n}\n<\/code><\/pre>\n
The #[sqlx::test]<\/code> macro spins up a fresh database per test, runs your migrations, and hands you a pool. It’s the most underrated feature in the whole library. I’d been hand-rolling test harnesses for a year before I noticed it existed.<\/p>\n
What I’d do differently on the next service<\/h2>\n
A few things I’d skip the rituals on. I’d reach for sqlx’s migration runner immediately instead of writing my own. I’d put a make dev<\/code> target in the Makefile from day one that spins up Postgres in Docker, runs migrations, and starts the service with cargo watch -x run<\/code>. And I’d wire up tower_http::trace<\/code> before I write the second handler, because debugging a Rust service without structured request logs is its own special kind of pain.<\/p>\n
If you want to see the kind of stuff I build with this stack, I keep a few projects on my portfolio<\/a>. Most have a Rust service somewhere in the backend.<\/p>\n
One thing to try this week<\/h2>\n
Pick the smallest internal tool you have. A status endpoint or a webhook receiver. Rewrite it as an axum + sqlx service. You’ll hit every pattern in this post in about three hours, the borrow checker will yell at you twice, and at the end you’ll have a binary that uses 12 megabytes of RAM. That’s the point Rust on the backend starts feeling reasonable instead of academic.<\/p>\n","protected":false},"excerpt":{"rendered":"
I picked axum for a Rust service and spent a weekend on basics nobody documents. Here’s the axum + sqlx production setup I actually ship, with real code.<\/p>\n","protected":false},"author":2,"featured_media":389,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"I picked axum for a Rust service and spent a weekend on basics nobody documents. Here's the axum + sqlx production setup I actually ship, with real code.","rank_math_focus_keyword":"axum rust","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[147,142],"tags":[117,49,64,419,176,418],"class_list":["post-390","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-backend","category-rust","tag-axum","tag-backend","tag-rust","tag-rust-web","tag-sqlx","tag-tokio"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/390","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=390"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/390\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/389"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=390"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=390"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=390"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}