aerich/README_RU.md

Aerich

English | Русский

Введение

Aerich - это инструмент для миграции базы данных для TortoiseORM, который аналогичен Alembic для SQLAlchemy или встроенному решению миграций в Django ORM.

Установка

Просто установите из pypi:

pip install aerich

Быстрый старт

> 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.

Использование

Сначала вам нужно добавить aerich.models в конфигурацию вашего Tortoise-ORM. Пример:

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

Инициализация

> 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.

Инициализируйте файл конфигурации и задайте местоположение миграций:

> aerich init -t tests.backends.mysql.TORTOISE_ORM
 
Success create migrate location ./migrations
Success write config to pyproject.toml

Инициализация базы данных

> aerich init-db
 
Success create app migrate location ./migrations/models
Success generate schema for app "models"

Если ваше приложение Tortoise-ORM не является приложением по умолчанию с именем models, вы должны указать правильное имя приложения с помощью параметра --app, например: aerich --app other_models init-db.

Обновление моделей и создание миграции

> aerich migrate --name drop_column
 
Success migrate 1_202029051520102929_drop_column.py

Формат имени файла миграции следующий: {версия}_{дата_и_время}_{имя|обновление}.py.

Если aerich предполагает, что вы переименовываете столбец, он спросит: Переименовать {старый_столбец} в {новый_столбец} [True]. Вы можете выбрать True, чтобы переименовать столбец без удаления столбца, или выбрать False, чтобы удалить столбец, а затем создать новый. Обратите внимание, что последний вариант может привести к потере данных.

Обновление до последней версии

> aerich upgrade
 
Success upgrade 1_202029051520102929_drop_column.py

Теперь ваша база данных обновлена до последней версии.

Откат до указанной версии

> 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.py

Теперь ваша база данных откатилась до указанной версии.

Показать историю

> aerich history
 
1_202029051520102929_drop_column.py

Чтобы узнать, какие миграции должны быть применены, можно использовать команду:

> aerich heads
 
1_202029051520102929_drop_column.py

Осмотр таблиц базы данных для модели TortoiseORM

В настоящее время inspectdb поддерживает MySQL, Postgres и SQLite.

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.

Посмотреть все таблицы и вывести их на консоль:

aerich --app models inspectdb

Осмотреть указанную таблицу в приложении по умолчанию и перенаправить в models.py:

aerich inspectdb -t user > models.py

Например, ваша таблица выглядит следующим образом:

CREATE TABLE `test`
(
    `id`       int            NOT NULL AUTO_INCREMENT,
    `decimal`  decimal(10, 2) NOT NULL,
    `date`     date                                    DEFAULT NULL,
    `datetime` datetime       NOT NULL                 DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    `time`     time                                    DEFAULT NULL,
    `float`    float                                   DEFAULT NULL,
    `string`   varchar(200) COLLATE utf8mb4_general_ci DEFAULT NULL,
    `tinyint`  tinyint                                 DEFAULT NULL,
    PRIMARY KEY (`id`),
    KEY `asyncmy_string_index` (`string`)
) ENGINE = InnoDB
  DEFAULT CHARSET = utf8mb4
  COLLATE = utf8mb4_general_ci

Теперь выполните команду aerich inspectdb -t test, чтобы увидеть сгенерированную модель:

from tortoise import Model, fields
 
 
class Test(Model):
    date = fields.DateField(null=True, )
    datetime = fields.DatetimeField(auto_now=True, )
    decimal = fields.DecimalField(max_digits=10, decimal_places=2, )
    float = fields.FloatField(null=True, )
    id = fields.IntField(pk=True, )
    string = fields.CharField(max_length=200, null=True, )
    time = fields.TimeField(null=True, )
    tinyint = fields.BooleanField(null=True, )

Обратите внимание, что эта команда имеет ограничения и не может автоматически определить некоторые поля, такие как IntEnumField, ForeignKeyField и другие.

Несколько баз данных

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", },
    },
}

Вам нужно указать aerich.models только в одном приложении и должны указывать --app при запуске команды aerich migrate и т.д.

Восстановление рабочего процесса aerich

В некоторых случаях, например, при возникновении проблем после обновления aerich, вы не можете запустить aerich migrate или aerich upgrade. В таком случае вы можете выполнить следующие шаги:

1. удалите таблицы aerich.
2. удалите директорию migrations/{app}.
3. rerun aerich init-db.

Обратите внимание, что эти действия безопасны, и вы можете использовать их для сброса миграций, если у вас слишком много файлов миграции.

Использование aerich в приложении

Вы можете использовать aerich вне командной строки, используя класс Command.

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

Лицензия

Этот проект лицензирован в соответствии с лицензией Apache-2.0 Лицензия.