diff options
author | Vlastimil Zíma <vlastimil.zima@nic.cz> | 2022-06-04 10:28:36 -0400 |
---|---|---|
committer | CaselIT <cfederico87@gmail.com> | 2023-04-02 10:47:01 +0200 |
commit | 79958bf68da0684ec7c7ffe90b1c5a41360c5906 (patch) | |
tree | d0c76862f6407e9f8a9ddfd3455e6626b0d5057d /docs/build | |
parent | bc0c305b7c2cc0401e250fcd6a725aacecdd6e33 (diff) | |
download | alembic-79958bf68da0684ec7c7ffe90b1c5a41360c5906.tar.gz |
Add docs for data migrations
### Description
I added a small docs regarding data migrations, based on #972.
### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)
-->
This pull request is:
- [X] A documentation / typographical error fix
- Good to go, no issue or tests are needed
**Have a nice day!**
Closes: #1040
Pull-request: https://github.com/sqlalchemy/alembic/pull/1040
Pull-request-sha: c985e0d8096e750df35aa07dde71f432a57656b6
Change-Id: Icf6fdb1089eb7c386dad4401b99caaddc352d92f
Diffstat (limited to 'docs/build')
-rw-r--r-- | docs/build/cookbook.rst | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/docs/build/cookbook.rst b/docs/build/cookbook.rst index 58a65ea..d05bd40 100644 --- a/docs/build/cookbook.rst +++ b/docs/build/cookbook.rst @@ -1554,3 +1554,46 @@ the same ``env.py`` file can be invoked using asyncio as:: asyncio.run(run_async_upgrade()) + +Data Migrations - General Techniques +==================================== + +Alembic migrations are designed for schema migrations. +The nature of data migrations are inherently different and it's not in fact advisable +in the general case to write data migrations that integrate with Alembic's +schema versioning model. +For example downgrades are difficult to address since they might require deletion of data, +which may even not be possible to detect. + +.. warning:: + + The solution needs to be designed specifically for each individual application and migration. + There are no general rules and the following text is only a recommendation based on experience. + +There are three basic approaches for the data migrations. + +Small data +---------- + +Small data migrations are easy to perform, especially in cases of initial data to a new table. +These can be handled using :meth:`.Operations.bulk_insert`. + +Separate migration script +------------------------- + +One possibility is a completely separate script aside of alembic migrations. +The complete migration is then processed in following steps: + +1. Run the initial alembic migrations (new columns etc.) +2. Run the separate data migration script +3. Run the final alembic migrations (database constraints, delete columns etc.) + +The data migration script may also need a separate ORM model to handle intermediate state of the database. + +Online migration +---------------- + +The application maintains a version of schema with both versions. +Writes are performed on both places, while the background script move all the remaining data across. +This technique is very challenging and time demanding, since it requires custom application logic to +handle the intermediate states. |