63 lines
2.1 KiB
ReStructuredText
63 lines
2.1 KiB
ReStructuredText
|
|
Migrating the Schema
|
|
====================
|
|
|
|
Rattail uses `Alembic`_ to manage its schema migrations.
|
|
|
|
.. _Alembic: https://alembic.sqlalchemy.org/en/latest/
|
|
|
|
Schema is defined in the ``model`` module(s) using SQLAlchemy, but the logic
|
|
for actually installing the schema is stored as Alembic "version" scripts.
|
|
|
|
Assuming a typical setup, you can migrate your DB to the latest schema like
|
|
so:
|
|
|
|
.. code-block:: sh
|
|
|
|
cd /srv/envs/poser
|
|
bin/alembic -c app/rattail.conf upgrade heads
|
|
|
|
.. note::
|
|
Since ``alembic`` is not a "native" Rattail command, we cannot use
|
|
:doc:`/base/config/inheritance`. In practice this means you probably
|
|
*cannot* use your ``quiet.conf`` file here. This is because Alembic will
|
|
simply read the specified file for its config, and will not know to
|
|
auto-include any others. Therefore the config file you specify, must itself
|
|
contain the ``[alembic]`` section; examples shown below.
|
|
|
|
Note that this will migrate both the core Rattail schema, as well as any
|
|
extensions you've defined. Or rather, it will migrate according to what it
|
|
finds in the config file.
|
|
|
|
A typical config snippet with just the core Rattail schema:
|
|
|
|
.. code-block:: ini
|
|
|
|
[alembic]
|
|
script_location = rattail.db:alembic
|
|
version_locations = rattail.db:alembic/versions
|
|
|
|
A typical config snippet for a project which extends schema *and* includes some
|
|
schema extensions which are provided by the rattail-corepos integration
|
|
package:
|
|
|
|
.. code-block:: ini
|
|
|
|
[alembic]
|
|
script_location = poser.db:alembic
|
|
version_locations = poser.db:alembic/versions rattail_corepos.db:alembic/versions rattail.db:alembic/versions
|
|
|
|
.. caution::
|
|
The order *does* matter within the ``version_locations`` setting above. It
|
|
should progress from "custom" to "core" when reading left to right.
|
|
|
|
Since we're using Alembic here, we have other commands available to us for
|
|
viewing the overall migration history etc. For instance:
|
|
|
|
.. code-block:: sh
|
|
|
|
cd /srv/envs/poser
|
|
bin/alembic -c app/rattail.conf heads
|
|
bin/alembic -c app/rattail.conf current
|
|
bin/alembic -c app/rattail.conf history
|