Skip to main content

Easy async ORM for python, built with relations in mind

Project description

https://img.shields.io/pypi/v/tortoise-orm.svg?style=flat https://pepy.tech/badge/tortoise-orm/month https://github.com/tortoise/tortoise-orm/workflows/gh-pages/badge.svg https://github.com/tortoise/tortoise-orm/actions/workflows/ci.yml/badge.svg?branch=develop https://coveralls.io/repos/github/tortoise/tortoise-orm/badge.svg https://app.codacy.com/project/badge/Grade/844030d0cb8240d6af92c71bfac764ff

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.9 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. In our benchmarks, where we measure different read and write operations (rows/sec, more is better), it’s trading places with Pony ORM:

https://raw.githubusercontent.com/tortoise/tortoise-orm/develop/docs/ORM_Perf.png

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):

Available Installation Options

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, check out aerich or other migration tools 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)

    # 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

Migration

Tortoise ORM uses Aerich as its database migration tool, see more detail at its docs.

Contributing

Please have a look at the Contribution Guide.

ThanksTo

Powerful Python IDE Pycharm from Jetbrains.

https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg

License

This project is licensed under the Apache License - see the LICENSE.txt file for details.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tortoise_orm-0.25.1.tar.gz (128.3 kB view details)

Uploaded Source

Built Distribution

tortoise_orm-0.25.1-py3-none-any.whl (167.7 kB view details)

Uploaded Python 3

File details

Details for the file tortoise_orm-0.25.1.tar.gz.

File metadata

  • Download URL: tortoise_orm-0.25.1.tar.gz
  • Upload date:
  • Size: 128.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for tortoise_orm-0.25.1.tar.gz
Algorithm Hash digest
SHA256 4d5bfd13d5750935ffe636a6b25597c5c8f51c47e5b72d7509d712eda1a239fe
MD5 ef8df163a207f40230c618efa18ca32b
BLAKE2b-256 d79bde966810021fa773fead258efd8deea2bb73bb12479e27f288bd8ceb8763

See more details on using hashes here.

File details

Details for the file tortoise_orm-0.25.1-py3-none-any.whl.

File metadata

  • Download URL: tortoise_orm-0.25.1-py3-none-any.whl
  • Upload date:
  • Size: 167.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for tortoise_orm-0.25.1-py3-none-any.whl
Algorithm Hash digest
SHA256 df0ef7e06eb0650a7e5074399a51ee6e532043308c612db2cac3882486a3fd9f
MD5 8a386089f6a0f1cdb0460a4dd15c1c34
BLAKE2b-256 70552bda7f4445f4c07b734385b46d1647a388d05160cf5b8714a713e8709378

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page