|
| 1 | +--- |
| 2 | +description: Learn how to set up an external PostgreSQL instance for your Appsmith application to manage session storage and caching effectively. |
| 3 | +toc_max_heading_level: 2 |
| 4 | +--- |
| 5 | + |
| 6 | +import Tabs from '@theme/Tabs'; |
| 7 | +import TabItem from '@theme/TabItem'; |
| 8 | + |
| 9 | +# Configure External PostgreSQL (AWS RDS) |
| 10 | + |
| 11 | +Appsmith relies on MongoDB, PostgreSQL and Redis. It uses PostgreSQL for SSO and workflows. By default in a single server deployment, it runs an embeded 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. |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +Before configuring an external PostgreSQL instance for your Appsmith deployment, ensure the following: |
| 16 | + |
| 17 | +- This guide applies only to **self-hosted Appsmith** instances. If you haven't installed Appsmith yet, refer to the [installation guides](/getting-started/setup/installation-guides). |
| 18 | +- You have access to an AWS account with permissions to create and manage RDS resources. |
| 19 | +- You have access to change environment variables on your Appsmith deployment. |
| 20 | + |
| 21 | +## Create PostgreSQL instance on AWS RDS |
| 22 | + |
| 23 | +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](#connect-appsmith-to-external-postgresql). |
| 24 | + |
| 25 | +1. **Create an RDS PostgreSQL instance:** |
| 26 | + - Sign in to the [AWS Management Console](https://console.aws.amazon.com/). |
| 27 | + - Navigate to **Aurora and RDS > Databases** and click **Create database**. |
| 28 | + - Choose **Standard Create** and select **PostgreSQL** as the engine. |
| 29 | + - Choose the latest 16.x option for engine version |
| 30 | + - Set a master username and choose the self-managed credentials management option. Save these credentials for later. |
| 31 | + - 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. |
| 32 | + - 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. |
| 33 | + - Complete the remaining configuration as needed and launch the instance. |
| 34 | + |
| 35 | +2. **Retrieve connection details:** |
| 36 | + - After the instance is available, note the **endpoint** (hostname), **port** (default: 5432), **database name**, **username**, and **password**. You will need these to configure Appsmith. |
| 37 | + |
| 38 | +## Connect Appsmith to external PostgreSQL |
| 39 | + |
| 40 | +Follow these steps to connect your Appsmith instance to the external PostgreSQL database: |
| 41 | + |
| 42 | +<Tabs queryString="current-command-type"> |
| 43 | + |
| 44 | +<TabItem label="Docker" value="docker-commands"> |
| 45 | + |
| 46 | +1. Navigate to the directory containing the `docker-compose.yml` file. |
| 47 | + |
| 48 | +2. Add or update the following environment variables with your PostgreSQL connection details: |
| 49 | + |
| 50 | + ```yaml |
| 51 | + APPSMITH_KEYCLOAK_DB_URL: postgresql://<username>:<password>@<hostname>/<database_name>?sslmode=require |
| 52 | + SQL_TLS_ENABLED: true |
| 53 | + SQL_TLS_DISABLE_HOST_VERIFICATION: true |
| 54 | + SQL_TLS: true |
| 55 | + ``` |
| 56 | +
|
| 57 | +:::note |
| 58 | +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. |
| 59 | +::: |
| 60 | + |
| 61 | +3. Update the Appsmith server configuration to apply the changes: |
| 62 | + |
| 63 | + ```bash |
| 64 | + docker-compose down && docker-compose up -d |
| 65 | + ``` |
| 66 | + |
| 67 | +</TabItem> |
| 68 | + |
| 69 | +<TabItem label="Kubernetes" value="kubernetes-commands"> |
| 70 | + |
| 71 | +1. Navigate to the directory containing your `values.yaml` file for you deployment. |
| 72 | + |
| 73 | +2. Add or update the following environment variables with your PostgreSQL connection details: |
| 74 | + |
| 75 | + ```yaml |
| 76 | + applicationConfig: |
| 77 | + APPSMITH_KEYCLOAK_DB_URL=postgresql://<username>:<password>@<hostname>/<database_name>?sslmode=require |
| 78 | + SQL_TLS_ENABLED: true |
| 79 | + SQL_TLS_DISABLE_HOST_VERIFICATION: true |
| 80 | + SQL_TLS: true |
| 81 | + ``` |
| 82 | + |
| 83 | +:::note |
| 84 | +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. |
| 85 | +::: |
| 86 | + |
| 87 | +3. Apply the environment variables: |
| 88 | + |
| 89 | + ```bash |
| 90 | + helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml |
| 91 | + ``` |
| 92 | + |
| 93 | +4. Restart the deployment: |
| 94 | + |
| 95 | + ```bash |
| 96 | + # if using a statefulset: |
| 97 | + kubectl rollout restart statefulset/appsmith-ee -n appsmith-ee |
| 98 | + # if using a deployment: |
| 99 | + kubectl rollout restart deployment/appsmith-ee -n appsmith-ee |
| 100 | + ``` |
| 101 | + |
| 102 | +</TabItem> |
| 103 | + |
| 104 | +</Tabs> |
| 105 | + |
| 106 | +## Troubleshooting |
| 107 | + |
| 108 | +If you face connection issues: |
| 109 | +- Double-check the RDS endpoint, port, database name, username, and password. |
| 110 | +- Ensure the RDS instance is accessible from your Appsmith server (check VPC, subnet, and security group settings). |
| 111 | +- Confirm that the PostgreSQL instance is accepting connections from the Appsmith server’s IP address. |
| 112 | +- Verify that the PostgreSQL user has the necessary privileges. |
| 113 | + |
| 114 | +If you continue facing issues, contact support using the chat widget available in the bottom-right corner of this page. |
| 115 | + |
| 116 | +## See also |
| 117 | + |
| 118 | +- [Configure External MongoDB](/getting-started/setup/instance-configuration/custom-mongodb-redis): Learn how to set up an external MongoDB instance. |
0 commit comments