STACK IT FAST
ALL RULES & SKILLS

Rust + Axum + PostgreSQL (sqlx & Tokio)

Raw .MD rust-axum-postgres
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

High-concurrency systems architecture for Rust 2024, Axum 0.8, Tokio async runtime, compile-time SQL verification with sqlx, and Tower middleware.

Rust Axum PostgreSQL sqlx Tokio Docker
CLI & AI Agent Import Verified in 4 production projects
AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/rust-axum-postgres
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
AGENTS.md·42 lines · 3.2 KB
1# Project Architecture & Guidelines (Rust + Axum + PostgreSQL)
2
3## 1. System Architecture
4- **Language & Edition**: Rust (2021 / 2024 edition, stable compiler).
5- **Async Runtime**: Tokio (`tokio = { version = "1", features = ["full"] }`).
6- **Web Framework**: Axum 0.8 with Tower service ecosystem.
7- **Database & Persistence**: PostgreSQL accessed via `sqlx` (`sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "uuid", "chrono"] }`).
8- **Serialization**: `serde` and `serde_json`.
9
10## 2. Project Layout & Modular Separation
11- `src/main.rs`: Runtime initialization, configuration loading, database pool creation, and router binding.
12- `src/routes/`: Route handlers split by resource domain (e.g. `users.rs`, `health.rs`).
13- `src/models/`: Domain structs deriving `Serialize`, `Deserialize`, and `sqlx::FromRow`.
14- `src/db/`: Database connection pool management and migration runners (`sqlx::migrate!()`).
15- `src/error.rs`: Unified `AppError` enum implementing `axum::response::IntoResponse`.
16
17## 3. Handlers & Extractors
18- Use Axum extractors (`State(pool)`, `Json(payload)`, `Path(id)`, `Query(params)`) in strict order (body extractors last).
19- Manage application state via `axum::extract::State<Arc<AppState>>`.
20- Validate all inbound requests using validator crates or custom domain constructors (`NewUser::validate()`).
21
22## 4. Database & sqlx Compile-Time Checks
23- Favor `sqlx::query_as!` and `sqlx::query!` macros to validate SQL syntax and types against the live database at compile time.
24- Always configure connection pooling: `PgPoolOptions::new().max_connections(20).acquire_timeout(Duration::from_secs(3))`.
25- Place migrations in `migrations/` folder as sequential `.sql` files (`YYYYMMDDHHMMSS_name.sql`).
26
27## 5. Error Handling & Observability
28- Never `unwrap()` or `panic!()` in route handlers. Propagate errors with the `?` operator into custom `AppError`.
29- Implement `IntoResponse` for `AppError` to emit appropriate HTTP status codes (400, 401, 404, 500) and structured JSON bodies `{ "error": "message" }`.
30- Integrate `tracing` and `tracing-subscriber` for structured JSON logging and distributed span tracking.
31
32## 6. Testing Conventions
33- Use `#[tokio::test]` for async integration tests; spin up a real Postgres instance with `testcontainers` rather than mocking `sqlx`.
34- Run `cargo sqlx prepare` in CI to verify the offline query cache (`.sqlx/`) stays in sync with actual schema — a stale cache silently masks broken queries.
35- Test `AppError` → HTTP status mapping explicitly; a wrong status code on an error path is a common silent regression.
36- `cargo clippy -- -D warnings` treated as a test failure, not a style nit — Rust's linter catches real bugs (unused Results, needless clones).
37
38## 7. Git Workflow & PR Conventions
39- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the module, e.g. `fix(routes/users): return 404 instead of 500 on missing user`.
40- New `migrations/*.sql` files ship in the same PR as the `sqlx::query!` changes that depend on them; commit the updated `.sqlx/` cache alongside.
41- Require `cargo test`, `cargo clippy -- -D warnings`, and `cargo fmt --check` green before merge.
42- Squash-merge; never merge with `unwrap()`/`panic!()` introduced in a route handler — `?` and `AppError` only.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

Architecture Overview

High-throughput systems architecture using Rust, Axum, Tokio, and sqlx with compile-time verified database operations.

Key Advantages

  • Zero Memory Leaks & Zero GC Pauses: Memory safety guaranteed at compile time without garbage collector spikes.
  • Compile-Time Query Verification: sqlx checks SQL queries against PostgreSQL schemas during cargo build, preventing runtime syntax errors.
  • Massive Concurrency: Tokio lightweight asynchronous tasks handle tens of thousands of concurrent connections on minimal hardware.
FREQUENTLY ASKED QUESTIONS

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Why does sqlx need a .sqlx/ offline query cache?

sqlx's query_as! and query! macros connect to a live database at compile time to verify SQL syntax and types, which breaks CI environments that don't have database access. cargo sqlx prepare snapshots that verification into a .sqlx/ cache file that ships in the repo, so cargo build can compile-check queries offline using the cached metadata instead of a live connection.

Why is unwrap() banned in route handlers?

unwrap() panics the current thread on an Err or None, and in an Axum handler that means the request-handling task crashes — potentially with a raw error message leaking to the client and no structured logging around the failure. Propagating errors with the ? operator into a typed AppError that implements IntoResponse guarantees every failure path returns a consistent, controlled HTTP response instead.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills
4 FILE FORMATS Astro, Tailwind CSS

Astro SSR + Tailwind CSS + Cloudflare

Architecture rules for Astro server-side rendering, React client islands, Tailwind CSS, and Cloudflare Pages/Workers edge deployment.

5 techs Copy Rules
4 FILE FORMATS Bun, Hono

Bun + Hono + SQLite (libSQL & Drizzle ORM)

Ultra-fast edge API architecture using Bun.serve(), Hono v4, Drizzle ORM with embedded SQLite / Turso libSQL, and Zod OpenAPI validation.

6 techs Copy Rules
4 FILE FORMATS FastAPI, Python

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Production guidelines for FastAPI, Pydantic v2 validation, Async SQLAlchemy 2.0 (asyncpg), Alembic migrations, and PostgreSQL/Redis.

7 techs Copy Rules
4 FILE FORMATS Go, Echo

Go + Echo + SQLite (Embedded, Self-Hosted Tools)

Architecture guidelines for single-binary Go services using the Echo framework, embedded SQLite, and minimal-JS server-rendered UI.

4 techs Copy Rules