GO — Healthy across the board

• Last commit 4d ago
• 22+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard}

Tortoise ORM is an asyncio-native Object-Relational Mapper for Python inspired by Django, providing a high-level, async-first API for querying SQLite, PostgreSQL, MySQL, MS SQL, and Oracle databases. It eliminates raw SQL boilerplate by letting developers work with Python objects and relationships, with a focus on performance benchmarked against competing Python ORMs. Monolithic single-package structure rooted at tortoise/ containing the ORM core, with docs/ holding Sphinx documentation including database-specific guides (docs/contrib/postgres.rst, docs/contrib/mysql.rst, etc.) and example integrations (docs/examples/fastapi.rst, docs/examples/sanic.rst). Workflows in .github/workflows/ drive CI, PyPI publishing, and documentation deployment.

Python async/await developers (particularly those familiar with Django ORM) who need to interact with relational databases in async applications—common in FastAPI, Sanic, Starlette, and other async web frameworks. Contributors are maintainers of the tortoise organization and community members extending support for additional databases and integrations.

Production-ready and actively maintained. The repository has comprehensive CI/CD workflows (GitHub Actions for testing, PyPI releases, documentation), supports CPython 3.10+, and maintains detailed changelog and contributor documentation. Regular releases, benchmarking infrastructure, and broad database support indicate stable maturity.

Low risk for critical production use due to active maintenance and test coverage, but moderate maintenance burden given support for 5+ database engines with multiple async drivers (asyncpg, aiomysql, asyncmy, psycopg, asyncodbc). The responsibility for tracking breaking changes across major database client library updates falls on maintainers; users should monitor CHANGELOG.rst and CI status closely.

Active development focused on database compatibility and framework integrations—indicated by multiple workflow files for continuous testing (ci.yml), performance benchmarking (codspeed.yml), and automated documentation publishing (gh-pages.yml). The presence of contrib docs for multiple frameworks (FastAPI, Sanic, Quart, Starlette, BlackSheep) and CHANGELOG.rst suggest ongoing feature additions and bug fixes.

git clone https://github.com/tortoise/tortoise-orm.git && cd tortoise-orm && pip install -e . && make test (Makefile present for common tasks). For database-specific setup, install extras: pip install tortoise-orm[asyncpg] for PostgreSQL or pip install tortoise-orm[aiomysql] for MySQL.

Daily commands: make test (from Makefile) runs the test suite. For development: pytest with conftest.py configuration (present at root). No dev server—this is a library. Documentation builds with make -C docs html.

• tortoise — Root package directory containing all ORM core modules
• README.rst — Project overview explaining asyncio ORM purpose and supported databases
• conftest.py — Pytest configuration and test fixtures for the entire test suite
• .github/workflows/ci.yml — CI/CD pipeline defining test execution across CPython 3.10+ and multiple databases
• docs/models.rst — Core documentation on defining ORM models, fields, and relationships
• docs/query.rst — Query API documentation explaining filtering, ordering, and async operations
• examples/basic.py — Minimal working example demonstrating model definition and basic CRUD operations

• Model (Python class with field descriptors) — Defines schema, relationships, and instance state; serves as data entity
  • Failure mode: Invalid field definitions or circular relations cause schema validation errors at init time
• QuerySet (async/await with expression tree evaluation) — Lazy-evaluated async query builder; chains filters, orderings, and aggregations
  • Failure mode: Malformed query expressions or missing await cause syntax or runtime errors
• SQL Backend (Database driver (asyncpg, aiomysql, aiosqlite)) — Translates QuerySet to database-specific SQL and executes async queries
  • Failure mode: Unsupported query patterns or connection pool exhaustion cause query failures
• Relationship Manager (Lazy loading with explicit join queries) — Handles ForeignKey, ManyToMany, and reverse relations; provides prefetch_related()
  • Failure mode: Missing prefetch_related() on related collections causes N+1 query overhead
• Signal System (Event emitter with decorator registration) — Dispatches lifecycle hooks (pre_save, post_delete) to registered handlers
  • Failure mode: Unhandled exceptions in signal handlers can silently skip event listeners
• Migration Engine (Aerich CLI with migration file versioning) — Generates and applies versioned schema changes to database
  • Failure mode: Failed migration rollback can leave database in inconsistent state
• Framework Integrations (Framework hooks (startup/shutdown events)) — Lifespan management and request-scope connection handling for FastAPI, Aiohttp, etc.
  • Failure mode: Incorrect lifespan setup causes connection leaks or premature pool closure

