Aerich

0.9.2 verified Thu Apr 16 auth: no python

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.

pip install aerich

Common errors

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

error 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".

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

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",
        }
    },
}