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

The Retool PostgreSQL database user must have superuser privileges on the hammerhead_production database. This is necessary to perform essential tasks, such as installing updates.

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_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