• Application → QuerySet — User calls async methods like await Model.filter(...).values() to construct lazy queries
• QuerySet → SQL Backend — Query execution triggers SQL generation and sends compiled statement to database driver
• SQL Backend → Database — Driver executes async SQL and returns raw row data from disk or connection pool
• Database → SQL Backend — Rows are deserialized and converted to ORM model instances with field type coercion
• SQL Backend → Signal System — On model save/delete, pre and post lifecycle signals are dispatched to registered handlers
• Signal System → Application — Handlers execute business logic (validation, audit logs) before/after persistence

Add a new Model with Relations

1. Define a new model class inheriting from tortoise.Model in your models.py (examples/basic.py)
2. Declare fields using tortoise field types (IntField, CharField, ForeignKeyField) as class attributes (tortoise/fields.py)
3. Set Meta class with table name and app label, then register with Tortoise.init() (tortoise/models.py)

Perform Advanced Async Queries

1. Use QuerySet methods like .filter(), .get(), .all() chained with .await (tortoise/queryset.py)
2. Build complex filters using Q objects from tortoise.expressions (tortoise/expressions.py)
3. Apply aggregation with functions from tortoise.functions (Count, Sum, Avg) (tortoise/functions.py)

Integrate with FastAPI or Another Framework

1. Import the framework adapter (e.g., tortoise.contrib.fastapi.register_tortoise) (tortoise/contrib/fastapi.py)
2. Call register_tortoise() in app startup with db_url and models module (examples/fastapi)
3. Use signal decorators (@pre_save, @post_delete) if lifecycle hooks needed (tortoise/signals.py)

Generate and Run Database Migrations

1. Use aerich CLI or tortoise-migrate to generate migration files from schema changes (tortoise/contrib/migrate.py)
2. Review auto-generated migration file, then apply via .upgrade() (examples/comprehensive_migrations_project/migrations)
3. Ensure migration files are committed and applied before production deployment (.github/workflows/ci.yml)

• asyncio — Enables non-blocking database operations and concurrent request handling in async frameworks
• Multiple database backends (SQLite, PostgreSQL, MySQL, MSSQL, Oracle) — Provides flexibility for developers to choose database engines without rewriting ORM code
• Signal/hook system — Decouples business logic from ORM lifecycle events (pre_save, post_delete) for clean architecture
• Pydantic integration — Bridges ORM models with validation and serialization without manual conversions

• Async-only design (no sync API)

  • Why: Forces developers into async patterns early; prevents blocking database calls
  • Consequence: Incompatible with sync-only frameworks; steep learning curve for Django developers

• Lazy relationship loading deferred to explicit prefetch_related()

  • Why: Prevents N+1 query problems by making relationships explicit
  • Consequence: Requires conscious query optimization; no automatic relationship fetching

• SQL generation per-backend

  • Why: Allows database-specific optimizations and features
  • Consequence: More code to maintain; subtle differences between backends may emerge

• Migration system separate from ORM core (Aerich)

  • Why: Decouples schema versioning from runtime ORM
  • Consequence: Adds external dependency; users must learn separate migration tool

• Does not provide synchronous API—entirely async-first
• Does not auto-generate migrations from model changes—manual or Aerich-based
• Does not include built-in authentication or authorization
• Does not support real-time subscriptions or reactive queries
• Does not provide GraphQL query layer—must be integrated separately

• Avg cyclomatic complexity: ~6.5 — ORM requires intricate query compilation, relationship resolution, and async context management; high cyclomatic complexity in backend SQL builders
• Largest file: tortoise/queryset.py (1,200 lines)
• Estimated quality issues: ~12 — Async-first design complicates error handling; signal system lacks centralized exception tracking; backend SQL builders have duplicated logic across database drivers

• Missing await on QuerySet operations (High) — tortoise/queryset.py: Developers forget to await async QuerySet methods, causing coroutine objects returned instead of data
• N+1 query problem with implicit lazy loading (High) — tortoise/manager.py, tortoise/fields.py: Accessing related objects in loops without prefetch_related() causes exponential queries
• Circular model imports (Medium) — tortoise/models.py: Models importing each other directly for type hints can cause initialization order failures
• Signal handler exceptions silently ignored (Medium) — tortoise/signals.py: Unhandled exceptions in pre_save/post_delete handlers are swallowed without logging
• Connection pool not closed on app shutdown (High) — tortoise/backends: Missing await Tortoise.close_connections() in async app shutdown causes resource leaks

• tortoise/queryset.py: .values() method (Memory allocation) — Converting large result sets to dictionaries causes memory overhead; no streaming API
• tortoise/backends: SQL query compilation per QuerySet (CPU/compilation) — Complex queries with deep joins trigger repeated SQL generation on each execute
• tortoise/manager.py: prefetch_related() implementation (Database round trips) — Prefetch executes separate queries per related collection instead of batching joins
• tortoise/transactions.py: nested transaction handling (Database overhead) — Savepoint overhead on databases with poor nested transaction support

