Cursor Rules Template: FastAPI + Tortoise ORM + Aerich + PostgreSQL

Overview

This Cursor rules configuration provides a concrete, copyable .cursorrules block for building a FastAPI application with Tortoise ORM, Aerich migrations, and PostgreSQL. It defines the role of the model layer, code style, architecture, security, and testing patterns to keep AI-assisted development aligned with best practices for this stack.

When to Use These Cursor Rules

• Starting a FastAPI project that uses Tortoise ORM for async ORM operations.
• Using Aerich to manage PostgreSQL migrations in a safe, versioned way.
• Seeking a ready-to-paste instruction block to guide AI during code generation and reviews.
• Ensuring secure DB access patterns and clean project structure from the outset.

Copyable .cursorrules Configuration

# Cursor rules template for FastAPI + Tortoise ORM + Aerich + PostgreSQL
# Framework Role & Context
framework: fastapi
stack: fastapi-tortoise-aerich-postgres
python_version: 3.11
environment: production
# Code Style and Style Guides
lint: true
lintTool: ruff
formatter: black
typeCheck: true
# Architecture & Directory Rules
rootDir: "/"
modules:
  - app
  - config
  - migrations
  - tests
  - tests e2e
# Authentication & Security Rules
auth:
  type: oauth2_password_bearer
  tokenUrl: "/auth/token"
security:
  httpsOnly: true
  corsOrigins: ["https://*.example.com"]
# Database and ORM patterns
database:
  engine: "postgres"
  url: "postgresql+asyncpg://user:pass@host:5432/dbname"
orm:
  modelModule: "app.models"
  migrate: true
  migrations: "migrations"
# Testing & Linting Workflows
testing:
  pytest: true
  asyncio: true
ci:
  workflow: "pytest && mypy"
# Prohibited Actions and Anti-patterns
doNot:
  - "Use raw SQL without parameters"
  - "Mix synchronous DB calls in async endpoints"
  - "Store credentials in code"
  - "Skip migrations"
# End of config

Recommended Project Structure

/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── v1/
│   │       └── endpoints/
│   ├── models/
│   ├── services/
│   ├── config/
│   ├── migrations/
│   │   └── versions/
│   └── tests/
├── config/
├── migrations/
└── tests/

Core Engineering Principles

• Async-first design with proper awaitables and event loops in FastAPI.
• Explicit migrations and versioned database changes with Aerich.
• Clear separation of concerns between API, service, and data layers.
• Type-safe boundaries using Pydantic models for requests and responses.
• Defensive security: TLS, strict CORS, and credential handling.
• Reliable tests: unit, integration, and end-to-end checks with CI.

Code Construction Rules

• Define ORM models with clear table names, indexes, and constraints in app/models.
• Use Aerich for migrations; never edit DB schema outside migrations.
• Endpoints must be async; avoid blocking calls in request handlers.
• Parameterize all raw queries; prefer ORM methods or parameterized SQL.
• Consistent naming: snake_case for Python, kebab-case for URLs.
• Use dependency injection for configs and DB sessions.
• Hash and salt passwords with a strong algorithm; never store plain passwords.
• Write tests that exercise async paths and migrations.

Security and Production Rules

• Enable TLS, enforce HTTPS, and configure secure cookies and headers.
• Limit CORS to trusted origins and use CSRF protection for state-changing calls.
• Store secrets in environment variables or a secret manager; avoid hard-coding.
• Rotate JWT keys and validate token claims on each protected endpoint.
• Use database connection pools and sensible timeouts; enable SSL for Postgres.

Testing Checklist

• Unit tests for models and utilities; mock DB where possible.
• Integration tests for API endpoints with a real Postgres container.
• Migration tests that apply and roll back Aerich migrations in CI.
• Lint and type-check in CI; run pytest with async support.
• End-to-end tests for critical flows if feasible.

Common Mistakes to Avoid

• Relying on synchronous ORM paths in async routes.
• Skipping migrations or altering DB schema manually.
• Hard-coding credentials or secrets in code.
• Overcomplicating dependency graphs and circular imports.
• Neglecting tests for migrations and edge cases.

FAQ

What is this Cursor Rules Template for?

This template provides a concrete, ready-to-use set of Cursor AI rules for a FastAPI project using Tortoise ORM, Aerich migrations, and PostgreSQL. Paste the .cursorrules block into your repo to ensure consistent AI guidance and coding standards.

Which stack does it cover?

It covers FastAPI as the web framework, Tortoise ORM for async data access, Aerich for migrations, and PostgreSQL as the database. The rules emphasize safe async patterns, migrations, and secure configuration.

How do I use the .cursorrules block?

Copy the block to your project root as .cursorrules, adjust environment variables (DB URLs, secrets), and let Cursor AI guide code generation and reviews in line with the rules.

Can I adapt this to other databases or ORMs?

You can adapt by editing the database engine and ORM sections to match your stack while preserving the same structure for roles, architecture, and security guidelines.

What tests should I add?

Unit tests for models and services, integration tests for API endpoints against a real Postgres database, and migration tests to verify Aerich migrations can be applied and rolled back cleanly.