From e5dde2d142d724c98562f992133bf524befbe437 Mon Sep 17 00:00:00 2001 From: Nathan Swain Date: Tue, 9 Jan 2024 09:04:51 -0700 Subject: [PATCH] Add missing docs: database_configuration.rst --- docs/installation/database_configuration.rst | 49 ++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/installation/database_configuration.rst diff --git a/docs/installation/database_configuration.rst b/docs/installation/database_configuration.rst new file mode 100644 index 000000000..73adeb291 --- /dev/null +++ b/docs/installation/database_configuration.rst @@ -0,0 +1,49 @@ +.. _database_configuration: + +********************** +Database Configuration +********************** + +**Last Updated:** September 2023 + +Tethys Platform supports several options for setting up a DB server: local, docker, or remote. By default Tethys uses a local SQLite database. When using the default settings, setting up a database can be done with one simple command: + +.. code-block:: bash + + tethys db configure + +.. note:: + + The tethys db command (:ref:`tethys_db_cmd`) will create a local database file in the location specified by the ``NAME`` setting in the ``DATABASES`` section of the :file:`portal_config.yml` file (by default ``tethys_platform.sqlite``). If the value of ``NAME`` is a relative path then the database file will be created relative to directory specified by the ``TETHYS_HOME`` environment variable. By default ``TETHYS_HOME`` is at `~/.tethys`. + +For information on additional database settings refer to the :ref:`database_settings` setting. + +Using PostreSQL +=============== + +.. important:: + + This feature requires that the PostgreSQL database and the ``psycopg2`` library be installed. Starting with Tethys 5.0 or if you are using ``micro-tethys-platform``, you will need to install ``postgresql`` and ``psycopg2`` using conda as follows: + + .. code-block:: bash + + # conda: conda-forge channel strongly recommended + conda install -c conda-forge postgresql psycopg2 + +While Tethys Platform uses the SQLite database by default for ease of use in development environments, it has excellent support for PostgreSQL (which is recommended for production). To use a local PostgreSQL database (for development) you will need to change the ``ENGINE`` setting in the ``DATABASES`` section of the :file:`portal_config.yml` file to ``django.db.backends.postgresql``, and you will need to add the ``DIR`` setting in the same section. This can easily be done using the :ref:`tethys_settings_cmd`: + +.. code-block:: bash + + tethys settings --set DATABASES.default.ENGINE django.db.backends.postgresql --set DATABASES.default.DIR psql + +.. note:: + + The tethys db command (:ref:`tethys_db_cmd`) will create a local database server in the directory specified by the ``DIR`` setting in the ``DATABASES`` section of the :file:`portal_config.yml` file. If the value of ``DIR`` is a relative path then the database server will be created relative to directory specified by the ``TETHYS_HOME`` environment variable. By default ``TETHYS_HOME`` is at `~/.tethys`. + + As an alternative to creating a local database server you can also configure a Docker DB server (see :ref:`using_docker`). A local database server is only recommended for development environments. For production environments please refer to :ref:`production_installation`. + + +Using Other Databases +===================== + +While many of the convenience tools that Tethys provides only support SQLite and PostgreSQL, Tethys can be configured with other Database engines. See ``_ for more information. \ No newline at end of file