rattail/rattail-manual
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add some about extending the schema, first alembic version

Browse source 
plus some more structure for web/mainapp
This commit is contained in:
Lance Edgar 2021-01-23 17:06:20 -06:00
parent 7a7a182bda
commit 0e83d60686
8 changed files with 107 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

62
docs/data/db/extend.rst
View file

@ -1,4 +1,6 @@
.. highlight:: sh
Extending the Schema
====================
@ -17,4 +19,62 @@ Rattail reserves the prefix-less namespace for its core schema. Also, certain
integration packages reserve other namespaces (e.g. ``corepos_`` prefix is used
by the rattail-corepos package for extension tables it provides).
TODO: obviously need to say how one can go about extending schema...
First Alembic Version
---------------------
In order to add custom extensions to the schema, you will need to establish
some things for sake of Alembic. Note that these steps are only required for
the "first" extension you add; subsequent versions are somewhat simpler and are
covered in the next section.
First you should have the basic folder structure::
cd ~/src/poser
mkdir -p poser/db/alembic/versions
You must edit your config file at ``/srv/envs/poser/app/rattail.conf`` and
update the ``version_locations`` setting for Alembic, to include your new
folder. Note the way we specify the path below; this ensures it works no
matter where things actually live on disk. Also note that we specify the
custom location first, core rattail goes last.
.. code-block:: ini
[alembic]
script_location = rattail.db:alembic
version_locations = poser.db:alembic/versions rattail.db:alembic/versions
Run a command like this (replacing names etc. as needed) to generate the script
in your versions folder::
cd /srv/envs/poser
bin/alembic -c app/rattail.conf revision --autogenerate --head rattail@head --version-path ~/src/poser/poser/db/alembic/versions/ -m 'initial Poser tables'
If all goes well that command output should end by telling you where the new
script lives. You will want to review this of course, to make sure it includes
all your new tables.
But you must also declare this version as a new branch head. This lets your
custom versions have a life of their own, essentially. So going forward, when
you upgrade your DB schema, both the core Rattail tables, as well as your own,
will be migrated properly.
There are two variables near the top of the script which you must edit, like so:
.. code-block:: python
down_revision = None
branch_labels = ('poser',)
And with all that in place, you can apply the migration to your DB (this part
is normal)::
cd /srv/envs/poser
bin/alembic -c app/rattail.conf upgrade heads
Additional Alembic Versions
---------------------------
TODO