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¶
While Alembic can be installed system wide, it’s more common that it’s installed local to a virtual environment , 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 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 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:
$ /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.
Changed in version 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
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.
Changed in version 1.5.0: Support for SQLAlchemy older than 1.3.0 was dropped.
Alembic supports Python versions 3.7 and above
Changed in version 1.8: Alembic now supports Python 3.7 and newer.
Changed in version 1.7: Alembic now supports Python 3.6 and newer; support for Python 2.7 has been dropped.
Versioning Scheme¶
Alembic’s versioning scheme is based on that of SQLAlchemy’s versioning scheme. 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 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, and is part of the SQLAlchemy project.
User issues, discussion of potential bugs and features are most easily discussed using Github Discussions.
Bugs¶
Bugs and feature enhancements to Alembic should be reported on the GitHub issue tracker.