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::
+To build a virtual environment for a specific project, a virtual environment
+can be created using the
+`Python venv library <https://docs.python.org/3/library/venv.html>`_::
$ cd /path/to/your/project
- $ virtualenv .venv
+ $ python -m venv .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``.
+Next,the ``activate`` command installed by venv can be used so that
+all binaries local to this new Python environment are in the local path::
+
+ $ source /path/to/your/project/.venv/bin/activate
+
We now install Alembic as follows::
- $ /path/to/your/project/.venv/bin/pip install alembic
+ $ 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 alembic
+ $ alembic init alembic
-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>`_::
+Finally, assuming your project is itself installable, meaning it has a
+``pyproject.toml`` file, and/or ``setup.py`` script, the local project can
+be made a part of the same local environment by installing it with ``pip``,
+optionally using "editable" mode::
- $ /path/to/your/project/.venv/bin/pip install -e .
+ $ 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.
-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
------------
scripts for a relational database, using SQLAlchemy as the underlying engine.
This tutorial will provide a full introduction to the theory and usage of this tool.
-To begin, make sure Alembic is installed as described at :ref:`installation`.
-As stated in the linked document, it is usually preferable that Alembic is
+To begin, make sure Alembic is installed; a common way to install within a
+local virtual environment is described at :ref:`installation`.
+As illustrated in that chapter, it is useful to have Alembic
installed in the **same module / Python path as that of the target project**,
usually using a `Python virtual environment
<https://docs.python.org/3/tutorial/venv.html>`_, so that when the ``alembic``
command is run, the Python script which is invoked by ``alembic``, namely your
project's ``env.py`` script, will have access to your application's models.
-This is not strictly necessary in all cases, however in the vast majority of
-cases is usually preferred.
+This is not strictly necessary, however is usually preferred.
The tutorial below assumes the ``alembic`` command line utility is present in
the local path and when invoked, will have access to the same Python module
Please edit configuration/connection/logging settings in
'/path/to/yourproject/alembic.ini' before proceeding.
-Alembic also includes other environment templates. These can be listed out using the ``list_templates``
-command::
+The above layout is produced using a layout template called ``generic``.
+Alembic also includes other environment templates. These can be listed out
+using the ``list_templates`` command::
$ alembic list_templates
Available templates:
alembic init --template generic ./scripts
-.. versionchanged:: 1.8 The "pylons" environment template has been removed.
-
.. versionchanged:: 1.16.0 A new ``pyproject`` template has been added. See
- the section :re3f:`using_pep_621` for background.
+ the section :ref:`using_pep_621` for background.
+
-`
.. _tutorial_alembic_ini:
Editing the .ini File
=====================
-Alembic placed a file ``alembic.ini`` into the current directory. This is a file that the ``alembic``
-script looks for when invoked. This file can exist in a different directory, with the location to it
-specified by either the ``--config`` option for the ``alembic`` runner or the ``ALEMBIC_CONFIG``
-environment variable (the former takes precedence).
+Alembic placed a file ``alembic.ini`` into the current directory. Alembic looks
+in the current directory for this file when any other commands are run; to
+indicate an alternative location, the ``--config`` option may be used, or the
+``ALEMBIC_CONFIG`` environment variable may be set.
+
+.. tip::
-The file generated with the "generic" configuration looks like::
+ The file generated with the ``generic`` configuration template contains all directives
+ for both source code configuration as well as database configuration. When using
+ the ``pyproject`` template, the source code configuration elements will instead
+ be in a separate ``pyproject.toml`` file, described in the :ref:`next section <using_pep_621>`.
+
+The all-in-one .ini file created by ``generic`` is illustrated below::
# A generic, single database configuration.
# are written from script.py.mako
# output_encoding = utf-8
+ # database URL. This is consumed by the user-maintained env.py script only.
+ # other means of configuring database URLs may be customized within the env.py
+ # file.
sqlalchemy.url = driver://user:pass@localhost/dbname
# [post_write_hooks]
# ruff.executable = %(here)s/.venv/bin/ruff
# ruff.options = check --fix REVISION_SCRIPT_FILENAME
- # Logging configuration
+ # Logging configuration. This is also consumed by the user-maintained
+ # env.py script only.
[loggers]
keys = root,sqlalchemy,alembic
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
-The file is read using Python's :class:`ConfigParser.SafeConfigParser` object. The
-``%(here)s`` variable is provided as a substitution variable, which
-can be used to produce absolute pathnames to directories and files, as we do above
-with the path to the Alembic script location.
+The ``alembic.ini`` file is consumed by Alembic using Python's
+`configparser.ConfigParser <https://docs.python.org/3/library/configparser.html#configparser.ConfigParser>`_
+library. The ``%(here)s`` variable is
+provided as a substitution which is populated with the absolute path to the
+``alembic.ini`` file itself. This can be used to produce correct pathnames
+to directories and files relative to where the config file is located.
This file contains the following features:
by default ``datetime.datetime.now()`` unless the ``timezone``
configuration option is also used.
- .. versionadded:: 1.8 added 'epoch'
-
* ``timezone`` - an optional timezone name (e.g. ``UTC``, ``EST5EDT``, etc.)
that will be applied to the timestamp which renders inside the migration
file's comment as well as within the filename. This option requires Python>=3.9
well, as ``alembic.ini`` is still the default location for **deployment**
details such as database URLs, connectivity options, and logging to be present.
However, as connectivity and logging is consumed only by user-managed code
-within the ``env.py`` file, it is feasible that the environment would not
+within the ``env.py`` file, it is feasible to have an environment that does not
require the ``alembic.ini`` file itself to be present at all, if these
configurational elements are consumed from other places elsewhere in the
-application.
+application. Alembic will still run successfully if only a ``pyproject.toml``
+file is present and no ``alembic.ini`` is found.
+
To start with a pyproject configuration, the most straightforward approach is
to use the ``pyproject`` template::
[alembic]
+ # database URL. This is consumed by the user-maintained env.py script only.
+ # other means of configuring database URLs may be customized within the env.py
+ # file.
sqlalchemy.url = driver://user:pass@localhost/dbname
- # Logging configuration
+ # Logging configuration. This is also consumed by the user-maintained
+ # env.py script only.
[loggers]
keys = root,sqlalchemy,alembic
projects / thirdparty / sqlalchemy / alembic.git / commitdiff
