Introduction
Tortoise ORM is an easy-to-use asyncio ORM (Object Relational Mapper) inspired by Django.
You can find the docs at Documentation
Tortoise ORM supports CPython 3.10 and later for SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.
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. Here are our benchmarks on PostgreSQL 17, where we measure different read and write operations (rows/sec, more is better):
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.
Getting Started
Installation
The following table shows the available installation options for different databases (note that there are multiple options of clients for some databases):
Database |
Installation Command |
|---|---|
SQLite |
pip install tortoise-orm |
PostgreSQL (psycopg) |
pip install tortoise-orm[psycopg] |
PostgreSQL (asyncpg) |
pip install tortoise-orm[asyncpg] |
MySQL (aiomysql) |
pip install tortoise-orm[aiomysql] |
MySQL (asyncmy) |
pip install tortoise-orm[asyncmy] |
MS SQL |
pip install tortoise-orm[asyncodbc] |
Oracle |
pip install tortoise-orm[asyncodbc] |
Quick Tutorial
Define the models by inheriting from tortoise.models.Model.
from tortoise.models import Model
from tortoise import fields
class Tournament(Model):
id = fields.IntField(primary_key=True)
name = fields.CharField(max_length=20)
class Event(Model):
id = fields.BigIntField(primary_key=True)
name = fields.TextField()
tournament = fields.ForeignKeyField('models.Tournament', related_name='events', on_delete=fields.OnDelete.CASCADE)
participants = fields.ManyToManyField('models.Team', related_name='events', through='event_team', on_delete=fields.OnDelete.SET_NULL)
class Team(Model):
id = fields.UUIDField(primary_key=True)
name = fields.CharField(max_length=20, unique=True)After defining the models, Tortoise ORM needs to be initialized to establish the relationships between models and connect to the database. The code below creates a connection to a SQLite DB database with the aiosqlite client. generate_schema sets up schema on an empty database. generate_schema is for development purposes only; use the built-in migrations for production use.
from tortoise import Tortoise, run_async
async def init():
# Here we connect to a SQLite DB file.
# also specify the app name of "models"
# which contain models from "app.models"
await Tortoise.init(
db_url='sqlite://db.sqlite3',
modules={'models': ['app.models']}
)
# Generate the schema
await Tortoise.generate_schemas()
run_async(main())run_async is a helper function to run simple Tortoise scripts. Check out Documentation for FastAPI, Sanic and other integrations.
With the Tortoise initialized, the models are available for use:
async def main():
await Tortoise.init(
db_url='sqlite://db.sqlite3',
modules={'models': ['app.models']}
)
await Tortoise.generate_schemas()
# Creating an instance with .save()
tournament = Tournament(name='New Tournament')
await tournament.save()
# Or with .create()
await Event.create(name='Without participants', tournament=tournament)
event = await Event.create(name='Test', tournament=tournament)
participants = []
for i in range(2):
team = await Team.create(name='Team {}'.format(i + 1))
participants.append(team)
# One to Many (ForeignKey) relations support creating related objects
another_event = await tournament.events.create(name='Another Event')
# Many to Many Relationship management is quite straightforward
# (there are .remove(...) and .clear() too)
await event.participants.add(*participants)
# Iterate over related entities with the async context manager
async for team in event.participants:
print(team.name)
# The related entities are cached and can be iterated in the synchronous way afterwards
for team in event.participants:
pass
# Use prefetch_related to fetch related objects
selected_events = await Event.filter(
participants=participants[0].id
).prefetch_related('participants', 'tournament')
for event in selected_events:
print(event.tournament.name)
print([t.name for t in event.participants])
# Prefetch multiple levels of related entities
await Team.all().prefetch_related('events__tournament')
# Filter and order by related models too
await Tournament.filter(
events__name__in=['Test', 'Prod']
).order_by('-events__participants__name').distinct()
run_async(main())Learn more at the documentation site
Migrations
Tortoise ORM ships with a built-in migration framework and CLI. Autodetect model changes, generate migration files, and apply them:
tortoise init # create migration packages
tortoise makemigrations # detect changes and generate migrations
tortoise migrate # apply pending migrations
tortoise sqlmigrate app 001 # preview SQL without executingMigrations support RunPython and RunSQL for data migrations, offline migration generation, reversible operations, and multi-app and multi db-schema projects.
See the migrations documentation for full setup and examples.
Contributing
Please have a look at the Contribution Guide.
License
This project is licensed under the Apache License - see the LICENSE.txt file for details.
3 maintainers
Release files for tortoise-orm 1.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tortoise_orm-1.1.8.tar.gz | 398.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tortoise_orm-1.1.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 676.9 kB
Release files / tortoise_orm-1.1.8.tar.gz
| Download URL | tortoise_orm-1.1.8.tar.gz |
|---|---|
| Size | 398.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
09e27be9db148824dacea470d01018ab571676f94aa5428a05bcaec44c413ec7
|
|
BLAKE2b-256 checksum How to use checksums |
108c059f284ed7a08e9cf3a45973e2b9d013a8f242fbb1051a06c3d60c638920
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / tortoise_orm-1.1.8-py3-none-any.whl
| Download URL | tortoise_orm-1.1.8-py3-none-any.whl |
|---|---|
| Size | 278.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f771365c54297543b3b2b7fab4ecb03e89de0a68a41328d2e171c043e08e911
|
|
BLAKE2b-256 checksum How to use checksums |
8a525508cea1339bf9de5016a1ace71e2cca51faf07c54cf54dc3d3ce25e07e1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
