← Back to branch summary

~jimmy-sigint/mailman/atomia_package_branch

« back to all changes in this revision

Viewing changes to src/mailman/database/docs/migration.rst

  • Committer: Barry Warsaw
  • Date: 2012-07-26 04:22:19 UTC
  • mfrom: (7149.2.19 bug-971013)
  • Revision ID: barry@list.org-20120726042219-o4asb3r7f6hil65t
 * The policy for archiving has now been collapsed into a single enum, called
   ArchivePolicy.  This describes the three states of never archive, archive
   privately, and archive_publicly. (LP: #967238)

Database
--------
 * Schema migrations (LP: #971013)
   - include_list_post_header -> allow_list_posts
   - news_prefix_subject_too  -> nntp_prefix_subject_too
   - news_moderation          -> newsgroup_moderation
   - archive and archive_private have been collapsed into archive_policy.
   - nntp_host has been removed.
 * The PostgreSQL port of the schema accidentally added a moderation_callback
   column to the mailinglist table.  Since this is unused in Mailman, it was
   simply commented out of the base schema for PostgreSQL.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mailman/database/docs/migration.rst
24
24
applied at any time by calling in the API directly.  Once applied, a
25
25
migration's version string is registered so it will not be applied again.
26
26
 
27
 
We see that the base migration is already applied.
 
27
We see that the base migration, as well as subsequent standard migrations, are
 
28
already applied.
28
29
 
29
30
    >>> from mailman.model.version import Version
30
31
    >>> results = config.db.store.find(Version, component='schema')
31
32
    >>> results.count()
32
 
    1
33
 
    >>> base = results.one()
34
 
    >>> print base.component
35
 
    schema
36
 
    >>> print base.version
 
33
    2
 
34
    >>> versions = sorted(result.version for result in results)
 
35
    >>> for version in versions:
 
36
    ...     print version
37
37
    00000000000000
 
38
    20120407000000
38
39
 
39
40
 
40
41
Migrations
55
56
    ... migrations_path: migrations
56
57
    ... """)
57
58
 
 
59
.. Clean this up at the end of the doctest.
 
60
    >>> def cleanup():
 
61
    ...     import shutil
 
62
    ...     from mailman.config import config
 
63
    ...     config.pop('migrations')
 
64
    ...     shutil.rmtree(tempdir)
 
65
    >>> cleanups.append(cleanup)
 
66
 
58
67
Here is an example migrations module.  The key part of this interface is the
59
68
``upgrade()`` method, which takes four arguments:
60
69
 
69
78
 
70
79
    >>> with open(os.path.join(path, '__init__.py'), 'w') as fp:
71
80
    ...     pass
72
 
    >>> with open(os.path.join(path, 'mm_20120211000000.py'), 'w') as fp:
 
81
    >>> with open(os.path.join(path, 'mm_20129999000000.py'), 'w') as fp:
73
82
    ...     print >> fp, """
74
83
    ... from __future__ import unicode_literals
75
84
    ... from mailman.model.version import Version
86
95
    >>> for result in sorted(result.version for result in results):
87
96
    ...     print result
88
97
    00000000000000
89
 
    20120211000000
 
98
    20120407000000
 
99
    20129999000000
90
100
    >>> test = config.db.store.find(Version, component='test').one()
91
101
    >>> print test.version
92
 
    20120211000000
 
102
    20129999000000
93
103
 
94
104
Migrations will only be loaded once.
95
105
 
96
 
    >>> with open(os.path.join(path, 'mm_20120211000001.py'), 'w') as fp:
 
106
    >>> with open(os.path.join(path, 'mm_20129999000001.py'), 'w') as fp:
97
107
    ...     print >> fp, """
98
108
    ... from __future__ import unicode_literals
99
109
    ... from mailman.model.version import Version
115
125
    >>> for result in sorted(result.version for result in results):
116
126
    ...     print result
117
127
    00000000000000
118
 
    20120211000000
119
 
    20120211000001
 
128
    20120407000000
 
129
    20129999000000
 
130
    20129999000001
120
131
    >>> test = config.db.store.find(Version, component='test')
121
132
    >>> for marker in sorted(marker.version for marker in test):
122
133
    ...     print marker
123
134
    00000000000801
124
 
    20120211000000
 
135
    20129999000000
125
136
 
126
137
We do not get an 802 marker because the migration has already been loaded.
127
138
 
130
141
    >>> for result in sorted(result.version for result in results):
131
142
    ...     print result
132
143
    00000000000000
133
 
    20120211000000
134
 
    20120211000001
 
144
    20120407000000
 
145
    20129999000000
 
146
    20129999000001
135
147
    >>> test = config.db.store.find(Version, component='test')
136
148
    >>> for marker in sorted(marker.version for marker in test):
137
149
    ...     print marker
138
150
    00000000000801
139
 
    20120211000000
140
 
 
141
 
.. Clean up the temporary directory::
142
 
 
143
 
    >>> config.pop('migrations')
144
 
    >>> sys.path.remove(tempdir)
145
 
    >>> import shutil
146
 
    >>> shutil.rmtree(tempdir)
 
151
    20129999000000
 
152
 
 
153
 
 
154
Partial upgrades
 
155
================
 
156
 
 
157
It's possible (mostly for testing purposes) to only do a partial upgrade, by
 
158
providing a timestamp to `load_migrations()`.  To demonstrate this, we add two
 
159
additional migrations, intended to be applied in sequential order.
 
160
 
 
161
    >>> from shutil import copyfile
 
162
    >>> from mailman.testing.helpers import chdir
 
163
    >>> with chdir(path):
 
164
    ...     copyfile('mm_20129999000000.py', 'mm_20129999000002.py')
 
165
    ...     copyfile('mm_20129999000000.py', 'mm_20129999000003.py')
 
166
    ...     copyfile('mm_20129999000000.py', 'mm_20129999000004.py')
 
167
 
 
168
Now, only migrate to the ...03 timestamp.
 
169
 
 
170
    >>> config.db.load_migrations('20129999000003')
 
171
 
 
172
You'll notice that the ...04 version is not present.
 
173
 
 
174
    >>> results = config.db.store.find(Version, component='schema')
 
175
    >>> for result in sorted(result.version for result in results):
 
176
    ...     print result
 
177
    00000000000000
 
178
    20120407000000
 
179
    20129999000000
 
180
    20129999000001
 
181
    20129999000002
 
182
    20129999000003