0
# Flask-Migrate
1

2
Flask-Migrate is a Flask extension that handles SQLAlchemy database migrations for Flask applications using Alembic. It provides both a programmatic API and command-line interface for managing database schema changes, creating migration scripts, and applying upgrades/downgrades.
3

4
## Package Information
5

6
- **Package Name**: Flask-Migrate
7
- **Language**: Python
8
- **Installation**: `pip install Flask-Migrate`
9

10
## Core Imports
11

12
```python
13
from flask_migrate import Migrate
14
```
15

16
For individual migration functions:
17

18
```python
19
from flask_migrate import init, revision, migrate, upgrade, downgrade
20
```
21

22
## Basic Usage
23

24
```python
25
from flask import Flask
26
from flask_sqlalchemy import SQLAlchemy
27
from flask_migrate import Migrate
28

29
app = Flask(__name__)
30
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'
31

32
db = SQLAlchemy(app)
33
migrate = Migrate(app, db)
34

35
class User(db.Model):
36
    id = db.Column(db.Integer, primary_key=True)
37
    name = db.Column(db.String(128))
38

39
# Initialize migration repository
40
# flask db init
41

42
# Generate migration
43
# flask db migrate -m "Add user table"
44

45
# Apply migration
46
# flask db upgrade
47
```
48

49
## Architecture
50

51
Flask-Migrate provides a Flask extension pattern with both programmatic and CLI interfaces:
52

53
- **Migrate class**: Main extension that integrates with Flask apps and provides configuration
54
- **Migration functions**: Programmatic API functions for all migration operations
55
- **CLI interface**: Flask CLI commands accessible via `flask db` for command-line usage
56
- **Templates**: Pre-configured migration environments for different Flask setups
57
- **Configuration system**: Callback-based configuration with Alembic integration
58

59
## Capabilities
60

61
### Core Extension
62

63
The main Flask-Migrate extension class that integrates database migration functionality into Flask applications.
64

65
```python { .api }
66
class Migrate:
67
    def __init__(self, app=None, db=None, directory='migrations', command='db',
68
                 compare_type=True, render_as_batch=True, **kwargs): ...
69
    def init_app(self, app, db=None, directory=None, command=None,
70
                 compare_type=None, render_as_batch=None, **kwargs): ...
71
    def configure(self, f): ...
72
    def get_config(self, directory=None, x_arg=None, opts=None): ...
73
```
74

75
[Core Extension](./core-extension.md)
76

77
### Migration Operations
78

79
Essential migration commands for creating, applying, and managing database schema changes.
80

81
```python { .api }
82
def init(directory=None, multidb=False, template=None, package=False): ...
83
def revision(directory=None, message=None, autogenerate=False, sql=False,
84
             head='head', splice=False, branch_label=None, version_path=None,
85
             rev_id=None): ...
86
def migrate(directory=None, message=None, sql=False, head='head', splice=False,
87
            branch_label=None, version_path=None, rev_id=None, x_arg=None): ...
88
def upgrade(directory=None, revision='head', sql=False, tag=None, x_arg=None): ...
89
def downgrade(directory=None, revision='-1', sql=False, tag=None, x_arg=None): ...
90
```
91

92
[Migration Operations](./migration-operations.md)
93

94
### Revision Management
95

96
Functions for managing migration revisions, including editing, merging, and stamping operations.
97

98
```python { .api }
99
def edit(directory=None, revision='current'): ...
100
def merge(directory=None, revisions='', message=None, branch_label=None,
101
          rev_id=None): ...
102
def stamp(directory=None, revision='head', sql=False, tag=None, purge=False): ...
103
```
104

105
[Revision Management](./revision-management.md)
106

107
### Information Commands  
108

109
Functions for inspecting migration history, current state, and repository status.
110

111
```python { .api }
112
def show(directory=None, revision='head'): ...
113
def history(directory=None, rev_range=None, verbose=False,
114
            indicate_current=False): ...
115
def heads(directory=None, verbose=False, resolve_dependencies=False): ...
116
def branches(directory=None, verbose=False): ...
117
def current(directory=None, verbose=False): ...
118
def check(directory=None): ...
119
def list_templates(): ...
120
```
121

122
[Information Commands](./information-commands.md)
123

124
### CLI Interface
125

126
Flask CLI integration that provides command-line access to all migration functionality through the `flask db` command group.
127

128
```python { .api }
129
@click.group()
130
def db(directory, x_arg): ...
131
```
132

133
[CLI Interface](./cli-interface.md)
134

135
## Configuration Classes
136

137
```python { .api }
138
class Config(AlembicConfig):
139
    """Extended Alembic configuration with template directory support."""
140
    def __init__(self, *args, template_directory=None, **kwargs): ...
141
    def get_template_directory(self): ...
142

143
class _MigrateConfig:
144
    """Configuration wrapper for backwards compatibility."""
145
    def __init__(self, migrate, db, **kwargs): ...
146
    @property
147
    def metadata(self): ...
148
```
149

150
## Utility Functions
151

152
```python { .api }
153
def catch_errors(f):
154
    """Decorator that catches CommandError and RuntimeError exceptions."""
155
```
156

157
## Available Templates
158

159
- **flask**: Single-database configuration for Flask applications
160
- **flask-multidb**: Multi-database configuration for Flask applications  
161
- **aioflask**: Single-database configuration for async Flask applications
162
- **aioflask-multidb**: Multi-database configuration for async Flask applications
163

164
## Error Handling
165

166
Flask-Migrate functions raise `CommandError` or `RuntimeError` for migration failures. The `catch_errors` decorator is used internally to handle these exceptions gracefully in CLI usage.