Retool's storage database

In most self-hosted setups, user information and documents are stored in a PostgreSQL Docker container with a persistent volume. As usage grows, it's often useful to switch to an externally hosted database for redundancy.

Retool recommends allocating at least 60GB of storage when you set up a new Retool instance. If you're migrating an existing instance, you might need more space.

📘

Database permissions

Retool's database user must have the CREATEDB privilege, own the hammerhead_production database, and also own the public schema within the hammerhead_production database.

If you want to use an external database, follow the steps below.

1. Export data from Retool's Docker container

To export data from Retool's PostgreSQL container, run this command on the virtual machine hosting the Retool containers, in the Retool directory.

docker-compose exec postgres \
    pg_dump hammerhead_production --no-acl --no-owner --clean \
    -U  retool_internal_user -f retool_db_dump.sql

This dumps the data into a file named retool_db_dump.sql in the root of the volume used by the Retool PostgreSQL container.

2. Migrate the data to an external hosted database

To migrate the data to an external database, run the following command. Replace $DB_CONNECTION_URI with the PostgreSQL connection string that connects to your externally hosted database. Make sure the URI is formatted correctly.

docker-compose exec postgres \
    psql $DB_CONNECTION_URI -f retool_db_dump.sql

3. Configure Retool to use the external database

The docker.env files defines several Retool options, including which database to connect to. The lines you need to edit follow this pattern:

POSTGRES_DB=hammerhead_production
POSTGRES_USER=retool_internal_user
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_PASSWORD={a random string}

Edit those variables to correspond with the database you created. For example:

POSTGRES_DB=retooldb
POSTGRES_USER=retool_user
POSTGRES_HOST=retool.xxxxxxxxxx.us-east-2.rds.amazonaws.com
POSTGRES_PORT=5432
POSTGRES_PASSWORD=xyzabc

Alternatively, you can delete the five environment variables and instead specify a database connection string like this:

DATABASE_URL=postgres://retool_user:[email protected]:5432/retooldb

4. Restart the Retool server

After updating the Retool configuration, run this command from the retool_onpremise directory to restart the server.

sudo docker-compose up -d

Did this page help you?