Aerich

Common errors

• No Tortoise-ORM config found. Please specify it via --tortoise-config or environment variable AERICH_CONFIG

  cause Aerich could not locate your Tortoise-ORM configuration. The `AERICH_CONFIG` environment variable is deprecated/removed in newer versions.
  fix Provide the configuration path directly using the `-t` or `--tortoise-config` argument: `aerich init -t your_app.config.TORTOISE_CONFIG`.

• tortoise.exceptions.ConfigurationError: app models has no default connection

  cause One of the apps defined in your `TORTOISE_CONFIG['apps']` dictionary is missing the `default_connection` key, or its value is invalid.
  fix Ensure each app configuration in `TORTOISE_CONFIG['apps']` correctly specifies its default connection, e.g., `"default_connection": "default"`.

• tortoise.exceptions.OperationalError: no such table: aerich

  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.
  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`.

Warnings

• breaking Aerich versions 0.6.0 and later removed the `AERICH_CONFIG` environment variable and changed how Tortoise-ORM configuration is specified.
  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`.
• gotcha 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.
  Fix: Ensure your `TORTOISE_CONFIG['apps']['models']['models']` list includes `'aerich.models'`, for example: `"models": ["your_app.models", "aerich.models"]`.
• gotcha Using `sqlite://:memory:` in your `TORTOISE_CONFIG` for database connections will result in database changes (including migrations) not being persisted.
  Fix: For persistent migrations, always configure a file-based SQLite database (e.g., `sqlite://db.sqlite3`) or a connection to a persistent database server.

Install

• pip install aerich Install Aerich

Imports

• AerichCommand

  from aerich.commands import AerichCommand

  Used for programmatic interaction with Aerich; most users interact via the CLI.

Quickstart

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: 1. Save the above content as `config.py` in your project root. 2. Run the following commands in your terminal to initialize Aerich, create, and apply migrations: ```bash aerich init -t config.TORTOISE_CONFIG aerich migrate aerich upgrade ```

# config.py
from tortoise import fields, models

class User(models.Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=255)

    class Meta:
        table = "users"


TORTOISE_CONFIG = {
    "connections": {"default": "sqlite://db.sqlite3"},
    "apps": {
        "models": {
            "models": ["config", "aerich.models"], # "config" refers to models defined in this file
            "default_connection": "default",
        }
    },
}