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.
67 Sep 01, 2022
1.2k Jan 05, 2023
1.4k Jan 01, 2023
1.7k Dec 28, 2022
119 Dec 01, 2022
281 Nov 10, 2022
3.9k Jan 09, 2023
815 Jan 03, 2023
19 Nov 03, 2022
930 Jan 08, 2023
1 Dec 24, 2021
15 Jan 03, 2023
178 Dec 16, 2022
3 Apr 13, 2022
2.5k Dec 31, 2022
440 Nov 13, 2022
4.2k Dec 26, 2022
128 Dec 31, 2022
122 Aug 23, 2022