Async database setup required: tests expect async database drivers installed (asyncpg, aiomysql, etc.) matching the DATABASE_URL environment variable. No default SQLite fallback in tests—conftest.py likely configures test DB at runtime. Multiple async driver options per database means subtle compatibility differences (e.g., asyncpg vs. psycopg for PostgreSQL). Relationship loading behavior varies by fetch strategy (FK auto-loading vs. explicit prefetch_related/select_related calls)—lazy fetches in loops cause N+1 queries. Schema migrations are delegated to external tool Aerich (not in this repo).

• Async/await database I/O — Tortoise is built entirely around asyncio—all database calls are non-blocking coroutines; understanding async context and event loops is essential to avoiding blocking calls that defeat the ORM's purpose
• Active Record pattern — Tortoise models inherit from Model and include both data and query methods (e.g., User.get(), user.save()); this differs from Data Mapper pattern—knowing the pattern clarifies method placement expectations
• Foreign key lazy-loading and N+1 query problem — By default, accessing related objects (e.g., post.author) triggers additional queries; understanding prefetch_related() and select_related() is critical to writing performant queries in production
• Object-Relational Impedance Mismatch — Tortoise abstracts relational joins and schemas into Python objects; recognizing where this abstraction leaks (e.g., raw SQL for complex aggregations) helps decide when to bypass the ORM
• Connection pooling in async contexts — Tortoise manages database connection pools for concurrent requests; misconfigured pool sizes or connection lifecycle handling can cause hangs or resource exhaustion under load—critical for scaling async apps
• Type hints and runtime schema validation — Tortoise fields use type annotations (IntField, CharField, ForeignKeyField) to both declare schema and enable static type checking; the dual nature requires understanding how runtime Field instances map to Python types
• Query Builder and Expression Trees — Tortoise constructs SQL dynamically via method chaining (e.g., User.filter(age__gte=18).order_by('-created_at')); understanding how filter lookups and Q objects build AST-like trees helps debug complex queries

