Cursor Rules Template: Rust Axum + Tokio + SQLx + Postgres

Overview

Direct answer: This Cursor Rules Template provides a copyable .cursorrules block and stack-specific guidance for Rust Axum services using Tokio for async runtime, SQLx for Postgres access, and a Postgres database. It includes architecture, auth, queries, tests, and safe AI usage to streamline Cursor AI assisted development.

The page also includes a ready-to-paste instruction block and stack-specific recommendations so you can drop it in your project root and start implementing

When to Use These Cursor Rules

• When starting a new Rust Axum API with Postgres
• When enforcing a consistent architecture with SQLx and PgPool
• When you want a copyable .cursorrules block for CI friendly development
• When securing endpoints with JWT based auth and proper error handling
• When you need an agreed project structure and testing workflow

Copyable .cursorrules Configuration

.cursorrules framework rust stack axum tokio sqlx postgres roleContext You are a senior Rust backend engineer building a production API using Axum and SQLx with Postgres. Your tasks include implementing endpoints, DB access, auth, and tests following Cursor AI guidelines. codeStyle rustfmt cargo-clippy architectureAndDirectoryRules projectRoot . src modules api db models services routes migrations tests authenticationAndSecurity auth JWT in Authorization header secureDefaults true secretFromEnv true databaseAndORM database Postgres orm sqlx pool PgPool migrations sqlx migrate run queries use query! or query_as! or query_scalar for compile-time checks testingAndLinting unitTests cargo test --lib integrationTests cargo test --tests lint cargo clippy --all-targets --all-features prohibitedActionsAndAntiPatterns Do not concatenate raw SQL strings without parameters. Do not bypass authentication. Do not use unsafe code without justification. Do not skip migrations or tests in CI. Do not rely on TLS disabled DB connections.

Recommended Project Structure

project/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── api/
│   │   ├── mod.rs
│   │   └── routes.rs
│   ├── db/
│   │   ├── mod.rs
│   │   └── postgres.rs
│   └── models/
├── migrations/
│   └── 0001_initial.sql
└── tests/

Core Engineering Principles

• Explicit dependencies and strong typing to catch issues at compile time
• Clear separation of concerns between API, DB, and domain logic
• Safe AI guidance with explicit prohibitions and anti patterns
• Test driven development with unit and integration tests
• Continuous linting and formatting with rustfmt and cargo clippy

Code Construction Rules

• Use Axum extractors to parse requests and typed route handlers
• Leverage SQLx macros for compile time checked queries
• Recycle PgPool connections; prefer per-request extractors for queries
• Prefer explicit error types and map errors to HTTP responses
• Do not unwrap in production code; propagate errors
• Keep business logic in services layer, not in handlers

Security and Production Rules

• All DB connections use TLS; configure TLS in Postgres and client
• Validate and sanitize inputs; avoid dynamic SQL with string concatenation
• Store secrets in environment variables; load at startup
• Enforce JWT based authentication and proper authorization for endpoints
• Enable structured logging and tracing for production debugging

Testing Checklist

• Unit tests for isolated components
• Integration tests for API endpoints and DB interactions
• Migration tests to ensure DB compatibility
• CI job to run cargo test and cargo clippy
• Lint checks and rustfmt formatting as part of PR checks

Common Mistakes to Avoid

• Relying on unwraps in production code
• Embedding raw SQL strings without parameters
• Neglecting TLS in DB connections
• Skipping migrations in CI or local development
• Non deterministic error handling returns

FAQ

What is this Cursor Rules Template for Rust Axum?

This Cursor Rules Template provides a copyable .cursorrules block and stack specific guidance for building a Rust API using Axum, Tokio, SQLx, and PostgreSQL. It defines architecture, security, testing, and anti patterns, enabling consistent AI assisted development.

How do I use the copyable .cursorrules block?

Place the .cursorrules block at the root of your Rust project. It covers framework role, code style, architecture, authentication, and tests. It guides the AI to generate stack aware, safe code while preventing unsafe shortcuts.

How should I structure the Rust Axum project with Postgres?

Follow a typical Axum layout: src/api for routes, src/db for DB logic and migrations, src/models for data structures, and migrations for SQLx migrations. Use PgPool and compile-time checks for queries to ensure reliability.

How do I run tests and migrations in CI?

Install sqlx-cli if needed, run cargo test for unit tests and cargo test --tests for integration tests, and sqlx migrate run for migrations in CI using a Postgres service with TLS enabled.

What anti-patterns should I avoid?

Avoid bypassing authentication, dynamic SQL without parameters, unsafe code without justification, and skipping migrations or tests in CI. Also ensure TLS is used for DB connections to protect data in transit.