{"id":7899,"library":"aerich","title":"Aerich","description":"Aerich is a database migrations tool specifically designed for Tortoise ORM. It automates schema evolution by generating and applying migration scripts, making it easier to manage database changes in Python projects. It is actively maintained, with version 0.9.2 being the latest as of early 2024, and features regular releases for bug fixes and new functionality.","status":"active","version":"0.9.2","language":"en","source_language":"en","source_url":"https://github.com/aerich/aerich","tags":["database","migrations","ORM","Tortoise-ORM","cli"],"install":[{"cmd":"pip install aerich","lang":"bash","label":"Install Aerich"}],"dependencies":[{"reason":"Aerich is a migration tool exclusively for Tortoise ORM.","package":"tortoise-orm","optional":false}],"imports":[{"note":"Used for programmatic interaction with Aerich; most users interact via the CLI.","symbol":"AerichCommand","correct":"from aerich.commands import AerichCommand"}],"quickstart":{"code":"# config.py\nfrom tortoise import fields, models\n\nclass User(models.Model):\n    id = fields.IntField(pk=True)\n    name = fields.CharField(max_length=255)\n\n    class Meta:\n        table = \"users\"\n\n\nTORTOISE_CONFIG = {\n    \"connections\": {\"default\": \"sqlite://db.sqlite3\"},\n    \"apps\": {\n        \"models\": {\n            \"models\": [\"config\", \"aerich.models\"], # \"config\" refers to models defined in this file\n            \"default_connection\": \"default\",\n        }\n    },\n}","lang":"python","description":"This quickstart provides the content for a `config.py` file, defining a simple Tortoise-ORM configuration (`TORTOISE_CONFIG`) and a `User` model. To use Aerich:\n\n1. Save the above content as `config.py` in your project root.\n2. Run the following commands in your terminal to initialize Aerich, create, and apply migrations:\n   ```bash\n   aerich init -t config.TORTOISE_CONFIG\n   aerich migrate\n   aerich upgrade\n   ```"},"warnings":[{"fix":"Always use the `-t` or `--tortoise-config` command-line argument to specify your Tortoise-ORM configuration module and variable name, e.g., `aerich init -t my_app.config.TORTOISE_CONFIG`.","message":"Aerich versions 0.6.0 and later removed the `AERICH_CONFIG` environment variable and changed how Tortoise-ORM configuration is specified.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Ensure your `TORTOISE_CONFIG['apps']['models']['models']` list includes `'aerich.models'`, for example: `\"models\": [\"your_app.models\", \"aerich.models\"]`.","message":"Failing to include `aerich.models` in your `TORTOISE_CONFIG['apps']['models']['models']` list will prevent Aerich from managing its internal schema and lead to errors.","severity":"gotcha","affected_versions":"All"},{"fix":"For persistent migrations, always configure a file-based SQLite database (e.g., `sqlite://db.sqlite3`) or a connection to a persistent database server.","message":"Using `sqlite://:memory:` in your `TORTOISE_CONFIG` for database connections will result in database changes (including migrations) not being persisted.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Provide the configuration path directly using the `-t` or `--tortoise-config` argument: `aerich init -t your_app.config.TORTOISE_CONFIG`.","cause":"Aerich could not locate your Tortoise-ORM configuration. The `AERICH_CONFIG` environment variable is deprecated/removed in newer versions.","error":"No Tortoise-ORM config found. Please specify it via --tortoise-config or environment variable AERICH_CONFIG"},{"fix":"Ensure each app configuration in `TORTOISE_CONFIG['apps']` correctly specifies its default connection, e.g., `\"default_connection\": \"default\"`.","cause":"One of the apps defined in your `TORTOISE_CONFIG['apps']` dictionary is missing the `default_connection` key, or its value is invalid.","error":"tortoise.exceptions.ConfigurationError: app models has no default connection"},{"fix":"1. Ensure `'aerich.models'` is in your `TORTOISE_CONFIG['apps']['models']['models']`. 2. Run `aerich init -t your_config.TORTOISE_CONFIG` followed by `aerich upgrade`.","cause":"Aerich's internal migration table (`aerich`) was not created. This usually happens if `aerich.models` is not included in `TORTOISE_CONFIG` or if `aerich initdb` (or `aerich init` then `aerich upgrade`) was not run.","error":"tortoise.exceptions.OperationalError: no such table: aerich"}]}