Tortoise ORM

Warnings

• breaking connections.close_all() removed in v1.0. Raises AttributeError.
  Fix: Use Tortoise.close_connections() instead.
• breaking Running multiple FastAPI apps in the same process (e.g., in tests) raises ConfigurationError: 'Global context fallback is already enabled'. Happens with lifespan-based testing.
  Fix: Pass _enable_global_fallback=False to RegisterTortoise for secondary apps.
• gotcha Must use 'modules' dict when calling Tortoise.init() — must list all model module paths explicitly. Missing a module means those models are unknown to Tortoise and relations fail silently.
  Fix: modules={'models': ['myapp.models.user', 'myapp.models.post']} — list ALL model files.
• gotcha tortoise-orm does not work on serverless/Vercel without workarounds. Connection pooling assumes long-running process — serverless cold starts cause 'connection pool is closed' errors.
  Fix: Not recommended for serverless. Use asyncpg directly or a serverless-compatible ORM.
• gotcha generate_schemas=True in production silently drops and recreates tables if schema changes. Use Aerich (tortoise's migration tool) for production schema management.
  Fix: Set generate_schemas=False in production. Use aerich for migrations: pip install aerich
• gotcha pydantic_model_creator() generates Pydantic models from Tortoise models. In v1.0, internal validator logic was cleaned up — custom PydanticMeta overrides may behave differently.
  Fix: Test pydantic_model_creator() output after upgrading to v1.0.
• gotcha DB-specific drivers must be installed separately. 'pip install tortoise-orm' alone raises ImproperlyConfigured when connecting to PostgreSQL or MySQL.
  Fix: pip install 'tortoise-orm[asyncpg]' for PostgreSQL, 'tortoise-orm[asyncmy]' for MySQL, 'tortoise-orm[aiosqlite]' for SQLite.

Install

• pip install tortoise-orm Python (pure — no C deps)
• pip install 'tortoise-orm[accel]' Python (with C accelerators — faster)
• pip install 'tortoise-orm[asyncpg]' Python (with asyncpg for PostgreSQL)

Imports

• RegisterTortoise (FastAPI — v1.0+ recommended)

  from contextlib import asynccontextmanager
  from fastapi import FastAPI
  from tortoise.contrib.fastapi import RegisterTortoise
  
  @asynccontextmanager
  async def lifespan(app: FastAPI):
      async with RegisterTortoise(
          app,
          db_url='postgres://user:pass@localhost/mydb',
          modules={'models': ['myapp.models']},
          generate_schemas=True,
      ):
          yield
  
  app = FastAPI(lifespan=lifespan)

  register_tortoise() still works but uses deprecated FastAPI on_event hooks. Use RegisterTortoise async context manager with FastAPI lifespan for v1.0+ style.
• Tortoise.init (standalone scripts)

  from tortoise import Tortoise
  
  async def main():
      await Tortoise.init(
          db_url='sqlite://db.sqlite3',
          modules={'models': ['myapp.models']}
      )
      await Tortoise.generate_schemas()
  
      user = await User.create(name='Alice')
      users = await User.filter(name='Alice').all()
  
      await Tortoise.close_connections()
  
  import asyncio
  asyncio.run(main())

  connections.close_all() removed in v1.0. Use Tortoise.close_connections() instead.

Quickstart

Tortoise ORM v1.x standalone script with PostgreSQL.

# pip install 'tortoise-orm[asyncpg]'
from tortoise import Tortoise, fields
from tortoise.models import Model
import asyncio

class User(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50)
    email = fields.CharField(max_length=120, unique=True)

    class Meta:
        table = 'users'

async def main():
    await Tortoise.init(
        db_url='postgres://user:pass@localhost/mydb',
        modules={'models': ['__main__']}
    )
    await Tortoise.generate_schemas()

    # Create
    user = await User.create(name='Alice', email='alice@example.com')

    # Query
    users = await User.filter(name='Alice').all()
    user = await User.get(id=1)
    user = await User.get_or_none(email='alice@example.com')

    await Tortoise.close_connections()

asyncio.run(main())