Aerich

Introduction

Aerich is a database migrations tool for Tortoise-ORM, which is like alembic for SQLAlchemy, or like Django ORM with it's own migration solution.

Install

Just install from pypi:

pip install aerich

Quick Start

> aerich -h

Usage: aerich [OPTIONS] COMMAND [ARGS]...

Options:
  -V, --version      Show the version and exit.
  -c, --config TEXT  Config file.  [default: pyproject.toml]
  --app TEXT         Tortoise-ORM app name.
  -h, --help         Show this message and exit.

Commands:
  downgrade  Downgrade to specified version.
  heads      Show current available heads in migrate location.
  history    List all migrate items.
  init       Init config file and generate root migrate location.
  init-db    Generate schema and generate app migrate location.
  inspectdb  Introspects the database tables to standard output as...
  migrate    Generate migrate changes file.
  upgrade    Upgrade to specified version.

Usage

You need add aerich.models to your Tortoise-ORM config first. Example:

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

Initialization

> aerich init -h

Usage: aerich init [OPTIONS]

  Init config file and generate root migrate location.

Options:
  -t, --tortoise-orm TEXT  Tortoise-ORM config module dict variable, like
                           settings.TORTOISE_ORM.  [required]
  --location TEXT          Migrate store location.  [default: ./migrations]
  -s, --src_folder TEXT    Folder of the source, relative to the project root.
  -h, --help               Show this message and exit.

Initialize the config file and migrations location:

> aerich init -t tests.backends.mysql.TORTOISE_ORM

Success create migrate location ./migrations
Success write config to pyproject.toml

Init db

> aerich init-db

Success create app migrate location ./migrations/models
Success generate schema for app "models"

If your Tortoise-ORM app is not the default models, you must specify the correct app via --app, e.g. aerich --app other_models init-db.

Update models and make migrate

> aerich migrate --name drop_column

Success migrate 1_202029051520102929_drop_column.sql

Format of migrate filename is {version_num}_{datetime}_{name|update}.sql.

If aerich guesses you are renaming a column, it will ask Rename {old_column} to {new_column} [True]. You can choose True to rename column without column drop, or choose False to drop the column then create. Note that the latter may lose data.

Upgrade to latest version

> aerich upgrade

Success upgrade 1_202029051520102929_drop_column.sql

Now your db is migrated to latest.

Downgrade to specified version

> aerich downgrade -h

Usage: aerich downgrade [OPTIONS]

  Downgrade to specified version.

Options:
  -v, --version INTEGER  Specified version, default to last.  [default: -1]
  -d, --delete           Delete version files at the same time.  [default:
                         False]

  --yes                  Confirm the action without prompting.
  -h, --help             Show this message and exit.

> aerich downgrade

Success downgrade 1_202029051520102929_drop_column.sql

Now your db is rolled back to the specified version.

Show history

> aerich history

1_202029051520102929_drop_column.sql

Show heads to be migrated

> aerich heads

1_202029051520102929_drop_column.sql

Inspect db tables to TortoiseORM model

Currently inspectdb only supports MySQL.

Usage: aerich inspectdb [OPTIONS]

  Introspects the database tables to standard output as TortoiseORM model.

Options:
  -t, --table TEXT  Which tables to inspect.
  -h, --help        Show this message and exit.

Inspect all tables and print to console:

aerich --app models inspectdb

Inspect a specified table in the default app and redirect to models.py:

aerich inspectdb -t user > models.py

Note that this command is limited and cannot infer some fields, such as IntEnumField, ForeignKeyField, and others.

Multiple databases

tortoise_orm = {
    "connections": {
        "default": expand_db_url(db_url, True),
        "second": expand_db_url(db_url_second, True),
    },
    "apps": {
        "models": {"models": ["tests.models", "aerich.models"], "default_connection": "default"},
        "models_second": {"models": ["tests.models_second"], "default_connection": "second", },
    },
}

You only need to specify aerich.models in one app, and must specify --app when running aerich migrate and so on.

Restore aerich workflow

In some cases, such as broken changes from upgrade of aerich, you can't run aerich migrate or aerich upgrade, you can make the following steps:

1. drop aerich table.
2. delete migrations/{app} directory.
3. rerun aerich init-db.

Note that these actions is safe, also you can do that to reset your migrations if your migration files is too many.

Use aerich in application

You can use aerich out of cli by use Command class.

from aerich import Command

command = Command(tortoise_config=config, app='models')
await command.init()
await command.migrate('test')

License

This project is licensed under the Apache-2.0 License.