0
# Alembic
1

2
A comprehensive database migration tool specifically designed for SQLAlchemy applications. Alembic enables developers to manage database schema changes through version-controlled migration scripts with advanced features including ALTER statement generation, sequential migration execution with upgrade/downgrade capabilities, auto-generation of migration candidates, and full support for transactional DDL operations.
3

4
## Package Information
5

6
- **Package Name**: alembic
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install alembic`
10
- **Documentation**: https://alembic.sqlalchemy.org/en/latest/
11

12
## Core Imports
13

14
```python
15
import alembic
16
from alembic import context, op
17
```
18

19
For command-line operations:
20
```python
21
from alembic.config import Config
22
from alembic import command
23
```
24

25
For programmatic migration execution:
26
```python
27
from alembic.runtime.environment import EnvironmentContext
28
from alembic.runtime.migration import MigrationContext
29
```
30

31
## Basic Usage
32

33
### Initialize Migration Environment
34
```python
35
from alembic.config import Config
36
from alembic import command
37

38
# Initialize new migration environment
39
config = Config("alembic.ini")
40
command.init(config, "migrations")
41
```
42

43
### Create Migration Revision
44
```python
45
# Create new migration revision
46
command.revision(config, message="Create user table", autogenerate=True)
47

48
# Run migration
49
command.upgrade(config, "head")
50
```
51

52
### Migration Script Example
53
```python
54
"""Create user table
55

56
Revision ID: 001
57
Create Date: 2023-01-01 10:00:00.000000
58

59
"""
60
from alembic import op
61
import sqlalchemy as sa
62

63
# revision identifiers
64
revision = '001'
65
down_revision = None
66

67
def upgrade():
68
    op.create_table('user',
69
        sa.Column('id', sa.Integer, primary_key=True),
70
        sa.Column('name', sa.String(50), nullable=False),
71
        sa.Column('email', sa.String(120), unique=True)
72
    )
73

74
def downgrade():
75
    op.drop_table('user')
76
```
77

78
## Architecture
79

80
Alembic is built around several key components:
81

82
- **Configuration System**: `Config` class manages connection strings, script locations, and environment settings
83
- **Migration Context**: Provides database connection and transaction management during migrations
84
- **Operations API**: High-level interface for schema changes (create_table, add_column, etc.)
85
- **Script Management**: Handles migration file generation, versioning, and dependency tracking
86
- **Autogeneration**: Compares database schema with SQLAlchemy models to generate migrations
87
- **Command Interface**: CLI and programmatic interfaces for migration management
88

89
## Capabilities
90

91
### CLI Commands
92

93
Complete command-line interface for migration management including environment initialization, revision creation, database upgrades/downgrades, and status checking.
94

95
```python { .api }
96
# Key command functions
97
def init(config, directory, template='generic', package=False): ...
98
def revision(config, message=None, autogenerate=False, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=None, depends_on=None, process_revision_directives=None): ...
99
def upgrade(config, revision, sql=False, tag=None): ...
100
def downgrade(config, revision, sql=False, tag=None): ...
101
def current(config, verbose=False): ...
102
def history(config, rev_range=None, verbose=False, indicate_current=False): ...
103
def check(config): ...  # v1.9.0+
104
def ensure_version(config, sql=False): ...  # v1.7.6+
105
def merge(config, revisions, message=None, branch_label=None, rev_id=None): ...
106
def stamp(config, revision, sql=False, tag=None, purge=False): ...
107
```
108

109
[CLI Commands](./cli-commands.md)
110

111
### Migration Operations
112

113
Schema modification operations available in migration scripts through the `op` module, including table and column operations, constraints, indexes, and data manipulation.
114

115
```python { .api }
116
# Core operation functions
117
def create_table(table_name, *columns, if_not_exists=None, **kw): ...
118
def drop_table(table_name, if_exists=None, **kw): ...  # v1.16.0+
119
def add_column(table_name, column, if_not_exists=None, **kw): ...  # v1.16.0+
120
def drop_column(table_name, column_name, if_exists=None, **kw): ...  # v1.16.0+
121
def alter_column(table_name, column_name, **kw): ...
122
def create_index(index_name, table_name, columns, if_not_exists=None, **kw): ...  # v1.12.0+
123
def drop_index(index_name, table_name=None, if_exists=None, **kw): ...  # v1.12.0+
124
def create_foreign_key(constraint_name, source_table, referent_table, local_cols, remote_cols, **kw): ...
125
def drop_constraint(constraint_name, table_name, type_=None, if_exists=None): ...  # v1.16.0+
126
def batch_alter_table(table_name, schema=None, **kw): ...  # Context manager
127
def run_async(async_function, *args, **kw_args): ...  # v1.11+
128
def f(name): ...  # Naming convention support
129
```
130

131
[Migration Operations](./migration-operations.md)
132

133
### Migration Context
134

135
Environment context functions for accessing database connections, configuration, and migration state within migration scripts.
136

137
```python { .api }
138
# Core context functions
139
def configure(connection=None, url=None, dialect_name=None, **kw): ...
140
def get_bind(): ...
141
def get_context(): ...
142
def execute(sql, execution_options=None): ...
143
def is_offline_mode(): ...
144
def is_transactional_ddl(): ...
145
def run_migrations(): ...
146
def begin_transaction(): ...  # Context manager
147
def get_head_revision(): ...
148
def get_head_revisions(): ...
149
def get_revision_argument(): ...
150
def get_starting_revision_argument(): ...
151
def get_tag_argument(): ...
152
def get_x_argument(as_dictionary=False): ...
153
def static_output(text): ...  # Offline mode output
154
```
155

156
[Migration Context](./migration-context.md)
157

158
### Configuration Management
159

160
Configuration classes and utilities for managing Alembic settings, database connections, and migration environments.
161

162
```python { .api }
163
class Config:
164
    def __init__(self, file_=None, toml_file=None, ini_section='alembic', output_buffer=None, stdout=sys.stdout, cmd_opts=None, config_args=None, attributes=None): ...
