Tortoise ORM

Tortoise ORM is an easy-to-use asyncio ORM (Object Relational Mapper) inspired by Django.

Source & issue trackers are available at https://github.com/tortoise/tortoise-orm/

Tortoise ORM supports CPython 3.10 and later for SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.

Introduction

Why was Tortoise ORM built?

Tortoise ORM was built to provide a lightweight, async-native Object-Relational Mapper for Python with a familiar Django-like API.

Tortoise ORM performs well when compared to other Python ORMs. In our benchmarks, where we measure different read and write operations (rows/sec, more is better), its trading places with Pony ORM:

How is an ORM useful?

An Object-Relational Mapper (ORM) abstracts database interactions, allowing developers to work with databases using high-level, object-oriented code instead of raw SQL.

• Reduces boilerplate SQL, allowing faster development with cleaner, more readable code.

• Helps prevent SQL injection by using parameterized queries.

• Centralized schema and relationship definitions make code easier to manage and modify.

• Handles schema changes through version-controlled migrations.

Features

Clean, familiar Python interface

Model definitions:

from tortoise.models import Model
from tortoise import fields

class Tournament(Model):
    id = fields.IntField(primary_key=True)
    name = fields.TextField()

Operations on models, queries and complex aggregations:

# Creating a record
await Tournament.create(name='Another Tournament')

# Searching for a record
tour = await Tournament.filter(name__contains='Another').first()
print(tour.name)

# Count groups of records with a complex condition
await Tournament.annotate(
    name_prefix=Case(
        When(name__startswith="One", then="1"),
        When(name__startswith="Two", then="2"),
        default="0",
    ),
).annotate(
    count=Count(F("name_prefix")),
).group_by(
    "name_prefix"
).values("name_prefix", "count")

See Getting started for a more detailed guide.

Pluggable Database backends

Tortoise ORM currently supports the following Databases:

• PostgreSQL >= 9.4 (using asyncpg)

• SQLite (using aiosqlite)

• MySQL/MariaDB (using asyncmy)

• Microsoft SQL Server/Oracle (using asyncodbc)

And more

Tortoise ORM supports the following features:

• Composable, Django-inspired Models

• Supports relations, such as ForeignKeyField and ManyToManyField

• Supports many standard Fields

• Comprehensive Query API

• Transactions Transactions

• Supports tests frameworks, see Testing Support

• PyLint plugin

If you want to contribute, check out issues first, and then create a PR.