Use Databases

Last Updated: September 2025

In this recipe you will configure your Tethys installation to use a PostgreSQL database. There are many ways to install PostgreSQL, but for this recipe you will install it using Docker.

  1. Install PostgreSQL database with the PostGIS extension using Docker:

    1. Install Docker Desktop or Docker Engine. Open Docker and have it run in the background while you complete the tutorial.

    2. Open a terminal and run the following command to create a new PostgreSQL with PostGIS Docker container:

    docker run -d --name tethys_postgis -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 postgis/postgis

    1. Verify in Docker desktop that you have a new container running with the name "tethys_postgis" on port 5432 (5432:5432).

  2. Add necessary Python dependencies:

    To use the PostgreSQL database you need to install the psycopg2 library. Install it using one of the following commands:

    # conda: conda-forge channel strongly recommended
conda install -c conda-forge psycopg2

# pip
pip install psycopg2

  3. Configure Tethys to use PostgreSQL database:

    1. Stop the Tethys development server if it is running by pressing CTRL-C in the terminal.

    2. Configure the Tethys Portal to use the new Docker database using the tethys settings command:

    tethys settings --set DATABASES.default.ENGINE django.db.backends.postgresql --set DATABASES.default.NAME tethys_platform --set DATABASES.default.USER tethys_default --set DATABASES.default.PASSWORD pass --set DATABASES.default.HOST localhost --set DATABASES.default.PORT 5432

    1. Run the correct tethys db configure command for your system to prepare the database for use by the Tethys portal:

    # Windows System
set PGPASSWORD=mysecretpassword
tethys db configure

# Unix System
PGPASSWORD=mysecretpassword tethys db configure

    The default password for the postgis/postgis container is "mysecretpassword". If you changed it, you will need to replace it in the command above.

    Note

    Command line interfaces will not show the keystrokes when entering passwords. Don't worry if you are typing the password into the terminal and nothing shows up on the screen.

    1. Start Tethys the development server (tethys start) and verify that the app is still working.

Important

You will now need to start the "tethys_postgis" container each time you want to start the Tethys development server. You can do this using the Docker Desktop application or by running the following command:

docker start tethys_postgis