1 files changed, 23 insertions, 0 deletions

diff --git a/src/mailman/docs/DATABASE.rst b/src/mailman/docs/DATABASE.rst
index 688a989e6..f0773f1f9 100644
--- a/src/mailman/docs/DATABASE.rst
+++ b/src/mailman/docs/DATABASE.rst
@@ -59,8 +59,31 @@ it::
 My thanks to Stephen A. Goss for his contribution of PostgreSQL support.
 
 
+Database Migrations
+===================
+
+Mailman uses `Alembic`_ to manage database migrations. Lets say you change
+something in the models, what steps are needed to reflect that change in
+the database schema? All you need to do is run this command::
+
+    alembic -c src/mailman/config/alembic.cfg revision --autogenerate
+
+This would create a new migration which would automatically be migrated to the
+database on the next run of mailman. Note that the database needs to be in the
+older state so that alembic can track the changes in the schema and autogenerate
+a migration. If you don't have the database in the older state you can remove
+the `--autogenerate` flag in the above command. It would then create a new empty
+revision which you can edit manually to reflect your changes in the database
+schema.
+
+People upgrading Mailman from previous versions need not do anything manually,
+as soon as a new migration is added in the sources, it will be automatically
+reflected in the schema on first-run post-update.
+
+
 .. _SQLAlchemy: http://www.sqlalchemy.org/
 .. _SQLite3: http://docs.python.org/library/sqlite3.html
 .. _PostgreSQL: http://www.postgresql.org/
 .. _MySQL: http://dev.mysql.com/
 .. _`Ubuntu article`: https://help.ubuntu.com/community/PostgreSQL
+.. _`Alembic`: https://alembic.readthedocs.org/en/latest/