tortoise-orm

Define models by subclassing tortoise.models.Model and declaring fields like CharField or IntField. Use ForeignKeyField, ManyToManyField, and OneToOneField for relations, specifying the model string, related_name, and on_delete behavior.

Tortoise QuerySets are lazy and must be awaited. Use Model.filter() with double-underscore operators like __gt or __icontains, combine conditions with Q objects, and eager-load relations with select_related or prefetch_related.

Yes, Tortoise ORM integrates with FastAPI through RegisterTortoise used inside the v1.x lifespan context manager. This handles database initialization and cleanup, and pydantic_model_creator generates serialization schemas from your models.

NoValuesFetched occurs when accessing a relation that was not explicitly fetched, since Tortoise has no lazy loading. Fix it by calling await obj.fetch_related("field") or using select_related/prefetch_related in the original query.

Tortoise v1.1.7 includes a built-in migration system replacing Aerich. Run tortoise init, tortoise makemigrations, and tortoise migrate from the CLI, and use RunPython or RunSQL for data migrations.

auto_now and auto_now_add set timestamps only in Python and create no database DEFAULT clause. Use db_default=Now() from tortoise.fields.db_defaults when the database itself must set the default, such as for raw SQL inserts.