165
    def get_main_option(self, name, default=None): ...
166
    def set_main_option(self, name, value): ...
167
    def get_section_option(self, section, name, default=None): ...
168
    def set_section_option(self, section, name, value): ...
169
    def get_section(self, name, default=None): ...
170
    def get_alembic_option(self, name, default=None): ...  # v1.16.0+
171
    def get_alembic_boolean_option(self, name): ...  # v1.16.0+
172
    def get_version_locations_list(self): ...
173
    def get_hooks_list(self): ...
174
    def print_stdout(self, text, *arg): ...
175
```
176

177
[Configuration](./configuration.md)
178

179
### Autogeneration
180

181
Automatic migration generation by comparing database schema with SQLAlchemy model definitions, including customizable comparison and rendering systems.
182

183
```python { .api }
184
def compare_metadata(context, metadata): ...
185
def produce_migrations(context, metadata): ...
186
def render_python_code(up_ops, down_ops, migration_context, **kwargs): ...
187
def render_op_text(autogen_context, op): ...
188

189
# Customization support
190
class AutogenContext: ...
191
class RevisionContext: ...
192
class Rewriter: ...  # Operation rewriting
193

194
# Registries for extensibility
195
comparators: Registry  # Custom comparison functions
196
renderers: Registry    # Custom rendering functions
197
```
198

199
[Autogeneration](./autogeneration.md)
200

201
### Script Management
202

203
Classes and utilities for managing migration scripts, revision tracking, and dependency graphs.
204

205
```python { .api }
206
class ScriptDirectory:
207
    def __init__(self, dir, file_template=None, truncate_slug_length=40, version_locations=None, sourceless=False, output_encoding='utf-8', timezone=None, hooks=None, recursive_version_locations=False, messaging_opts=None): ...
208
    def from_config(cls, config): ...  # Class method
209
    def generate_revision(self, revid, message, **kw): ...
210
    def get_revision(self, id_): ...
211
    def get_current_head(self): ...
