Merge pull request #981 from iiasa/enh/document-local-postgres-setup

Document how to setup a local Postgres DB

Author: khaeru

RELEASE_NOTES.rst

@@ -48,6 +48,8 @@ All changes
   - :mod:`message_ix.message_macro` includes :class:`.MESSAGE_MACRO`.
 
 - Document the :ref:`minimum version of Java <install-java>` required for :class:`ixmp.JDBCBackend <ixmp.backend.jdbc.JDBCBackend>` (:pull:`962`).
+- Document :ref:`how to run a local PostgreSQL instance <install-postgres>`
+  for local testing using :class:`ixmp.IXMP4Backend <ixmp.backend.ixmp4.IXMP4Backend>` (:pull:`981`).
 - Improve type hinting (:pull:`963`).
 - Fix capitalization in auxiliary_settings.gms to enable GDX output file compression on MacOS and Linux. (:pull:`965`) 
 

doc/conf.py

@@ -214,6 +214,7 @@ def local_inv(name: str, *parts: str) -> str | None:
         "https://docs.messageix.org/projects/ixmp/en/latest/",
         (local_inv("ixmp"), None),
     ),
+    "ixmp4": ("https://docs.ece.iiasa.ac.at/projects/ixmp4/en/latest", None),
     "jpype": ("https://jpype.readthedocs.io/en/stable", None),
     "message-ix-models": (
         "https://docs.messageix.org/projects/models/en/latest/",

doc/install-adv.rst

@@ -137,6 +137,83 @@ If you want to use :meth:`.visualize` or run the test suite, the Graphviz progra
 If you install MESSAGEix :ref:`using conda <using-conda>`, Graphviz is installed automatically via `its conda-forge package`_.
 For other methods of installation (such as :program:`pip`) see the `Graphviz download page`_ for downloads and instructions for your system.
 
+.. _install-postgres:
+
+PostgreSQL (optional)
+---------------------
+
+.. caution::
+   Support for PostgreSQL via :class:`ixmp.IXMP4Backend <ixmp.backend.ixmp4.IXMP4Backend>` experimental,
+   and still under development.
+   If you notice differences in behaviour or performance, 
+   please let us know by opening an issue on GitHub.
+
+While the :mod:`ixmp4` package supports both SQLite and `PostgreSQL <https://www.postgresql.org/>`__ databases
+it and thus :class:`~ixmp.backend.ixmp4.IXMP4Backend` only provide complete support for |MESSAGEix| when using PostgreSQL.
+(See `iiasa/ixmp4#190 <https://github.com/iiasa/ixmp4/pull/190>`__ for details.)
+In order to use IXMP4Backend, ixmp4, and PostgreSQL for local storage of :class:`message_ix.Scenario` data,
+you must have a running instance of PostgreSQL.
+
+There are multiple ways to install and configure PostgreSQL;
+`the ixmp4 developer documentation <https://github.com/iiasa/ixmp4/blob/main/DEVELOPING.md#running-tests-with-postgresql>`__ contains some discussion.
+One way that suffices for local testing is to use `Docker <https://docker.com>`__:
+
+- Ensure Docker is installed.
+  If necessary,
+  follow the `the Docker install instructions <https://docs.docker.com/engine/install>`__.
+- Pull (retrieve) the latest version of the official PostgreSQL Docker image.
+  In a terminal, run::
+
+    docker pull postgres
+
+- Run the container::
+
+    docker run -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=ixmp_test -p 5432:5432 -d postgres
+
+  As of version 3.12, the :mod:`ixmp` default configuration includes a Platform named ``ixmp4-local``
+  that uses IXMP4Backend with the setting :py:`dsn="postgresql+psycopg://postgres:postgres@localhost:5432/ixmp_test"`.
+  In the above :program:`docker run` call,
+  the particular values for the ``POSTGRES_PASSWORD`` and ``POSTGRES_DB`` environment variables 
+  result in a database instance that matches this setting.
+  You may choose different values for these environment variables;
+  if so, then use a setting like :py:`dsn="postgresql+psycopg://postgres:{POSTGRES_PASSWORD}@localhost:5432/{POSTGRES_DB}"`
+  for the given Platform.
+
+The container must continue running while using :mod:`message_ix` with any PostgreSQL-backed Platform(s).
+Afterwards:
+
+- Show information about the running container(s)::
+
+    docker ps
+
+  This will show CONTAINER ID like "9d80a28ce850" and NAMES like "foo_bar".
+
+- Stop the PostgreSQL container using either its ID or name::
+
+    docker stop [CONTAINER ID]
+
+  .. warning:: When the container is stopped
+     —for instance, if the computer is turned off or rebooted—
+     **no data is preserved**.
+     In order for the contents of PostgreSQL database(s) in the container
+     to persist across container restarts,
+     the Docker :program:`--volume` option or similiar configuration must be used
+     to 'mount' or 'bind' a directory outside the container.
+
+  .. todo:: Expand the above commands to include :program:`--volume` examples.
+
+.. tip::
+   If :mod:`ixmp4` is installed or available from source
+   a `Docker Compose <https://docs.docker.com/compose/>`__ file,
+   :file:`tests/docker-compose.yaml`
+   (`view on GitHub <https://github.com/iiasa/ixmp4/blob/main/tests/docker-compose.yml>`__)
+   is available.
+   This allows to combine the :program:`docker pull` and :program:`docker run` steps
+   and use enviroment variables set by the file contents.
+   In a terminal, run::
+
+     docker-compose -f docker-compose.yml up
+
 Install |MESSAGEix|
 ===================