0
# Revision Management
1
2
Functions for managing migration revisions, including editing, merging, and stamping operations. These commands provide advanced revision control capabilities for complex migration scenarios.
3
4
## Capabilities
5
6
### Revision Editing
7
8
Edit an existing revision file, useful for making corrections or additions to migration scripts.
9
10
```python { .api }
11
def edit(directory=None, revision='current'):
12
"""
13
Edit current revision.
14
15
Parameters:
16
- directory: Migration directory path (optional, uses app extension config if None)
17
- revision: Revision to edit (default: 'current')
18
19
Raises:
20
- RuntimeError: If Alembic version is less than 0.8.0
21
- CommandError: If editing fails
22
"""
23
```
24
25
### Revision Merging
26
27
Merge two revisions together, creating a new migration file that resolves branching in the migration history.
28
29
```python { .api }
30
def merge(directory=None, revisions='', message=None, branch_label=None,
31
rev_id=None):
32
"""
33
Merge two revisions together, creating a new migration file.
34
35
Parameters:
36
- directory: Migration directory path (optional, uses app extension config if None)
37
- revisions: Revisions to merge (space-separated string, default: '')
38
- message: Merge revision message (optional)
39
- branch_label: Branch label to apply to the new revision (optional)
40
- rev_id: Hardcoded revision id instead of generating one (optional)
41
42
Raises:
43
- CommandError: If merge fails
44
- RuntimeError: If Flask application context is not available
45
"""
46
```
47
48
### Revision Stamping
49
50
Mark the revision table with a given revision without running any migrations. Useful for synchronizing the database state with the migration history.
51
52
```python { .api }
53
def stamp(directory=None, revision='head', sql=False, tag=None, purge=False):
54
"""
55
'stamp' the revision table with the given revision; don't run any migrations.
56
57
Parameters:
58
- directory: Migration directory path (optional, uses app extension config if None)
59
- revision: Revision to stamp (default: 'head')
60
- sql: Generate SQL output instead of executing (default: False)
61
- tag: Arbitrary tag name for custom env.py scripts (optional)
62
- purge: Delete existing version before stamping (default: False)
63
64
Raises:
65
- CommandError: If stamping fails
66
- RuntimeError: If Flask application context is not available
67
"""
68
```
69
70
## Usage Examples
71
72
### Editing Revisions
73
74
```python
75
from flask_migrate import edit
76
77
# Edit the current revision
78
edit()
79
80
# Edit a specific revision
81
edit(revision="abc123def456")
82
```
83
84
### Merging Branches
85
86
```python
87
from flask_migrate import merge
88
89
# Merge two revisions
90
merge(revisions="abc123 def456", message="Merge feature and bugfix branches")
91
92
# Merge with branch label
93
merge(
94
revisions="abc123 def456",
95
message="Merge branches",
96
branch_label="production"
97
)
98
```
99
100
### Stamping Database State
101
102
```python
103
from flask_migrate import stamp
104
105
# Stamp database as being at head revision
106
stamp()
107
108
# Stamp with specific revision
109
stamp(revision="abc123def456")
110
111
# Generate stamp SQL without executing
112
stamp(sql=True)
113
114
# Purge existing version before stamping
115
stamp(purge=True)
116
```
117
118
### Advanced Revision Management
119
120
```python
121
from flask_migrate import stamp, merge
122
123
# Synchronize database with migration history after manual changes
124
stamp(revision="current_actual_state")
125
126
# Resolve complex branching scenario
127
merge(
128
revisions="branch1_head branch2_head",
129
message="Resolve parallel development branches",
130
branch_label="unified"
131
)
132
```
133
134
### Database State Recovery
135
136
```python
137
from flask_migrate import stamp
138
139
# Recovery scenario: mark database as being at a known good state
140
# without running migrations (useful after manual schema changes)
141
stamp(revision="known_good_revision", purge=True)
142
```