1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
.. _api:
===========
API Details
===========
This section describes some key functions used within the migration process, particularly those referenced within
a migration environment's ``env.py`` file.
Overview
========
The three main objects in use are the :class:`.EnvironmentContext`, :class:`.MigrationContext`,
and :class:`.Operations` classes, pictured below.
.. image:: api_overview.png
An Alembic command begins by instantiating an :class:`.EnvironmentContext` object, then
making it available via the ``alembic.context`` proxy module. The ``env.py``
script, representing a user-configurable migration environment, is then
invoked. The ``env.py`` script is then responsible for calling upon the
:meth:`.EnvironmentContext.configure`, whose job it is to create
a :class:`.MigrationContext` object.
Before this method is called, there's not
yet any database connection or dialect-specific state set up. While
many methods on :class:`.EnvironmentContext` are usable at this stage,
those which require database access, or at least access to the kind
of database dialect in use, are not. Once the
:meth:`.EnvironmentContext.configure` method is called, the :class:`.EnvironmentContext`
is said to be *configured* with database connectivity, available via
a new :class:`.MigrationContext` object. The :class:`.MigrationContext`
is associated with the :class:`.EnvironmentContext` object
via the :meth:`.EnvironmentContext.get_context` method.
Finally, ``env.py`` calls upon the :meth:`.EnvironmentContext.run_migrations`
method. Within this method, a new :class:`.Operations` object, which
provides an API for individual database migration operations, is established
within the ``alembic.op`` proxy module. The :class:`.Operations` object
uses the :class:`.MigrationContext` object ultimately as a source of
database connectivity, though in such a way that it does not care if the
:class:`.MigrationContext` is talking to a real database or just writing
out SQL to a file.
The Environment Context
=======================
The :class:`.EnvironmentContext` class provides most of the
API used within an ``env.py`` script. Within ``env.py``,
the instantated :class:`.EnvironmentContext` is made available
via a special *proxy module* called ``alembic.context``. That is,
you can import ``alembic.context`` like a regular Python module,
and each name you call upon it is ultimately routed towards the
current :class:`.EnvironmentContext` in use.
In particular, the key method used within ``env.py`` is :meth:`.EnvironmentContext.configure`,
which establishes all the details about how the database will be accessed.
.. automodule:: alembic.environment
:members:
The Migration Context
=====================
.. automodule:: alembic.migration
:members:
The Operations Object
=====================
Within migration scripts, actual database migration operations are handled
via an instance of :class:`.Operations`. See :ref:`ops` for an overview
of this object.
Commands
=========
Alembic commands are all represented by functions in the :mod:`alembic.command`
package. They all accept the same style of usage, being sent
the :class:`~.alembic.config.Config` object as the first argument.
Commands can be run programmatically, by first constructing a :class:`.Config`
object, as in::
from alembic.config import Config
from alembic import command
alembic_cfg = Config("/path/to/yourapp/alembic.ini")
command.upgrade(alembic_cfg, "head")
To write small API functions that make direct use of database and script directory
information, rather than just running one of the built-in commands,
use the :class:`.ScriptDirectory` and :class:`.MigrationContext`
classes directly.
.. currentmodule:: alembic.command
.. automodule:: alembic.command
:members:
Configuration
==============
The :class:`.Config` object represents the configuration
passed to the Alembic environment. From an API usage perspective,
it is needed for the following use cases:
* to create a :class:`.ScriptDirectory`, which allows you to work
with the actual script files in a migration environment
* to create an :class:`.EnvironmentContext`, which allows you to
actually run the ``env.py`` module within the migration environment
* to programatically run any of the commands in the :mod:`alembic.command`
module.
The :class:`.Config` is *not* needed for these cases:
* to instantiate a :class:`.MigrationContext` directly - this object
only needs a SQLAlchemy connection or dialect name.
* to instantiate a :class:`.Operations` object - this object only
needs a :class:`.MigrationContext`.
.. currentmodule:: alembic.config
.. automodule:: alembic.config
:members:
Script Directory
================
The :class:`.ScriptDirectory` object provides programmatic access
to the Alembic version files present in the filesystem.
.. automodule:: alembic.script
:members:
Autogeneration
==============
Alembic 0.3 introduces a small portion of the autogeneration system
as a public API.
.. autofunction:: alembic.autogenerate.compare_metadata
DDL Internals
=============
These are some of the constructs used to generate migration
instructions. The APIs here build off of the :class:`sqlalchemy.schema.DDLElement`
and :mod:`sqlalchemy.ext.compiler` systems.
For programmatic usage of Alembic's migration directives, the easiest
route is to use the higher level functions given by :mod:`alembic.operations`.
.. automodule:: alembic.ddl
:members:
:undoc-members:
.. automodule:: alembic.ddl.base
:members:
:undoc-members:
.. automodule:: alembic.ddl.impl
:members:
:undoc-members:
MySQL
-----
.. automodule:: alembic.ddl.mysql
:members:
:undoc-members:
:show-inheritance:
MS-SQL
------
.. automodule:: alembic.ddl.mssql
:members:
:undoc-members:
:show-inheritance:
Postgresql
----------
.. automodule:: alembic.ddl.postgresql
:members:
:undoc-members:
:show-inheritance:
SQLite
------
.. automodule:: alembic.ddl.sqlite
:members:
:undoc-members:
:show-inheritance:
|
