From 0e83d60686f0d94c5baeb7a5983fe31124559660 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Sat, 23 Jan 2021 17:06:20 -0600 Subject: [PATCH] Add some about extending the schema, first alembic version plus some more structure for web/mainapp --- docs/data/db/extend.rst | 62 +++++++++++++++++++++++- docs/web/index.rst | 2 +- docs/web/mainapp/index.rst | 12 +++++ docs/web/mainapp/overview.rst | 5 ++ docs/web/mainapp/patterns.rst | 6 +++ docs/web/mainapp/tasks/index.rst | 10 ++++ docs/web/mainapp/tasks/newmasterview.rst | 12 +++++ docs/web/webmain.rst | 17 ------- 8 files changed, 107 insertions(+), 19 deletions(-) create mode 100644 docs/web/mainapp/index.rst create mode 100644 docs/web/mainapp/overview.rst create mode 100644 docs/web/mainapp/patterns.rst create mode 100644 docs/web/mainapp/tasks/index.rst create mode 100644 docs/web/mainapp/tasks/newmasterview.rst delete mode 100644 docs/web/webmain.rst diff --git a/docs/data/db/extend.rst b/docs/data/db/extend.rst index 42f1a3d..d956538 100644 --- a/docs/data/db/extend.rst +++ b/docs/data/db/extend.rst @@ -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 diff --git a/docs/web/index.rst b/docs/web/index.rst index 2a10ee8..2725b48 100644 --- a/docs/web/index.rst +++ b/docs/web/index.rst @@ -8,6 +8,6 @@ Web Layer :caption: Contents: overview - webmain + mainapp/index webapi spa diff --git a/docs/web/mainapp/index.rst b/docs/web/mainapp/index.rst new file mode 100644 index 0000000..54907de --- /dev/null +++ b/docs/web/mainapp/index.rst @@ -0,0 +1,12 @@ + +Default Web App +=============== + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + patterns + tasks/index diff --git a/docs/web/mainapp/overview.rst b/docs/web/mainapp/overview.rst new file mode 100644 index 0000000..45595c5 --- /dev/null +++ b/docs/web/mainapp/overview.rst @@ -0,0 +1,5 @@ + +Overview +======== + +TODO diff --git a/docs/web/mainapp/patterns.rst b/docs/web/mainapp/patterns.rst new file mode 100644 index 0000000..4674b76 --- /dev/null +++ b/docs/web/mainapp/patterns.rst @@ -0,0 +1,6 @@ + +================= + Common Patterns +================= + +TODO diff --git a/docs/web/mainapp/tasks/index.rst b/docs/web/mainapp/tasks/index.rst new file mode 100644 index 0000000..7c6706e --- /dev/null +++ b/docs/web/mainapp/tasks/index.rst @@ -0,0 +1,10 @@ + +Common Tasks +============ + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + newmasterview diff --git a/docs/web/mainapp/tasks/newmasterview.rst b/docs/web/mainapp/tasks/newmasterview.rst new file mode 100644 index 0000000..42391b7 --- /dev/null +++ b/docs/web/mainapp/tasks/newmasterview.rst @@ -0,0 +1,12 @@ + +=============== +New Master View +=============== + +This assumes you already have a table in your (or another) DB and wish to +expose basic CRUD things for it, a la typical master view style. + +If you want to use a custom table you created, you must do that part first. +See also :doc:`/data/db/extend`. + +TODO: how exactly to do it, without copy/pasta diff --git a/docs/web/webmain.rst b/docs/web/webmain.rst deleted file mode 100644 index 372dcf8..0000000 --- a/docs/web/webmain.rst +++ /dev/null @@ -1,17 +0,0 @@ - -Default Web App -=============== - -TODO - - -Common Tasks ------------- - -TODO - - -Common Patterns ---------------- - -TODO