64 lines
2 KiB
ReStructuredText
64 lines
2 KiB
ReStructuredText
|
|
||
|
|
Migrating the Schema
|
||
|
|
====================
|
||
|
|
|
||
|
|
.. contents:: :local:
|
||
|
|
|
||
|
|
As development progresses for your custom app, you may need to migrate the
|
||
|
|
database schema from time to time.
|
||
|
|
|
||
|
|
See also this general discussion of the :doc:`concepts/schema`.
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
|
||
|
|
The only "safe" migrations are those which add or modify (or remove)
|
||
|
|
"custom" tables, i.e. those *not* provided by the ``rattail.db.model``
|
||
|
|
package. This doc assumes you are aware of this and are only attempting a
|
||
|
|
safe migration.
|
||
|
|
|
||
|
|
|
||
|
|
Modify ORM Classes
|
||
|
|
------------------
|
||
|
|
|
||
|
|
First step is to modify the ORM classes defined by your app, so they reflect
|
||
|
|
the "desired" schema. Typically this will mean editing files under the
|
||
|
|
``poser.db.model`` package within your source. In particular when adding new
|
||
|
|
tables, you must be sure to include them within ``poser/db/model/__init__.py``.
|
||
|
|
|
||
|
|
As noted above, only those classes *not* provided by ``rattail.db.model``
|
||
|
|
should be modified here, to be safe. If you wish to "extend" an existing
|
||
|
|
table, you must create a secondary table which ties back to the first via
|
||
|
|
one-to-one foreign key relationship.
|
||
|
|
|
||
|
|
|
||
|
|
Create Migration Script
|
||
|
|
-----------------------
|
||
|
|
|
||
|
|
Next you will create the Alembic script which is responsible for performing the
|
||
|
|
schema migration against a database. This is typically done like so:
|
||
|
|
|
||
|
|
.. code-block:: sh
|
||
|
|
|
||
|
|
workon poser
|
||
|
|
cdvirtualenv
|
||
|
|
bin/alembic -c app/rattail.conf revision --autogenerate --head poser@head -m "describe migration here"
|
||
|
|
|
||
|
|
This will create a new file under
|
||
|
|
e.g. ``~/src/poser/poser/db/alembic/versions/``. You should edit this file as
|
||
|
|
needed to ensure it performs all steps required for the migration. Technically
|
||
|
|
it should support downgrade as well as upgrade, although in practice that isn't
|
||
|
|
always required.
|
||
|
|
|
||
|
|
|
||
|
|
Upgrade Database Schema
|
||
|
|
-----------------------
|
||
|
|
|
||
|
|
Once you're happy with the new script, you can apply it against your dev
|
||
|
|
database with something like:
|
||
|
|
|
||
|
|
.. code-block:: sh
|
||
|
|
|
||
|
|
workon poser
|
||
|
|
cdvirtualenv
|
||
|
|
bin/alembic -c app/rattail.conf upgrade heads
|