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
|
============
Front Matter
============
Information about the Alembic project.
Project Homepage
================
Alembic is hosted on GitHub at https://github.com/sqlalchemy/alembic under the SQLAlchemy organization.
Releases and project status are available on Pypi at https://pypi.python.org/pypi/alembic.
The most recent published version of this documentation should be at https://alembic.sqlalchemy.org.
.. _installation:
Installation
============
While Alembic can be installed system wide, it's more common that it's
installed local to a `virtual environment
<https://docs.python.org/3/tutorial/venv.html>`_ , as it also uses libraries
such as SQLAlchemy and database drivers that are more appropriate for
local installations.
The documentation below is **only one kind of approach to installing Alembic
for a project**; there are many such approaches. The documentation below is
provided only for those users who otherwise have no specific project setup
chosen.
To build a virtual environment for a specific project, first we assume that
`Python virtualenv <https://pypi.org/project/virtualenv/>`_ is installed
systemwide. Then::
$ cd /path/to/your/project
$ virtualenv .venv
There is now a Python interpreter that you can access in
``/path/to/your/project/.venv/bin/python``, as well as the `pip
<http://pypi.python.org/pypi/pip>`_ installer tool in
``/path/to/your/project/.venv/bin/pip``.
We now install Alembic as follows::
$ /path/to/your/project/.venv/bin/pip install alembic
The install will add the ``alembic`` command to the virtual environment. All
operations with Alembic in terms of this specific virtual environment will then
proceed through the usage of this command, as in::
$ /path/to/your/project/.venv/bin/alembic init .
The next step is **optional**. If our project itself has a ``setup.py``
file, we can also install it in the local virtual environment in
`editable mode <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_::
$ /path/to/your/project/.venv/bin/pip install -e .
If we don't "install" the project locally, that's fine as well; the default
``alembic.ini`` file includes a directive ``prepend_sys_path = .`` so that the
local path is also in ``sys.path``. This allows us to run the ``alembic``
command line tool from this directory without our project being "installed" in
that environment.
.. versionchanged:: 1.5.5 Fixed a long-standing issue where the ``alembic``
command-line tool would not preserve the default ``sys.path`` of ``.``
by implementing ``prepend_sys_path`` option.
As a final step, the `virtualenv activate <https://virtualenv.pypa.io/en/latest/userguide/#activate-script>`_
tool can be used so that the ``alembic`` command is available without any
path information, within the context of the current shell::
$ source /path/to/your/project/.venv/bin/activate
Dependencies
------------
Alembic's install process will ensure that SQLAlchemy_
is installed, in addition to other dependencies. Alembic will work with
SQLAlchemy as of version **1.3.0**.
.. versionchanged:: 1.5.0 Support for SQLAlchemy older than 1.3.0 was dropped.
Alembic supports Python versions **3.7 and above**
.. versionchanged:: 1.8 Alembic now supports Python 3.7 and newer.
.. versionchanged:: 1.7 Alembic now supports Python 3.6 and newer; support
for Python 2.7 has been dropped.
.. _versioning_scheme:
Versioning Scheme
-----------------
Alembic's versioning scheme is based on that of
`SQLAlchemy's versioning scheme <https://www.sqlalchemy.org/download.html#versions>`_.
In particular, it should be noted that while Alembic uses a three-number
versioning scheme, it **does not use SemVer**. In SQLAlchemy and Alembic's
scheme, **the middle digit is considered to be a "Significant Minor Release",
which may include removal of previously deprecated APIs with some risk of
non-backwards compatibility in a very small number of cases**.
This means that version "1.8.0", "1.9.0", "1.10.0", "1.11.0", etc. are
**Significant Minor Releases**, which will include new API features and may
remove or modify existing ones.
Therefore, when `pinning <https://pip.pypa.io/en/stable/topics/repeatable-installs/>`_
Alembic releases, pin to the "major" and "minor" digits to avoid API changes.
A true "Major" release such as a change to "2.0" would include complete
redesigns/re-architectures of foundational features; currently no such series
of changes are planned, although changes such as replacing the entire
"autogenerate" scheme with a new approach would qualify for that level of
change.
Community
=========
Alembic is developed by `Mike Bayer <http://techspot.zzzeek.org>`_, and is
part of the SQLAlchemy_ project.
User issues, discussion of potential bugs and features are most easily
discussed using `Github Discussions <https://github.com/sqlalchemy/alembic/discussions/>`_.
.. _bugs:
Bugs
====
Bugs and feature enhancements to Alembic should be reported on the `GitHub
issue tracker
<https://github.com/sqlalchemy/alembic/issues/>`_.
.. _SQLAlchemy: https://www.sqlalchemy.org
|
