Aerich Documentation

To prevent Aerich from managing a specific table during migrations, set managed = False in the model's Meta class.

Note: This setting is only recognized by aerich migrate. It is not recognized by tortoise-orm or aerich init-db.

class MyModel(Model):
    class Meta:
        managed = False

Install Aerich from PyPI to use it as a database migration tool for TortoiseORM.

pip install aerich

Aerich can introspect existing MySQL, Postgres, or SQLite tables and generate TortoiseORM model code. This is useful for reverse-engineering schemas.

Options:

• -t, --table: Specify a specific table to inspect. If omitted, all tables are inspected.

Usage:

• To print all models to stdout: aerich --app models inspectdb
• To save a specific table to a file: aerich inspectdb -t user > models.py

Note: Some complex fields like IntEnumField or ForeignKeyField might not be correctly inferred.

Install Aerich from PyPI with TOML support using pip. You can also install the latest version directly from GitHub.

Note: For tortoise-orm>=1.0.0, you can use the built-in CLI for migrations (e.g., python -m tortoise makemigrations) instead of Aerich.

pip install "aerich[toml]"

# Or from GitHub
pip install "aerich[toml] @git+https://github.com/tortoise/aerich"

Use aerich init to create the configuration file (defaults to pyproject.toml) and the root migration storage location.

Options:

• -t, --tortoise-orm: The path to your Tortoise-ORM config module/variable (e.g., settings.TORTOISE_ORM). Required.
• --location: The migration store location (defaults to ./migrations).
• -s, --src_folder: Folder of the source, relative to the project root.

To use a Django-style per-app migration structure, set the location to include the {app} placeholder, for example: --location "./{app}/migrations".

aerich init -t tests.backends.mysql.TORTOISE_ORM

To use Aerich, you must include aerich.models in your Tortoise-ORM configuration under the apps section. This allows Aerich to track migration state.

If you have only one app in your configuration, the aerich.models entry might be omitted, but it is recommended for clarity.

TORTOISE_ORM = {
    "connections": {"default": "mysql://root:123456@127.0.0.1:3306/test"},
    "apps": {
        "models": {
            "models": ["tests.models", "aerich.models"],
            "default_connection": "default",
        },
    },
}

To use Aerich, you must include aerich.models in your Tortoise-ORM configuration under the relevant app.

Note: If you are using multiple databases, you should only include aerich.models in one of your apps. For all other apps, you must specify the app name using the --app flag when running Aerich commands.

Example configuration:

TORTOISE_ORM = {
    "connections": {"default": "mysql://root:123456@127.0.0.1:3306/test"},
    "apps": {
        "models": {
            "models": ["tests.models", "aerich.models"],
            "default_connection": "default",
        },
    },
}

Use aerich init-db to generate the initial database schema and create the migration folder for your app.

If your Tortoise-ORM app is named something other than models, you must specify it using the --app flag.

aerich init-db

# For a custom app name
aerich --app other_models init-db

If you encounter issues (e.g., after an Aerich update) where migrate or upgrade fails, you can reset the migration state.

Warning: This is a destructive process used to reset migrations.

1. Delete the aerich tables in your database.
2. Delete the migrations/{app} directory.
3. Run aerich init-db to start fresh.

You can execute Aerich commands outside of the CLI by using the Command class.

from aerich import Command

# config is your Tortoise-ORM configuration dictionary
command = Command(tortoise_config=config, app="models")
await command.init()
await command.migrate("test")