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 58a65ea5a8aae1c0472ec9becfd524f9226ccbc2..d05bd4071d81c5ef6b59a9242bfa0c3b2fd30b93 100644 (file)
--- 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.