{"id":163,"library":"tortoise-orm","title":"Tortoise ORM","description":"Async ORM for Python inspired by Django ORM. Built on asyncio — requires async context. Current version: 1.1.7 (Mar 2026). v1.0 released 2024 — first stable release after years of 0.x. Breaking changes from 0.x: connections.close_all() removed, ConnectionHandler uses per-instance ContextVar storage. FastAPI integration changed from register_tortoise() to RegisterTortoise context manager. Does not work on serverless/Vercel without workarounds.","status":"active","version":"1.1.7","language":"python","source_language":"en","source_url":"https://github.com/tortoise/tortoise-orm","tags":["tortoise-orm","orm","async","asyncio","fastapi","postgresql","python"],"install":[{"cmd":"pip install tortoise-orm","lang":"bash","label":"Python (pure — no C deps)"},{"cmd":"pip install 'tortoise-orm[accel]'","lang":"bash","label":"Python (with C accelerators — faster)"},{"cmd":"pip install 'tortoise-orm[asyncpg]'","lang":"bash","label":"Python (with asyncpg for PostgreSQL)"}],"dependencies":[{"reason":"Required for PostgreSQL. Install via tortoise-orm[asyncpg].","package":"asyncpg","optional":true},{"reason":"Required for SQLite async. Install via tortoise-orm[aiosqlite].","package":"aiosqlite","optional":true},{"reason":"Required for MySQL. Install via tortoise-orm[asyncmy].","package":"asyncmy","optional":true}],"imports":[{"wrong":"from tortoise.contrib.fastapi import RegisterTortoise","symbol":"RegisterTortoise","correct":"from tortoise.contrib.fastapi import RegisterTortoise"}],"quickstart":{"code":"# pip install 'tortoise-orm[asyncpg]'\nfrom tortoise import Tortoise, fields\nfrom tortoise.models import Model\nimport asyncio\n\nclass User(Model):\n    id = fields.IntField(pk=True)\n    name = fields.CharField(max_length=50)\n    email = fields.CharField(max_length=120, unique=True)\n\n    class Meta:\n        table = 'users'\n\nasync def main():\n    await Tortoise.init(\n        db_url='postgres://user:pass@localhost/mydb',\n        modules={'models': ['__main__']}\n    )\n    await Tortoise.generate_schemas()\n\n    # Create\n    user = await User.create(name='Alice', email='alice@example.com')\n\n    # Query\n    users = await User.filter(name='Alice').all()\n    user = await User.get(id=1)\n    user = await User.get_or_none(email='alice@example.com')\n\n    await Tortoise.close_connections()\n\nasyncio.run(main())","lang":"python","description":"Tortoise ORM v1.x standalone script with PostgreSQL."},"warnings":[{"fix":"Use Tortoise.close_connections() instead.","message":"connections.close_all() removed in v1.0. Raises AttributeError.","severity":"breaking","affected_versions":">= 1.0"},{"fix":"Pass _enable_global_fallback=False to RegisterTortoise for secondary apps.","message":"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.","severity":"breaking","affected_versions":">= 1.0"},{"fix":"modules={'models': ['myapp.models.user', 'myapp.models.post']} — list ALL model files.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Not recommended for serverless. Use asyncpg directly or a serverless-compatible ORM.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set generate_schemas=False in production. Use aerich for migrations: pip install aerich","message":"generate_schemas=True in production silently drops and recreates tables if schema changes. Use Aerich (tortoise's migration tool) for production schema management.","severity":"gotcha","affected_versions":"all"},{"fix":"Test pydantic_model_creator() output after upgrading to v1.0.","message":"pydantic_model_creator() generates Pydantic models from Tortoise models. In v1.0, internal validator logic was cleaned up — custom PydanticMeta overrides may behave differently.","severity":"gotcha","affected_versions":">= 1.0"},{"fix":"pip install 'tortoise-orm[asyncpg]' for PostgreSQL, 'tortoise-orm[asyncmy]' for MySQL, 'tortoise-orm[aiosqlite]' for SQLite.","message":"DB-specific drivers must be installed separately. 'pip install tortoise-orm' alone raises ImproperlyConfigured when connecting to PostgreSQL or MySQL.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your database server (e.g., PostgreSQL) is running and accessible from the application's environment on the configured host and port. Verify database server logs, firewall rules, and the connection string (TORTOISE_CONFIG) used by Tortoise-ORM.","message":"Database server is unreachable or connection refused. The application is configured to connect to a database (e.g., PostgreSQL on port 5432), but the server is not running or is not accessible at the specified host/port (e.g., 127.0.0.1:5432).","severity":"breaking","affected_versions":"all"}],"env_vars":null,"search_vec":"'0':31,36 '1.1.7':19 '2024':24 '2026':21 'async':3,15,69 'asyncio':13,70 'break':33 'built':11 'chang':34,50 'connectionhandl':41 'connections.close':38 'context':16,56 'contextvar':46 'current':17 'django':9 'fastapi':48,71 'first':25 'inspir':7 'instanc':45 'integr':49 'manag':57 'mar':20 'orm':2,4,10,67,68 'per':44 'per-inst':43 'postgresql':72 'python':6,73 'regist':52 'registertortois':55 'releas':23,27 'remov':40 'requir':14 'serverless/vercel':62 'stabl':26 'storag':47 'tortois':1,53,66 'tortoise-orm':65 'use':42 'v1.0':22 'version':18 'without':63 'work':60 'workaround':64 'x':32,37 'year':29","created_at":"2026-03-24T18:56:39.687106+00:00","updated_at":"2026-04-16T23:07:07.584846+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":80,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.1.8","cli_name":"tortoise","cli_version":"1.1.7","type":"library","homepage":"https://tortoise-orm.readthedocs.io","github":"https://github.com/tortoise/tortoise-orm","docs":"https://tortoise.github.io","changelog":null,"pypi":"https://pypi.org/project/tortoise-orm/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-08-26","next_check":"2026-07-30","install_tag":"verified"}}