Tortoise ORM is an easy-to-use asyncio ORM (Object Relational Mapper) inspired by Django.
You can find the docs at Documentation
Note
Tortoise ORM is a young project and breaking changes are to be expected. We keep a Changelog and it will have possible breakage clearly documented.
Tortoise ORM supports CPython 3.10 and later for SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.
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), it's trading places with Pony ORM:
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.
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] |
Define the models by inheriting from tortoise.models.Model.
fromtortoise.modelsimportModelfromtortoiseimportfieldsclassTournament(Model): id=fields.IntField(primary_key=True) name=fields.CharField(max_length=20) classEvent(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) classTeam(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.
fromtortoiseimportTortoise, run_asyncasyncdefinit(): # Here we connect to a SQLite DB file.# also specify the app name of "models"# which contain models from "app.models"awaitTortoise.init( db_url='sqlite://db.sqlite3', modules={'models': ['app.models']} ) # Generate the schemaawaitTortoise.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:
asyncdefmain(): awaitTortoise.init( db_url='sqlite://db.sqlite3', modules={'models': ['app.models']} ) awaitTortoise.generate_schemas() # Creating an instance with .save()tournament=Tournament(name='New Tournament') awaittournament.save() # Or with .create()awaitEvent.create(name='Without participants', tournament=tournament) event=awaitEvent.create(name='Test', tournament=tournament) participants= [] foriinrange(2): team=awaitTeam.create(name='Team{}'.format(i+1)) participants.append(team) # One to Many (ForeignKey) relations support creating related objectsanother_event=awaittournament.events.create(name='Another Event') # Many to Many Relationship management is quite straightforward# (there are .remove(...) and .clear() too)awaitevent.participants.add(*participants) # Iterate over related entities with the async context managerasyncforteaminevent.participants: print(team.name) # The related entities are cached and can be iterated in the synchronous way afterwardsforteaminevent.participants: pass# Use prefetch_related to fetch related objectsselected_events=awaitEvent.filter( participants=participants[0].id ).prefetch_related('participants', 'tournament') foreventinselected_events: print(event.tournament.name) print([t.namefortinevent.participants]) # Prefetch multiple levels of related entitiesawaitTeam.all().prefetch_related('events__tournament') # Filter and order by related models tooawaitTournament.filter( events__name__in=['Test', 'Prod'] ).order_by('-events__participants__name').distinct() run_async(main())Learn more at the documentation site
Tortoise ORM ships with built-in migrations and a CLI. See the migrations documentation for setup, commands, and examples.
Please have a look at the Contribution Guide.
Powerful Python IDE Pycharm from Jetbrains.
This project is licensed under the Apache License - see the LICENSE.txt file for details.