Aerich

Introduction

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

Important: You can only use absolutely import in your models.py to make aerich work.

Install

Just install from pypi:

> pip install aerich

Quick Start

> aerich -h

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

Options:
  -c, --config TEXT  Config file.  [default: aerich.ini]
  --app TEXT         Tortoise-ORM app name.  [default: models]
  -n, --name TEXT    Name of section in .ini file to use for aerich config.
                     [default: aerich]
  -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.
  migrate    Generate migrate changes file.
  upgrade    Upgrade to latest version.

Usage

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

TORTOISE_ORM = {
    "connections": {"default": "mysql://root:123456@127.0.0.1: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]
  -h, --help               Show this message and exit.

Init config file and location:

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

Success create migrate location ./migrations
Success generate config file aerich.ini

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 default models, you must specify --app like 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.

And if aerich guess you are renaming a column, it will ask Rename {old_column} to {new_column} [True], you can choice True to rename column without column drop, or choice False to drop column then create.

If you use MySQL, only MySQL8.0+ support rename..to syntax.

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 init -h

Usage: aerich downgrade [OPTIONS]

  Downgrade to specified version.

Options:
  -v, --version INTEGER  Specified version, default to last.  [default: -1]
  -h, --help             Show this message and exit.

> aerich downgrade

Success downgrade 1_202029051520102929_drop_column.sql

Now your db rollback to specified version.

Show history

> aerich history

1_202029051520102929_drop_column.sql

Show heads to be migrated

> aerich heads

1_202029051520102929_drop_column.sql

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 need only specify aerich.models in one app, and must specify --app when run aerich migrate and so on.

Support this project

AliPay	WeChatPay	PayPal
		PayPal to my account long2ice.

License

This project is licensed under the Apache-2.0 License.

SakuraSound/aerich