212
    def get_heads(self): ...
213
    def get_base(self): ...
214
    def walk_revisions(self, head='heads', base='base'): ...
215
    def iterate_revisions(self, upper, lower): ...
216
    def run_env(self): ...
217
```
218

219
[Script Management](./script-management.md)
220

221
### Runtime Components
222

223
Core runtime classes for migration execution context management, revision tracking, and transaction handling.
224

225
```python { .api }
226
class MigrationContext:
227
    def configure(cls, connection=None, url=None, **opts): ...  # Class method
228
    def get_current_revision(self): ...
229
    def get_current_heads(self): ...
230
    def execute(self, sql, execution_options=None): ...
231
    def stamp(self, script_directory, revision): ...
232
    def run_migrations(self): ...
233

234
class EnvironmentContext:
235
    def configure(self, connection=None, target_metadata=None, **kw): ...
236
    def run_migrations(self, **kw): ...
237
    # Properties
238
    config: Config
239
    script: ScriptDirectory
240
```
241

242
[Runtime Components](./runtime.md)
243

244
## Common Patterns
245

246
### Environment Setup
247
```python
248
# alembic/env.py template structure
249
from alembic import context
250
from sqlalchemy import engine_from_config
251

252
config = context.config
253
target_metadata = None
254

255
def run_migrations_offline():
256
    context.configure(url=url, target_metadata=target_metadata)
257
    with context.begin_transaction():
258
        context.run_migrations()
259

260
def run_migrations_online():
261
    connectable = engine_from_config(config.get_section(config.config_ini_section))
262
    with connectable.connect() as connection:
263
        context.configure(connection=connection, target_metadata=target_metadata)
264
        with context.begin_transaction():
265
            context.run_migrations()
266
```
267

268
### Batch Operations for SQLite
269
```python
270
def upgrade():
271
    with op.batch_alter_table("user") as batch_op:
272
        batch_op.add_column(sa.Column('created_at', sa.DateTime))
273
        batch_op.alter_column('name', nullable=True)
274
```
275

276
## Types
277

278
```python { .api }
279
# Type imports
280
from typing import Union, List, Optional, Set, Any, Dict, Tuple, Callable, Iterator, ContextManager
281
from sqlalchemy import Connection, Dialect, Table, Column
282
from sqlalchemy.sql.schema import Constraint, Index
283
from argparse import Namespace
284

285
# Type aliases
286
_RevIdType = Union[str, List[str], Tuple[str, ...]]
287
ProcessRevisionDirectiveFn = Callable[..., Any]
288

289
# Configuration types
290
class Config:
291
    cmd_opts: Optional[Namespace]
292
    config_args: Dict[str, Any]
293
    config_file_name: Optional[str]
294
    toml_file_name: Optional[str]  # v1.16.0+
295
    attributes: Dict[str, Any]
296
    
297
# Context types  
298
class MigrationContext:
299
    bind: Connection
300
    dialect: Dialect
301
    
302
class EnvironmentContext:
303
    config: Config
304
    script: ScriptDirectory
305

306
# Script types
307
class Script:
308
    revision: str
309
    down_revision: Optional[str]
310
    branch_labels: Optional[Set[str]]
311
    depends_on: Optional[Set[str]]
312
    path: str
313

314
class ScriptDirectory:
315
    dir: str
316
    versions: str
317
    revision_map: RevisionMap
318

319
# Operation types
320
class Operations:
321
    migration_context: MigrationContext
322
    
323
class BatchOperations(Operations):
324
    table: Table
325

326
# Messaging configuration (v1.15.3+)
327
class MessagingOptions:
328
    file_template: str
329
    truncate_slug_length: int
330
    timezone: Optional[str]
331
    
332
# Post-write hook configuration
333
class PostWriteHookConfig:
334
    type: str
335
    entrypoint: str
336
    options: Dict[str, Any]
337

338
# Exception types
339
class CommandError(Exception): ...
340
class AutogenerateDiffsDetected(Exception): ...
341
class RevisionError(Exception): ...
342
```