Tortoise ORM

Tortoise ORM is an easy-to-use, async-native Object-Relational Mapper for Python inspired by Django’s ORM. It lets you define models as Python classes, express relationships declaratively, and run non-blocking database queries against SQLite, PostgreSQL, MySQL/MariaDB, Microsoft SQL Server, and Oracle.

Designed for asyncio applications and frameworks like FastAPI, Starlette, and aiohttp, Tortoise combines a clean, chainable query API with a full field system, model signals, migrations, and pluggable database backends, so you can work with your data in high-level object-oriented code instead of hand-written SQL.

What You Get

• A declarative model layer with typed fields, relationships (FK, M2M, O2O), and model-level signals
• An async, chainable QuerySet API for filtering, ordering, aggregation, annotations, and prefetching
• Pluggable database backends for SQLite, PostgreSQL, MySQL/MariaDB, MS SQL Server, and Oracle
• Built-in schema generation and migration tooling for evolving your database over time
• First-class integration examples for FastAPI, Starlette, aiohttp, Sanic, and other async frameworks

Common Use Cases

• Backing an async web API (FastAPI/Starlette) with a relational database using non-blocking queries
• Replacing hand-written SQL with typed models and a high-level query API in asyncio services
• Modeling complex relational data with foreign keys, many-to-many links, and prefetching
• Managing schema evolution through generated migrations across multiple database engines

Under The Hood

Architecture — Tortoise is organized around a declarative model layer (tortoise/models.py, fields/) that maps Python classes to tables, a lazily-evaluated QuerySet (queryset.py, query_utils.py, expressions.py, functions.py) that builds SQL and only executes on await, and a pluggable backend layer under tortoise/backends/ where each engine (SQLite, asyncpg/psycopg for Postgres, aiomysql/asyncmy for MySQL, ODBC for MS SQL/Oracle) implements a common client and executor interface. SQL generation is delegated to the pypika-tortoise query builder, while connection.py, context.py, and transactions.py manage connection pools and transaction scope across the asyncio event loop.

Tech Stack — Pure Python (requires 3.10+) built on asyncio, with pypika-tortoise for SQL construction, aiosqlite bundled by default, and optional extras (asyncpg, psycopg, aiomysql, asyncmy, asyncodbc) pulling in database-specific async drivers. Optional acceleration via ciso8601, uvloop, and orjson. Packaging and dependency management use pyproject.toml with uv.

Code Quality — The codebase is fully type-annotated (ships a py.typed marker) and organized into clear modules (fields, filters, functions, signals, migrations, backends). It carries an extensive test suite of 63+ test modules under tests/ plus a large set of runnable examples/ covering FastAPI, aiohttp, Starlette, and complex filtering/prefetching, indicating strong coverage and maintained behavior.

API Design — The public API is deliberately Django-like: subclass Model, declare fields, and use a chainable, awaitable QuerySet (filter, annotate, prefetch_related, values). This makes the learning curve gentle for anyone with Django or SQL background, and getting started requires only a Tortoise.init config and model definitions with minimal boilerplate.