0
# Migration Operations
1

2
Essential migration commands for creating, applying, and managing database schema changes. These functions form the core workflow of database migration management.
3

4
## Capabilities
5

6
### Repository Initialization
7

8
Create a new migration repository with the necessary directory structure and configuration files.
9

10
```python { .api }
11
def init(directory=None, multidb=False, template=None, package=False):
12
    """
13
    Creates a new migration repository.
14

15
    Parameters:
16
    - directory: Migration directory path (optional, uses app extension config if None)
17
    - multidb: Support multiple databases (default: False)
18
    - template: Repository template name (optional, defaults to 'flask' or 'flask-multidb')
19
    - package: Write empty __init__.py files to environment and version locations (default: False)
20

21
    Raises:
22
    - CommandError: If repository initialization fails
23
    - RuntimeError: If Flask application context is not available
24
    """
25
```
26

27
### Manual Revision Creation
28

29
Create a new revision file manually, optionally with auto-generated migration operations based on model changes.
30

31
```python { .api }
32
def revision(directory=None, message=None, autogenerate=False, sql=False,
33
             head='head', splice=False, branch_label=None, version_path=None,
34
             rev_id=None):
35
    """
36
    Create a new revision file.
37

38
    Parameters:
39
    - directory: Migration directory path (optional, uses app extension config if None)
40
    - message: Revision message (optional)
41
    - autogenerate: Populate revision with candidate migration operations (default: False)
42
    - sql: Generate SQL output instead of executing (default: False)
43
    - head: Head revision or <branchname>@head to base new revision on (default: 'head')
44
    - splice: Allow non-head revision as the "head" to splice onto (default: False)
45
    - branch_label: Branch label to apply to the new revision (optional)
46
    - version_path: Specific path from config for version file (optional)
47
    - rev_id: Hardcoded revision id instead of generating one (optional)
48

49
    Raises:
50
    - CommandError: If revision creation fails
51
    - RuntimeError: If Flask application context is not available
52
    """
53
```
54

55
### Automatic Migration Generation
56

57
Generate a migration automatically by comparing the current database state with the model definitions.
58

59
```python { .api }
60
def migrate(directory=None, message=None, sql=False, head='head', splice=False,
61
            branch_label=None, version_path=None, rev_id=None, x_arg=None):
62
    """
63
    Autogenerate a new revision file (Alias for 'revision --autogenerate').
64

65
    Parameters:
66
    - directory: Migration directory path (optional, uses app extension config if None)
67
    - message: Revision message (optional)
68
    - sql: Generate SQL output instead of executing (default: False)
69
    - head: Head revision or <branchname>@head to base new revision on (default: 'head')
70
    - splice: Allow non-head revision as the "head" to splice onto (default: False)
71
    - branch_label: Branch label to apply to the new revision (optional)
72
    - version_path: Specific path from config for version file (optional)
73
    - rev_id: Hardcoded revision id instead of generating one (optional)
74
    - x_arg: Additional arguments consumed by custom env.py scripts (list, optional)
75

76
    Raises:
77
    - CommandError: If migration generation fails
78
    - RuntimeError: If Flask application context is not available
79
    """
80
```
81

82
### Database Upgrade
83

84
Apply migrations to upgrade the database to a later version.
85

86
```python { .api }
87
def upgrade(directory=None, revision='head', sql=False, tag=None, x_arg=None):
88
    """
89
    Upgrade to a later version.
90

91
    Parameters:
92
    - directory: Migration directory path (optional, uses app extension config if None)
93
    - revision: Target revision (default: 'head')
94
    - sql: Generate SQL output instead of executing (default: False)
95
    - tag: Arbitrary tag name for custom env.py scripts (optional)
96
    - x_arg: Additional arguments consumed by custom env.py scripts (list, optional)
97

98
    Raises:
99
    - CommandError: If upgrade fails
100
    - RuntimeError: If Flask application context is not available
101
    """
102
```
103

104
### Database Downgrade
105

106
Revert the database to a previous version by applying downgrade operations.
107

108
```python { .api }
109
def downgrade(directory=None, revision='-1', sql=False, tag=None, x_arg=None):
110
    """
111
    Revert to a previous version.
112

113
    Parameters:
114
    - directory: Migration directory path (optional, uses app extension config if None)
115
    - revision: Target revision (default: '-1' for one step back)
116
    - sql: Generate SQL output instead of executing (default: False)
117
    - tag: Arbitrary tag name for custom env.py scripts (optional)
118
    - x_arg: Additional arguments consumed by custom env.py scripts (list, optional)
119

120
    Raises:
121
    - CommandError: If downgrade fails
122
    - RuntimeError: If Flask application context is not available
123
    """
124
```
125

126
## Usage Examples
127

128
### Basic Migration Workflow
129

130
```python
131
from flask_migrate import init, migrate, upgrade
132

133
# Initialize migration repository
134
init()
135

136
# Generate migration after model changes
137
migrate(message="Add user table")
138

139
# Apply migration to database
140
upgrade()
141
```
142

143
### Advanced Migration Operations
144

145
```python
146
from flask_migrate import revision, upgrade, downgrade
147

148
# Create manual revision
149
revision(message="Custom migration", autogenerate=False)
150

151
# Upgrade to specific revision
152
upgrade(revision="abc123")
153

154
# Downgrade two steps
155
downgrade(revision="-2")
156

157
# Generate SQL without executing
158
upgrade(sql=True)
159
```
160

161
### Multi-database Setup
162

163
```python
164
from flask_migrate import init, migrate
165

166
# Initialize with multi-database support
167
init(multidb=True)
168

169
# Generate migration with custom env.py arguments
170
migrate(message="Multi-db changes", x_arg=['--database', 'users'])
171
```
172

173
### Custom Templates
174

175
```python
176
from flask_migrate import init
177

178
# Use custom template
179
init(template="custom-template")
180

181
# Use async Flask template
182
init(template="aioflask")
183
```