Set up Retool Database on Self-hosted deployments

Learn how to configure Retool Database on Self-hosted Retool deployments.

Retool Database is a PostgreSQL resource provided by Retool. You can query it like any other resource, but it also includes a spreadsheet-like interface for interacting with data.

Retool Database is separate from the storage database, which is required in self-hosted Retool deployments to store user information and logs.

On self-hosted deployments, you can use your own PostgreSQL database to host Retool Database. Your database automatically connects to the main Retool backend service for your deployment. This allows you to use Retool Database's interface for managing data.

Retool Database is included in all pricing plans. Because you control your own PostgreSQL database on self-hosted deployments, there are no data limits or overages for Retool Database on self-hosted deployments.

Use Docker Compose PostgreSQL container

Using Docker to host Retool Database is not recommended for storing production data, and Retool recommends externalizing the database

Retool Database runs as a separate PostgreSQL service in your Docker deployment, using PostgreSQL version 14.3 by default. Retool Database is automatically created and provisioned on new deployments which use Docker Compose.

Existing Docker Compose deployments

When upgrading from an existing deployment on versions 2.112 or earlier, you must run a one-time script to generate credentials for Retool Database before you upgrade.

To generate credentials for Retool Database, follow these steps.

1. Check out the latest version of the retool-onpremise repository.
2. Run retooldb_upgrade.sh.

After running retooldb_upgrade.sh, follow the usual process to update your Retool instance. Retool Database will then be configured as a resource and ready to use. You do not need to run retooldb_upgrade.sh on any future version updates.

Specify an external PostgreSQL database

Organizations with managed deployments using Kubernetes, Helm, or ECS Fargate must specify a PostgreSQL database to use for the backend. Organizations using Docker Compose can use the built-in PostgreSQL container, or specify an external database.

Requirements

To use Retool Database on managed deployments, you need:

• A PostgreSQL database running version 13 or later. On self-hosted Retool versions earlier than 3.14, you need a PostgreSQL database running version 14.3 or later.
• Credentials for a database user with permissions to create databases and roles. These credentials are used once to create the database and generate a generic user, who only has access to the created database. Further interactions, such as querying the database, use the generic user and its permissions.

Import existing data

Your supplied PostgreSQL database can be empty or populated with data, but Retool always creates a new database for each of your environments. To import existing data to Retool Database, use pg_dump and psql commands. You can use the connection strings dropdown to find the database host, name, user, password, and port for the current environment.

Your pg_dump and psql commands might use the following structure.

pg_dump EXISTING_DATABASE_CONNECTION_STRING > pg_dump.sql

psql RETOOL_CONNECTION_STRING < pgdump.sql

1. Add database configuration

Navigate to {your-domain}/resources?setupRetoolDB=1 on Retool and fill out the form with the following fields.

Setting	Description
Database host	The URL or IP address.
Database name	The name of the database.
Database username	The username.
Database password	The password.
Database port	The port number.
Use SSL/TLS	Connect with SSL/TLS.

Select Test your connection to confirm you can connect to Retool Database.

2. Save your resource

Click Save and initialize to save your Retool Database settings. You can now use with the Database editor UI to configure and interact with your Retool Database tables.