Skip to main content

Configure External PostgreSQL (AWS RDS)

Appsmith relies on MongoDB, PostgreSQL and Redis. It uses PostgreSQL for SSO and workflows. By default in a single server deployment, it runs an embedded instance of each within the container. You can also switch to an external PostgreSQL instance to enable better performance, scalability, and reliability. This page provides steps on how to set up an external PostgreSQL instance on AWS RDS and how to connect it to your Appsmith instance.

Prerequisites​

Before configuring an external PostgreSQL instance for your Appsmith deployment, ensure the following:

  • This guide applies only to self-hosted Appsmith instances. If you haven't installed Appsmith yet, refer to the installation guides.
  • You have access to an AWS account with permissions to create and manage RDS resources.
  • You have access to change environment variables on your Appsmith deployment.

Create PostgreSQL instance on AWS RDS​

Follow these steps to set up a PostgreSQL instance on AWS RDS for Appsmith. If you already have a PostgreSQL instance, skip to Connect Appsmith to external PostgreSQL.

  1. Create an RDS PostgreSQL instance:

    • Sign in to the AWS Management Console.
    • Navigate to Aurora and RDS > Databases and click Create database.
    • Choose Standard Create and select PostgreSQL as the engine.
    • Choose the latest 16.x option for engine version
    • Set a master username and choose the self-managed credentials management option. Save these credentials for later.
    • For most deployments, you can start with db.t4g.small as the instance type and scale it as needed. We recommend gp3 storage type, allocating at least 20GB of storage, and checking the box "Enable storage autoscaling" allowing up to 100GB.
    • In the connectivity section, ensure the instance is in the correct VPC and subnets. Configure security groups to allow inbound connections from your Appsmith containers.
    • Complete the remaining configuration as needed and launch the instance.

  2. Retrieve connection details:

    • After the instance is available, note the endpoint (hostname), port (default: 5432), database name, username, and password. You will need these to configure Appsmith.

Connect Appsmith to external PostgreSQL​

Follow these steps to connect your Appsmith instance to the external PostgreSQL database:

note

Encrypted connections are required. PostgreSQL uses TLS (often called SSL); set sslmode=require in APPSMITH_KEYCLOAK_DB_URL and use the environment variables in the steps below. On AWS RDS, encrypted connections are commonly enforced (for example with the rds.force_ssl parameter). Ensure security groups and networking allow Appsmith to reach the database endpoint. If you need details about Temporal and host verification, see the note after the connection variables.

  1. Navigate to the directory containing the docker-compose.yml file.

  2. Add or update the following environment variables with your PostgreSQL connection details:

    APPSMITH_KEYCLOAK_DB_URL: postgresql://<username>:<password>@<hostname>/<database_name>?sslmode=require
    SQL_TLS_ENABLED: true
    SQL_TLS_DISABLE_HOST_VERIFICATION: true
    SQL_TLS: true
note

The SQL_TLS_DISABLE_HOST_VERIFICATION environment variable is only used by Temporal, which can have issues connecting to PostgreSQL over TLS on both Azure Database for PostgreSQL and AWS RDS. As an alternative, you can disable rds.force_ssl in your RDS parameter group, but this is less secure than disabling host verification.

  1. Update the Appsmith server configuration to apply the changes:

    docker-compose down && docker-compose up -d

Troubleshooting​

If you face connection issues:

  • Double-check the RDS endpoint, port, database name, username, and password.
  • Ensure the RDS instance is accessible from your Appsmith server (check VPC, subnet, and security group settings).
  • Confirm that the PostgreSQL instance is accepting connections from the Appsmith server’s IP address.
  • Verify TLS settings: sslmode=require in APPSMITH_KEYCLOAK_DB_URL and the TLS-related variables match the steps above.
  • Verify that the PostgreSQL user has the necessary privileges.

If you continue facing issues, contact support using the chat widget available in the bottom-right corner of this page.

See also​