{"id":13424632,"url":"https://github.com/tortoise/aerich","last_synced_at":"2025-04-29T18:52:09.161Z","repository":{"id":37104318,"uuid":"262825230","full_name":"tortoise/aerich","owner":"tortoise","description":"A database migrations tool for TortoiseORM, ready to production.","archived":false,"fork":false,"pushed_at":"2025-04-23T02:00:13.000Z","size":1106,"stargazers_count":908,"open_issues_count":58,"forks_count":108,"subscribers_count":17,"default_branch":"dev","last_synced_at":"2025-04-23T03:18:48.532Z","etag":null,"topics":["database-migrations","migration-tool","mysql","orm","postgresql","tortoise-orm"],"latest_commit_sha":null,"homepage":"https://github.com/tortoise/aerich","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tortoise.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":["https://sponsor.long2ice.io"]}},"created_at":"2020-05-10T16:09:30.000Z","updated_at":"2025-04-23T03:02:53.000Z","dependencies_parsed_at":"2024-04-10T09:46:53.951Z","dependency_job_id":"cfa6eef4-90e9-4358-b56e-aabc67b4b6cf","html_url":"https://github.com/tortoise/aerich","commit_stats":{"total_commits":333,"total_committers":34,"mean_commits":9.794117647058824,"dds":0.3513513513513513,"last_synced_commit":"103470f4c1ca6bd20146368d3990a587afe75d09"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tortoise%2Faerich","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tortoise%2Faerich/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tortoise%2Faerich/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tortoise%2Faerich/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tortoise","download_url":"https://codeload.github.com/tortoise/aerich/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250360537,"owners_count":21417724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database-migrations","migration-tool","mysql","orm","postgresql","tortoise-orm"],"created_at":"2024-07-31T00:00:57.187Z","updated_at":"2025-04-29T18:52:09.121Z","avatar_url":"https://github.com/tortoise.png","language":"Python","readme":"# Aerich\n\n[![image](https://img.shields.io/pypi/v/aerich.svg?style=flat)](https://pypi.python.org/pypi/aerich)\n[![image](https://img.shields.io/github/license/tortoise/aerich)](https://github.com/tortoise/aerich)\n[![image](https://github.com/tortoise/aerich/workflows/pypi/badge.svg)](https://github.com/tortoise/aerich/actions?query=workflow:pypi)\n[![image](https://github.com/tortoise/aerich/workflows/ci/badge.svg)](https://github.com/tortoise/aerich/actions?query=workflow:ci)\n\nEnglish | [Русский](./README_RU.md)\n\n## Introduction\n\nAerich is a database migrations tool for TortoiseORM, which is like alembic for SQLAlchemy, or like Django ORM with\nit\\'s own migration solution.\n\n## Install\n\nJust install from pypi:\n\n```shell\npip install \"aerich[toml]\"\n```\n\n## Quick Start\n\n```shell\n\u003e aerich -h\n\nUsage: aerich [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  -V, --version      Show the version and exit.\n  -c, --config TEXT  Config file.  [default: pyproject.toml]\n  --app TEXT         Tortoise-ORM app name.\n  -h, --help         Show this message and exit.\n\nCommands:\n  downgrade  Downgrade to specified version.\n  heads      Show current available heads in migrate location.\n  history    List all migrate items.\n  init       Init config file and generate root migrate location.\n  init-db    Generate schema and generate app migrate location.\n  inspectdb  Introspects the database tables to standard output as...\n  migrate    Generate migrate changes file.\n  upgrade    Upgrade to specified version.\n```\n\n## Usage\n\nYou need to add `aerich.models` to your `Tortoise-ORM` config first. Example:\n\n```python\nTORTOISE_ORM = {\n    \"connections\": {\"default\": \"mysql://root:123456@127.0.0.1:3306/test\"},\n    \"apps\": {\n        \"models\": {\n            \"models\": [\"tests.models\", \"aerich.models\"],\n            \"default_connection\": \"default\",\n        },\n    },\n}\n```\n\n### Initialization\n\n```shell\n\u003e aerich init -h\n\nUsage: aerich init [OPTIONS]\n\n  Init config file and generate root migrate location.\n\nOptions:\n  -t, --tortoise-orm TEXT  Tortoise-ORM config module dict variable, like\n                           settings.TORTOISE_ORM.  [required]\n  --location TEXT          Migrate store location.  [default: ./migrations]\n  -s, --src_folder TEXT    Folder of the source, relative to the project root.\n  -h, --help               Show this message and exit.\n```\n\nInitialize the config file and migrations location:\n\n```shell\n\u003e aerich init -t tests.backends.mysql.TORTOISE_ORM\n\nSuccess create migrate location ./migrations\nSuccess write config to pyproject.toml\n```\n\n### Init db\n\n```shell\n\u003e aerich init-db\n\nSuccess create app migrate location ./migrations/models\nSuccess generate schema for app \"models\"\n```\n\nIf your Tortoise-ORM app is not the default `models`, you must specify the correct app via `--app`,\ne.g. `aerich --app other_models init-db`.\n\n### Update models and make migrate\n\n```shell\n\u003e aerich migrate --name drop_column\n\nSuccess migrate 1_202029051520102929_drop_column.py\n```\n\nFormat of migrate filename is\n`{version_num}_{datetime}_{name|update}.py`.\n\nIf `aerich` guesses you are renaming a column, it will ask `Rename {old_column} to {new_column} [True]`. You can choose\n`True` to rename column without column drop, or choose `False` to drop the column then create. Note that the latter may\nlose data.\n\nIf you need to manually write migration, you could generate empty file:\n\n```shell\n\u003e aerich migrate --name add_index --empty\n\nSuccess migrate 1_202326122220101229_add_index.py\n```\n\n### Upgrade to latest version\n\n```shell\n\u003e aerich upgrade\n\nSuccess upgrade 1_202029051520102929_drop_column.py\n```\n\nNow your db is migrated to latest.\n\n### Downgrade to specified version\n\n```shell\n\u003e aerich downgrade -h\n\nUsage: aerich downgrade [OPTIONS]\n\n  Downgrade to specified version.\n\nOptions:\n  -v, --version INTEGER  Specified version, default to last.  [default: -1]\n  -d, --delete           Delete version files at the same time.  [default:\n                         False]\n\n  --yes                  Confirm the action without prompting.\n  -h, --help             Show this message and exit.\n```\n\n```shell\n\u003e aerich downgrade\n\nSuccess downgrade 1_202029051520102929_drop_column.py\n```\n\nNow your db is rolled back to the specified version.\n\n### Show history\n\n```shell\n\u003e aerich history\n\n1_202029051520102929_drop_column.py\n```\n\n### Show heads to be migrated\n\n```shell\n\u003e aerich heads\n\n1_202029051520102929_drop_column.py\n```\n\n### Inspect db tables to TortoiseORM model\n\nCurrently `inspectdb` support MySQL \u0026 Postgres \u0026 SQLite.\n\n```shell\nUsage: aerich inspectdb [OPTIONS]\n\n  Introspects the database tables to standard output as TortoiseORM model.\n\nOptions:\n  -t, --table TEXT  Which tables to inspect.\n  -h, --help        Show this message and exit.\n```\n\nInspect all tables and print to console:\n\n```shell\naerich --app models inspectdb\n```\n\nInspect a specified table in the default app and redirect to `models.py`:\n\n```shell\naerich inspectdb -t user \u003e models.py\n```\n\nFor example, you table is:\n\n```sql\nCREATE TABLE `test`\n(\n    `id`       int            NOT NULL AUTO_INCREMENT,\n    `decimal`  decimal(10, 2) NOT NULL,\n    `date`     date                                    DEFAULT NULL,\n    `datetime` datetime       NOT NULL                 DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,\n    `time`     time                                    DEFAULT NULL,\n    `float`    float                                   DEFAULT NULL,\n    `string`   varchar(200) COLLATE utf8mb4_general_ci DEFAULT NULL,\n    `tinyint`  tinyint                                 DEFAULT NULL,\n    PRIMARY KEY (`id`),\n    KEY `asyncmy_string_index` (`string`)\n) ENGINE = InnoDB\n  DEFAULT CHARSET = utf8mb4\n  COLLATE = utf8mb4_general_ci\n```\n\nNow run `aerich inspectdb -t test` to see the generated model:\n\n```python\nfrom tortoise import Model, fields\n\n\nclass Test(Model):\n    date = fields.DateField(null=True)\n    datetime = fields.DatetimeField(auto_now=True)\n    decimal = fields.DecimalField(max_digits=10, decimal_places=2)\n    float = fields.FloatField(null=True)\n    id = fields.IntField(primary_key=True)\n    string = fields.CharField(max_length=200, null=True)\n    time = fields.TimeField(null=True)\n    tinyint = fields.BooleanField(null=True)\n```\n\nNote that this command is limited and can't infer some fields, such as `IntEnumField`, `ForeignKeyField`, and others.\n\n### Multiple databases\n\n```python\ntortoise_orm = {\n    \"connections\": {\n        \"default\": \"postgres://postgres_user:postgres_pass@127.0.0.1:5432/db1\",\n        \"second\": \"postgres://postgres_user:postgres_pass@127.0.0.1:5432/db2\",\n    },\n    \"apps\": {\n        \"models\": {\"models\": [\"tests.models\", \"aerich.models\"], \"default_connection\": \"default\"},\n        \"models_second\": {\"models\": [\"tests.models_second\"], \"default_connection\": \"second\", },\n    },\n}\n```\n\nYou only need to specify `aerich.models` in one app, and must specify `--app` when running `aerich migrate` and so on, e.g. `aerich --app models_second migrate`.\n\n## Restore `aerich` workflow\n\nIn some cases, such as broken changes from upgrade of `aerich`, you can't run `aerich migrate` or `aerich upgrade`, you\ncan make the following steps:\n\n1. drop `aerich` table.\n2. delete `migrations/{app}` directory.\n3. rerun `aerich init-db`.\n\nNote that these actions is safe, also you can do that to reset your migrations if your migration files is too many.\n\n## Use `aerich` in application\n\nYou can use `aerich` out of cli by use `Command` class.\n\n```python\nfrom aerich import Command\n\nasync with Command(tortoise_config=config, app='models') as command:\n    await command.migrate('test')\n    await command.upgrade()\n```\n\n## Upgrade/Downgrade with `--fake` option\n\nMarks the migrations up to the latest one(or back to the target one) as applied, but without actually running the SQL to change your database schema.\n\n- Upgrade\n\n```bash\naerich upgrade --fake\naerich --app models upgrade --fake\n```\n- Downgrade\n\n```bash\naerich downgrade --fake -v 2\naerich --app models downgrade --fake -v 2\n```\n\n### Ignore tables\n\nYou can tell aerich to ignore table by setting `managed=False` in the `Meta` class, e.g.:\n```py\nclass MyModel(Model):\n    class Meta:\n        managed = False\n```\n**Note** `managed=False` does not recognized by `tortoise-orm` and `aerich init-db`, it is only for `aerich migrate`.\n\n## License\n\nThis project is licensed under the\n[Apache-2.0](https://github.com/long2ice/aerich/blob/master/LICENSE) License.\n","funding_links":["https://sponsor.long2ice.io"],"categories":["Python","Third-Party Extensions"],"sub_categories":["Databases"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftortoise%2Faerich","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftortoise%2Faerich","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftortoise%2Faerich/lists"}