Cursor Rules Template: Multi-Tenant SaaS DB Isolation (Cursor AI)

Overview

Cursor AI configuration for a multi-tenant SaaS with database isolation using PostgreSQL schemas. This Cursor rules template targets a Python FastAPI stack with SQLAlchemy 2.0 and JWT-based tenant context. It provides concrete guidance for per-tenant data boundaries, secure access, and reliable migrations. Direct answer: paste the .cursorrules block below to establish a reusable, auditable baseline for per-tenant isolation and safe AI-assisted development.

Overview answer: This template defines tenant-resolved context, per-request schema switching, and strict isolation guarantees so Cursor AI can reason about data access without cross-tenant leakage.

When to Use These Cursor Rules

• Starting a new multi-tenant SaaS project requiring strong data isolation between tenants.
• Implementing per-tenant PostgreSQL schema isolation with per-request tenant resolution.
• Using Cursor AI to guide secure data access, migrations, and testing in a multi-tenant stack.
• Enforcing a consistent code style and deployment workflow across tenant boundaries.
• Auditing tenant context in all ORM queries and raw SQL paths.

Copyable .cursorrules Configuration

frameworkRole: Senior Backend Engineer for multi-tenant SaaS with schema-per-tenant isolation in PostgreSQL
frameworkContext: Cursor AI assists Python FastAPI + SQLAlchemy 2.0 stack. Enforce per-tenant data boundaries, per-request tenant context, and safe SQL generation.
codeStyleGuides: Black, isort, mypy
architectureRules:
  - apps/
  - tenants/
  - infra/
  - migrations/
  - tests/
authenticationSecurity:
  scheme: OAuth2 with JWT
  tenantIsolation: per-request tenant context; tenantId from JWT; enforce in all queries
dbAndOrm:
  orm: SQLAlchemy 2.0
  databasePattern: schema-per-tenant; set search_path per request; per-tenant migrations
testingAndLinting:
  unitTests: pytest
  integrationTests: pytest with isolated databases per tenant
  linting: mypy, black, ruff
pipelines:
  ci: GitHub Actions
prohibitedActions:
  - Do not access or expose data across tenants without explicit tenant context
  - Do not bypass schema switching or rely on global search_path changes without audit
  - Do not construct dynamic SQL without parameterization and validation

Recommended Project Structure

project/
├── app/
│   ├── api/
│   ├── models/
│   ├── schemas/
│   ├── db/
│   │   ├── connections.py
│   │   └── migrations/
│   ├── tenancy.py
│   └── main.py
├── tenants/
│   ├── schemas/
│   └── migrations/
├── infra/
├── tests/
└── config/

Core Engineering Principles

• Strict tenant boundary enforcement in all data access paths
• Per-tenant migrations with audit trails
• Request-scoped tenant context and hardened ORM queries
• Explicit database connection handling with safe rollbacks
• Automated testing across tenant contexts and environments
• Cursor AI usage that reinforces safe, auditable development patterns

Code Construction Rules

• Always derive tenant from the request and do not proceed if missing
• Prefer parameterized queries; never interpolate tenant IDs into SQL strings
• Switch PostgreSQL search_path per request within a transaction boundary
• Validate inputs and model schemas with Pydantic; fail closed on invalid data
• Use migrations that are tenant-aware and reversible
• Do not bypass ORM-level filters that enforce tenant isolation

Security and Production Rules

• Enforce least privilege DB roles per tenant
• Encrypt data at rest and in transit; enable TLS for all DB and API calls
• Rotate secrets regularly; store in a vault
• Audit all schema changes per tenant; require review for migrations
• Monitor and alert on cross-tenant access attempts or anomalous queries

Testing Checklist

• Unit tests for tenant context resolution and middleware
• Integration tests with isolated in-memory or per-tenant databases
• End-to-end tests validating tenant boundaries across API layers
• Static type checks with mypy; linting with ruff
• CI checks for migrations and schema validation

Common Mistakes to Avoid

• Assuming global data access is safe in a multi-tenant environment
• Overriding tenant context in background jobs or async tasks
• Skipping per-tenant migrations or mixing tenants in a single migration
• Building raw SQL without parameterization affecting tenant data

FAQ

What is a Cursor rules template for multi-tenant DB isolation?

This Cursor rules template provides a concrete, pasteable .cursorrules block tailored for a multi-tenant SaaS with per-tenant PostgreSQL schema isolation. It defines a safe tenant context, data boundaries, and practical guidelines for security, testing, and deployments to help Cursor AI reason about multi-tenant access correctly.

Which stack does this Cursor rules template target?

This template targets a Python FastAPI stack with PostgreSQL using schema-per-tenant isolation, SQLAlchemy 2.0 as the ORM, and JWT/OAuth2 for tenant-aware authentication. It provides per-tenant migrations, tenant context handling, and testing workflows.

How do I apply the .cursorrules block in my project?

Copy the entire .cursorrules configuration from the Copyable section into a file named .cursorrules at the project root. Cursor AI will then use the rules to shape responses, validate code, and guide implementation within the designated stack.

What are the key security considerations for per-tenant DB isolation?

Maintain strict tenant boundaries, verify tenant id on every access, prefer per-tenant schemas with explicit search_path management, enforce least privilege in DB roles, rotate secrets, enable TLS, and audit schema changes with per-tenant migration tracking.

What are common mistakes to avoid in this stack?

Avoid cross-tenant data leakage by bypassing tenant context, using global migrations without per-tenant scoping, constructing dynamic SQL unsafely, and bypassing request-scoped tenant binding in ORM queries.