Rust Actix-Web + Diesel ORM Cursor Rules Template

Overview

Direct answer: This Cursor rules configuration provides a copyable, stack-specific .cursorrules block for Rust Actix-Web + Diesel ORM. It constrains AI-generated code and guidance to idiomatic Rust, Actix-Web handlers, Diesel ORM patterns, and secure API practices.

Cursor AI rules template for the Rust Actix-Web + Diesel ORM stack ensures the AI favors typed APIs, explicit error handling, and safe concurrency, while preserving clean architecture and testability.

When to Use These Cursor Rules

• When you want Cursor AI to generate Rust Actix-Web handlers that consistently use Diesel ORM models and PostgreSQL migrations.
• When enforcing JWT-based authentication and middleware-based security across endpoints.
• When you need a repeatable project structure aligned with Rust and Actix-Web best practices.
• When you require strict code style (rustfmt) and linting (clippy) in CI.
• When prototyping API endpoints with a safe, auditable repository pattern.

Copyable .cursorrules Configuration

// Cursor Rules Template for Rust Actix-Web + Diesel ORM
version: 1
framework: "rust"
stack: "actix-web-diesel"
frameworkRoleAndContext:
  - role: "Backend Engineer"
    context: "You're building a REST API in Rust using Actix-Web and Diesel ORM. Follow strong typing, safe concurrency, and explicit error handling."
codeStyleAndGuides:
  - "rustfmt"
  - "clippy"
  - "documentation: rustdoc"
architectureAndDirectoryRules:
  - "src/api/handlers"
  - "src/core"
  - "src/db"
  - "src/repositories"
  - "src/utils"
authenticationAndSecurityRules:
  - "JWT-based authentication middleware"
  - "HTTPS in production, CORS, CSRF when applicable"
databaseAndORMPatterns:
  - "Diesel ORM with PostgreSQL"
  - "connection pooling with r2d2"
  - "diesel migrations and schema.rs usage"
testingAndLintingWorkflows:
  - "cargo test"
  - "cargo test -- --nocapture"
  - "cargo clippy"
  - "cargo fmt -- --check"
prohibitedActionsAndAntiPatterns:
  - "Do not use unsafe blocks unless strictly necessary"
  - "Do not bypass input validation"
  - "Do not access DB outside repository layer"

Recommended Project Structure

project-root/
├── Cargo.toml
├── src/
│   ├── api/
│   │   └── handlers.rs
│   ├── core/
│   │   └── models.rs
│   ├── db/
│   │   ├── mod.rs
│   │   ├── schema.rs
│   │   └── migrations/
│   ├── repositories/
│   │   └── user_repo.rs
│   └── main.rs
└── migrations/

Core Engineering Principles

• Type safety as a primary design principle: leverage Rust's strong typing for API payloads and database models.
• Explicit error handling and clear boundaries between layers: API, service, and repository layers.
• Small, testable units with deterministic behavior and easy mocking for Cursor AI guidance.
• Idempotent handlers and safe concurrency through Actix-Web's actor model and Rust concurrency guarantees.
• Configuration via environment variables with explicit defaults and documented schemas.

Code Construction Rules

• Define a project state in AppState with a Diesel connection pool and pass it to handlers.
• Use Diesel ORM for all data access; avoid raw SQL outside migrations and repository layer.
• Validate all input with strong types and serde deserialization safeguards.
• Return consistent JSON error shapes and proper HTTP status codes.
• Follow rustfmt and Clippy recommendations in CI; document public APIs with rustdoc.
• Do not mix ORM models with domain logic; keep repository translation explicit.

Security and Production Rules

• Use JWT-based authentication middleware and role checks for protected endpoints.
• Enforce TLS in production, implement CORS with strict origins, and rotate secrets via environment stores.
• Guard against SQL injection via Diesel parameterization; avoid dynamic SQL strings.
• Validate inputs thoroughly and return safe, non-leaking error messages.
• Lease DB credentials with least privilege and rotate credentials periodically.

Testing Checklist

• Unit tests for core business logic and validators.
• Integration tests for Actix-Web handlers using actix_web::test.
• Database integration tests against a test PostgreSQL instance.
• CI steps: cargo fmt -- --check, cargo clippy, cargo test.
• End-to-end tests to validate authentication flows.

Common Mistakes to Avoid

• Using unsafe blocks without necessity; prefer safe abstractions.
• Skipping input validation or returning generic errors to clients.
• Mixing domain logic with persistence concerns in handlers.
• Hard-coding secrets or credentials in source code.

FAQ

What is this Cursor Rules Template for Rust Actix-Web + Diesel ORM?

This template provides a copyable .cursorrules configuration and stack-specific rules to guide Cursor AI when generating code for a Rust API built on Actix-Web with Diesel ORM.

Which stack does this template cover?

It targets Rust, Actix-Web for HTTP, and Diesel ORM for PostgreSQL integrations, with JWT-based authentication and secure API design.

How do I use the .cursorrules block?

Place the copyable block at the project root as .cursorrules. Cursor AI will read Stack, Roles, and rules to constrain code generation and AI-assisted edits.

How should I structure tests for this stack?

Include unit tests for business logic, integration tests for handlers, and CI steps to run cargo fmt, cargo clippy, and cargo test on PRs.

Can I adapt this for other ORM stacks?

Yes, you can adapt the rules by swapping the ORM section and migration patterns, keeping security and testing rules aligned to Rust conventions.