> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/rds-database-setup.md).

# RDS Database Setup

Set up a managed PostgreSQL database for Hivel services to connect to.

## **Provision RDS PostgreSQL Instance**

1. Go to AWS RDS Console and create a PostgreSQL database with these settings:
   * **Engine:** PostgreSQL 12–15 (tested versions for this deployment)
   * **Instance Class:** `db.t3.medium` or larger (minimum supported)
   * **Storage:** 20GB+ (gp3)
   * **Master Username:** `postgres` (fixed, do not change)
   * **Master Password:** Choose a strong password and save it securely (see [Security and Secrets](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/security-and-secrets))
2. **Configure the DB Parameter Group:**
   * Create a custom parameter group for your PostgreSQL version
   * Set `rds.force_ssl` to `0` (this deployment uses network-level isolation as the security boundary)
   * Attach the parameter group to your RDS instance
   * Reboot if AWS requires it
3. **Note these values for later:**

* RDS Endpoint (e.g., `mydb.xxxxx.ap-south-1.rds.amazonaws.com`)
* Port (usually 5432)
* Master Username
* Master Password

**Expected result:** RDS console shows status as **Available**.

4. **Configure RDS Security Group**

RDS must be accessible only from your VM. No external access.

1. Go to RDS Console → Your Database → **Connectivity & security**
2. Click on the Security Group
3. Edit inbound rules and add:
   * **Type:** PostgreSQL
   * **Port:** 5432
   * **Source:** VM Security Group ID

**Expected result:** connection test from the VM to RDS succeeds on port 5432.

## **Important: Credentials and Two-Phase Approach**

Hivel uses a two-phase credential approach for security:

### **Phase 1 (Database Migration):**

* Use the RDS master (`postgres`) credentials to run the Flyway migration.
* Flyway needs elevated privileges to create schemas, tables, and users.
* Include master credentials in `.env` for the migration step only.

### **Phase 2 (Services):**

* After migration completes, Flyway creates an application user with limited privileges
* Switch `.env` to use the application user credentials for all services
* This follows the least-privilege security principle

For credential management details, see [Security and Secrets](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/security-and-secrets).

## **Create the "insightly" Database**

You must create the `insightly` database before deploying services. ("insightly" is Hivel's legacy internal product name. This is the correct database name, not a placeholder to rename.)

### **Option A: Using psql (Direct Connection)**

Use this if you have network access from your VM (or your machine) to RDS:

```
# Connect to RDS
psql -h <your-rds-endpoint> -U <rds-username> -d postgres

# Create the database
CREATE DATABASE insightly;

# Exit
\q
```

**Expected result:** `CREATE DATABASE` executes with no error.

### **Option B: Using AWS RDS Query Editor**

Use this if you only have AWS console access:

1\. Go to AWS RDS Console → Your Database → Query Editor

2\. Connect to your database

3\. Run: CREATE DATABASE insightly;

**Expected result:** Query Editor reports successful execution.

If either option fails, see [Troubleshooting](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/troubleshooting).<br>

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/prerequisites-overview/verify-ec2-instance-requirements-resource-sizing.md" class="button primary" data-icon="backward">Back to Verify EC2 Instance</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/project-setup-and-environment-configuration.md" class="button primary" data-icon="forward">Project Setup and Environment Configuration</a>
{% endcolumn %}
{% endcolumns %}