• encode/orm — Lightweight async ORM alternative (Encode's orm) with similar asyncio-first design; competitive comparison for async database abstraction
• sqlalchemy/sqlalchemy — Industry-standard Python ORM with SQLAlchemy 2.0 async support; reference implementation for relationship patterns and query building
• tiangolo/sqlmodel — Built on SQLAlchemy + Pydantic, bridges ORM models and API validation; complementary to Tortoise for FastAPI projects needing schema serialization
• tortoise/aerich — Official migration tool for Tortoise ORM, separate repo managing schema versioning and migrations (essential companion for production deployments)
• django/django — Original inspiration for Tortoise ORM's API design and philosophy; Django ORM patterns directly inform relationship handling and query syntax

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for contrib modules

The repo has extensive contrib integrations (aiohttp, fastapi, starlette, sanic, quart, blacksheep, pydantic, mysql, postgres, unittest) documented in docs/contrib/ but there's no evidence of dedicated test suites for each. A new contributor could create a test_contrib/ directory with integration tests for each framework to ensure compatibility and catch regressions early.

• [ ] Create tests/contrib/ directory structure mirroring docs/contrib/
• [ ] Add test_fastapi.py with integration tests for FastAPI initialization and middleware
• [ ] Add test_aiohttp.py with integration tests for aiohttp setup and signal handling
• [ ] Add test_pydantic.py validating Pydantic model serialization with Tortoise models
• [ ] Update CI workflow to run contrib tests separately or in dedicated job
• [ ] Document how to run contrib tests in CONTRIBUTING.rst

Implement comprehensive CLI command tests and examples

docs/cli.rst documents CLI functionality but there's no evidence of dedicated CLI test coverage or examples. The tortoise.cli module likely has untested code paths. A contributor could add tests/test_cli.py with fixtures for testing init, migrate, and other CLI commands.

• [ ] Create tests/test_cli.py with fixtures for temporary databases and config files
• [ ] Add test cases for 'tortoise-orm init' command with various project types
• [ ] Add test cases for 'tortoise-orm migrate' with version control scenarios
• [ ] Add test cases for CLI error handling (invalid configs, missing databases)
• [ ] Create docs/examples/cli_usage.rst with real-world CLI examples
• [ ] Verify CLI tests run in CI workflow

Add missing signal/event hook tests and documentation

docs/signals.rst documents signal functionality, but signal implementation likely lacks comprehensive test coverage for edge cases and integration scenarios. A contributor could create tests/test_signals.py validating all signal hooks (pre_save, post_save, pre_delete, post_delete) with async/await edge cases.

• [ ] Create tests/test_signals.py with fixtures for model lifecycle tracking
• [ ] Add tests for signal execution order with multiple handlers
• [ ] Add tests for signal exception handling and rollback scenarios
• [ ] Add tests for signal behavior with transactions and batch operations
• [ ] Create docs/examples/signals_advanced.rst documenting signal best practices
• [ ] Add type hints validation for signal callbacks in tests

• Add async context manager tests for connection pooling scenarios in tortoise/backends/ to cover connection lifecycle edge cases not yet documented in tests/
• Expand docs/contrib/linters.rst with mypy and pyright configuration snippets for Tortoise model type checking, addressing missing static analysis guidance for async model relationships
• Implement missing database driver error mapping in tortoise/backends/ to standardize exception handling across PostgreSQL (asyncpg/psycopg), MySQL (aiomysql/asyncmy), and MS SQL (asyncodbc) for constraint violation detection

Tortoise ORM appears to be a well-maintained asyncio ORM with good structural practices. The primary security concerns are: (1) lack of visible dependency pinning information, (2) potential SQL injection risks in direct query support that needs explicit documentation, (3) missing asyncio-specific security guidance, and (4) absence of a formal security reporting policy. The framework likely implements parameterized queries (standard ORM practice) but documentation and examples should more prominently emphasize secure coding patterns. No hardcoded credentials, exposed ports, or critical misconfigurations were identified from the provided file structure.

• Medium · Potential SQL Injection in ORM Query Construction — docs/direct_queries.rst, tortoise/tortoise-orm codebase. As an ORM that constructs SQL queries, Tortoise ORM could be vulnerable to SQL injection if user input is not properly parameterized. While ORMs typically mitigate this through parameterized queries, the presence of 'direct_queries.rst' documentation suggests raw SQL query support which may bypass ORM protections if misused. Fix: Ensure all direct SQL query APIs enforce parameterized queries and use prepared statements. Add prominent security warnings in documentation about avoiding string concatenation for dynamic SQL.
• Medium · Missing Dependency Pinning Information — Repository root (dependencies/packaging files). No 'requirements.txt', 'setup.py', 'pyproject.toml', or 'poetry.lock' file was provided in the analysis. Without visibility into pinned dependency versions, there is a risk of vulnerable transitive dependencies being installed without explicit version constraints. Fix: Provide and maintain a complete dependency manifest with pinned versions. Use tools like 'pip-audit' or 'safety' in CI/CD to scan for known vulnerable dependencies.
• Medium · Asyncio ORM without Visible Async Security Considerations — docs/ (general security documentation). Tortoise ORM is built on asyncio. Asyncio applications can be vulnerable to timing attacks, race conditions, and improper connection pool management if not handled carefully. No visible security documentation about async-specific concerns was found. Fix: Add documentation covering asyncio security best practices, connection pool limits, timeout configurations, and protection against timing-based attacks.
• Low · No Visible Security Policy — Repository root. No SECURITY.md or security policy file was found in the repository structure, making it unclear how to report security vulnerabilities responsibly. Fix: Create a SECURITY.md file in the root directory documenting the security reporting process and expected response times.
• Low · Examples Directory Without Input Validation Emphasis — examples/ directory. Multiple example files exist (aiohttp, fastapi, sanic, starlette) but there is no visible emphasis on input validation and sanitization patterns in the example code structure. Fix: Ensure example applications demonstrate proper input validation, output encoding, and security best practices for web framework integrations.
• Low · Missing Security Headers Documentation — docs/contrib/ directory. Framework integration documentation (FastAPI, Aiohttp, Sanic, Starlette) is present, but no explicit guidance on security headers configuration was identified. Fix: Add security-focused documentation for each framework integration covering CORS, CSRF, security headers, and authentication patterns.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tortoise/tortoise-orm shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tortoise/tortoise-orm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tortoise/tortoise-orm.

What it runs against: a local clone of tortoise/tortoise-orm — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tortoise/tortoise-orm | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tortoise/tortoise-orm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tortoise/tortoise-orm.git
#   cd tortoise-orm
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tortoise/tortoise-orm and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tortoise/tortoise-orm(\\.git)?\\b" \\
  && ok "origin remote is tortoise/tortoise-orm" \\
  || miss "origin remote is not tortoise/tortoise-orm (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "tortoise" \\
  && ok "tortoise" \\
  || miss "missing critical file: tortoise"
test -f "README.rst" \\
  && ok "README.rst" \\
  || miss "missing critical file: README.rst"
test -f "conftest.py" \\
  && ok "conftest.py" \\
  || miss "missing critical file: conftest.py"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "docs/models.rst" \\
  && ok "docs/models.rst" \\
  || miss "missing critical file: docs/models.rst"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tortoise/tortoise-orm"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.