DEV Community


Posted on • Updated on

aerich migration package for Tortoise ORM

Aerich a migration module for Tortoise ORM

original post in

Async programming is getting more popular with Python in recent years. From Python 3.4, we have native async support. Currently, there are not many ORMs (Object Relation Mappers) that support async. One such notable ORM is Tortoise ORM. But it does not support migration features.

aerich package adds migrations support to Tortoise ORM. It works well with MySQL. I am yet to test with SQLite and PostgreSQL, will check and post findings.

We need Tortoise ORM version > 16.2 or above for aerich.

How it works

aerich maintains file to which keeps tracks of last changes. Old models and current models compared, and if there are changes, respective SQL commands will be for upgrading and reverting.

aerich can be installed through pip

pip install aerich
Enter fullscreen mode Exit fullscreen mode

Configuring aerich in the application pretty easy. we need to configure the TortoiseORM models.

  • We need to add "aerich.models" in Tortoise ORM configuration dict. It will create a table called aerich to capture the history of migrations.
        "connections": {
            "default": "mysql://user:test_pwd@localhost:3306/communication?charset=utf8mb4"
        "apps": {
            "models": {
                "models": ["app.models", "aerich.models"],
                "default_connection": "default",
Enter fullscreen mode Exit fullscreen mode
  • We can initiate aerich with the below command and it will initiate migrations for the application.
    aerich init -t settings.TORTOISE_ORM
Enter fullscreen mode Exit fullscreen mode
* *aerich.ini* -  config file maintains aerich configurations.
* *migrations folder* - to capture all migrations. 
Enter fullscreen mode Exit fullscreen mode
  • To create initial migration files, the below creates initial migrations if not exists.
   aerich init-db
Enter fullscreen mode Exit fullscreen mode
* It creates JSON file with timestamp with initial SQL commands and 
* - keeps tracks last applied changes. 
Enter fullscreen mode Exit fullscreen mode

The module provides the following commands.

  • migrate - compares the current models with old models and creates SQL query commands.
  • upgrade - applies all unapplied migrations to the database.
  • downgrade - reverts the last applied migrations.
  • history - lists all applied migrations.
  • heads - list unapplied migrations

to clear all migrations,

  • truncate the aerich table
  • remove models folder under migrations.

aerich is a promising module for tortoise ORM.

Top comments (0)