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 Docker container.

sudo docker exec -t retool-onpremise_postgres_1 \
    pg_dump hammerhead_production --no-acl --no-owner --clean \
    -U  postgres > retool_db_dump.sql

This dumps the data into a file named retool_db_dump.sql in the directory that you ran the command.

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.

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_PASSWORD={a random string}

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


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?