0
# Information Commands
1
2
Functions for inspecting migration history, current state, and repository status. These commands provide visibility into the migration repository and database state without making changes.
3
4
## Capabilities
5
6
### Revision Display
7
8
Show detailed information about a specific revision.
9
10
```python { .api }
11
def show(directory=None, revision='head'):
12
"""
13
Show the revision denoted by the given symbol.
14
15
Parameters:
16
- directory: Migration directory path (optional, uses app extension config if None)
17
- revision: Revision to show (default: 'head')
18
19
Raises:
20
- CommandError: If revision cannot be found or displayed
21
- RuntimeError: If Flask application context is not available
22
"""
23
```
24
25
### Migration History
26
27
List all changeset scripts in chronological order, providing an overview of the migration timeline.
28
29
```python { .api }
30
def history(directory=None, rev_range=None, verbose=False,
31
indicate_current=False):
32
"""
33
List changeset scripts in chronological order.
34
35
Parameters:
36
- directory: Migration directory path (optional, uses app extension config if None)
37
- rev_range: Revision range filter in format [start]:[end] (optional)
38
- verbose: Use more verbose output (default: False)
39
- indicate_current: Indicate current version - requires Alembic 0.9.9+ (default: False)
40
41
Raises:
42
- CommandError: If history cannot be retrieved
43
- RuntimeError: If Flask application context is not available
44
"""
45
```
46
47
### Head Revisions
48
49
Show current available heads in the script directory, useful for identifying branch points.
50
51
```python { .api }
52
def heads(directory=None, verbose=False, resolve_dependencies=False):
53
"""
54
Show current available heads in the script directory.
55
56
Parameters:
57
- directory: Migration directory path (optional, uses app extension config if None)
58
- verbose: Use more verbose output (default: False)
59
- resolve_dependencies: Treat dependency versions as down revisions (default: False)
60
61
Raises:
62
- CommandError: If heads cannot be retrieved
63
- RuntimeError: If Flask application context is not available
64
"""
65
```
66
67
### Branch Points
68
69
Show current branch points in the migration history.
70
71
```python { .api }
72
def branches(directory=None, verbose=False):
73
"""
74
Show current branch points.
75
76
Parameters:
77
- directory: Migration directory path (optional, uses app extension config if None)
78
- verbose: Use more verbose output (default: False)
79
80
Raises:
81
- CommandError: If branches cannot be retrieved
82
- RuntimeError: If Flask application context is not available
83
"""
84
```
85
86
### Current Revision
87
88
Display the current revision for each database, showing the actual state of the database.
89
90
```python { .api }
91
def current(directory=None, verbose=False):
92
"""
93
Display the current revision for each database.
94
95
Parameters:
96
- directory: Migration directory path (optional, uses app extension config if None)
97
- verbose: Use more verbose output (default: False)
98
99
Raises:
100
- CommandError: If current revision cannot be determined
101
- RuntimeError: If Flask application context is not available
102
"""
103
```
104
105
### Migration Check
106
107
Check if there are any new operations to migrate by comparing the current database state with model definitions.
108
109
```python { .api }
110
def check(directory=None):
111
"""
112
Check if there are any new operations to migrate.
113
114
Parameters:
115
- directory: Migration directory path (optional, uses app extension config if None)
116
117
Raises:
118
- CommandError: If check fails or if there are pending migrations
119
- RuntimeError: If Flask application context is not available
120
"""
121
```
122
123
### Template Listing
124
125
List all available migration templates that can be used for repository initialization.
126
127
```python { .api }
128
def list_templates():
129
"""
130
List available templates.
131
132
Raises:
133
- CommandError: If templates cannot be listed
134
"""
135
```
136
137
## Usage Examples
138
139
### Basic Information Queries
140
141
```python
142
from flask_migrate import show, current, history
143
144
# Show information about the head revision
145
show()
146
147
# Show specific revision
148
show(revision="abc123def456")
149
150
# Display current database revision
151
current()
152
153
# Show migration history
154
history()
155
```
156
157
### Detailed History Analysis
158
159
```python
160
from flask_migrate import history, heads, branches
161
162
# Show verbose history
163
history(verbose=True)
164
165
# Show history for specific range
166
history(rev_range="abc123:def456")
167
168
# Show history with current revision indicated (Alembic 0.9.9+)
169
history(indicate_current=True)
170
171
# Show all head revisions
172
heads(verbose=True)
173
174
# Show branch points
175
branches(verbose=True)
176
```
177
178
### Repository Status Checking
179
180
```python
181
from flask_migrate import check, current, heads
182
183
# Check if migrations are needed
184
try:
185
check()
186
print("No pending migrations")
187
except CommandError:
188
print("Migrations needed")
189
190
# Get comprehensive status
191
current()
192
heads()
193
```
194
195
### Template Discovery
196
197
```python
198
from flask_migrate import list_templates
199
200
# List all available templates
201
list_templates()
202
```
203
204
### Advanced Information Gathering
205
206
```python
207
from flask_migrate import history, heads, branches, current
208
209
def migration_status_report():
210
"""Generate comprehensive migration status report."""
211
print("=== Current Database State ===")
212
current(verbose=True)
213
214
print("\n=== Available Heads ===")
215
heads(verbose=True, resolve_dependencies=True)
216
217
print("\n=== Branch Points ===")
218
branches(verbose=True)
219
220
print("\n=== Recent History ===")
221
history(verbose=True, rev_range="-5:")
222
223
# Run status report
224
migration_status_report()
225
```