From: Vlastimil Zíma <vlastimil.zima@nic.cz>
Date: Sat, 4 Jun 2022 14:28:36 +0000 (-0400)
Subject: Add docs for data migrations
X-Git-Tag: rel_1_10_3~3
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=79958bf68da0684ec7c7ffe90b1c5a41360c5906;p=thirdparty%2Fsqlalchemy%2Falembic.git

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

diff --git a/docs/build/cookbook.rst b/docs/build/cookbook.rst
index 58a65ea5..d05bd407 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.