~abompard/mailman/mailman-templates-utf8

« back to all changes in this revision

Viewing changes to src/mailman/docs/DATABASE.rst

  • Committer: Barry Warsaw
  • Date: 2015-01-20 22:37:20 UTC
  • mfrom: (7288.1.3 mailman-maxking)
  • Revision ID: barry@list.org-20150120223720-c05vtjylqvhmkiht
 * Improve the documentation describing how to run Alembic to add new schema
   migrations.  Given by Abhilash Raj.

Show diffs side-by-side

added added

removed removed

Lines of Context:
59
59
My thanks to Stephen A. Goss for his contribution of PostgreSQL support.
60
60
 
61
61
 
 
62
Database Migrations
 
63
===================
 
64
 
 
65
Mailman uses `Alembic`_ to manage database migrations.  Let's say you change
 
66
something in the models, what steps are needed to reflect that change in the
 
67
database schema?  You need to create and enter a virtual environment, install
 
68
Mailman into that, and then run the ``alembic`` command.  For example::
 
69
 
 
70
    $ virtualenv -p python3 /tmp/mm3
 
71
    $ source /tmp/mm3/bin/activate
 
72
    $ python setup.py develop
 
73
    $ alembic -c src/mailman/config/alembic.cfg revision --autogenerate
 
74
 
 
75
This would create a new migration which would automatically be migrated to the
 
76
database on the next run of Mailman.  Note that the database needs to be in
 
77
the older state so that Alembic can track the changes in the schema and
 
78
autogenerate a migration.  If you don't have the database in the older state
 
79
you can remove the `--autogenerate` flag in the above command.  It would then
 
80
create a new empty revision which you can edit manually to reflect your
 
81
changes in the database schema.
 
82
 
 
83
People upgrading Mailman from previous versions need not do anything manually,
 
84
as soon as a new migration is added in the sources, it will be automatically
 
85
reflected in the schema on first-run post-update.
 
86
 
 
87
 
62
88
.. _SQLAlchemy: http://www.sqlalchemy.org/
63
89
.. _SQLite3: http://docs.python.org/library/sqlite3.html
64
90
.. _PostgreSQL: http://www.postgresql.org/
65
91
.. _MySQL: http://dev.mysql.com/
66
92
.. _`Ubuntu article`: https://help.ubuntu.com/community/PostgreSQL
 
93
.. _`Alembic`: https://alembic.readthedocs.org/en/latest/