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:
- drop
aerichtable. - delete
migrations/{app}directory. - 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.
6 Mar 31, 2022
1.6k Dec 30, 2022
2.2k Dec 28, 2022
1 Nov 15, 2021
53k Jan 2, 2023
82 Nov 29, 2022
10k Dec 31, 2022
268 Jan 1, 2023
876 Jan 5, 2023
1.5k Jan 2, 2023
12 Nov 6, 2022
2.9k Jan 6, 2023
2 Oct 19, 2021
33 Dec 27, 2022
14 May 25, 2022
1 Dec 16, 2021
1 Jan 1, 2022