> 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/database-migration.md).

# Database Migration

On-prem Deployment Guide (AWS)

**Goal:** Initialize the database schema and create the application user (run once before any service starts).

**Prerequisites:**

* Environment Configuration completed with Phase 1 (root/master) credentials in `.env`
* "insightly" database created in RDS (see RDS Database Setup, Step 3)
* RDS connectivity verified from VM (see Environment Configuration, Step 3)

### Step 1: Verify Root Credentials in .env

**Application/System:** EC2 VM and AWS Secrets Manager (if applicable)

**Verify that `config/.env` contains root/master credentials:**

```
cd /opt/hivel-onprem

# Verify .env has root credentials
cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD
# Should show:
# DB_USER=your_rds_master_username
# DB_PASSWORD='your_rds_master_password'
```

**If RDS uses AWS Secrets Manager:**

```
# Retrieve credentials from Secrets Manager
aws secretsmanager get-secret-value --secret-id <your-secret-name> --query SecretString --output text

# Update .env file with root credentials from Secrets Manager
```

**Do not proceed until root credentials are correctly set in** `.env`.

### Step 2: Run Flyway Database Migration

**Application/System:** EC2 VM (Docker)

**Critical:** This step runs **once only, before any other services start**. It initializes the entire database.

```
cd /opt/hivel-onprem
# Ensure .env has root credentials (for migration)
# Then deploy only the flyway-migration service
./deploy.sh --service flyway-migration
```

**What this does:**

* Creates all Hivel database schemas and tables
* Creates the application user (`<user>`)
* Sets default application password
* Initializes all required database objects

**Wait 1–2 minutes for completion.**

### Step 3: Verify Migration Success

**Application/System:** EC2 VM (Docker)

```
# Check migration logs
docker logs flyway-migration

# Check exit code (0 = success, non-zero = failure)
docker inspect flyway-migration --format='{{.State.ExitCode}}'

# Check container status
docker ps -a | grep flyway-migration
```

**Success indicators:**

* Exit code: `0`
* Logs contain: "Successfully applied X migration(s)"
* Logs contain: "user `<user>` created"
* Container status: "Exited (0)"

**Failure indicators:**

* Exit code: non-zero (e.g., 1, 2)
* Logs show error messages
* Container status: "Exited (1)" or similar

**If migration failed:** See [Troubleshooting: Migration Failed](https://docs.hivel.ai/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/troubleshooting). **Do not proceed to the next step.**

### Step 4: Update .env with Application User Credentials

**After migration succeeds, update .env file to use application user:**

```
# Edit .env file
nano config/.env
# Update these values:
DB_USER=<user>
DB_PASSWORD='<password>'  # Default password (or your custom password)

# Save and exit
```

**Notes:**

* Default password is `<password>` (if you did not customize it during migration).
* If you customized the password earlier, use the same password here.
* Passwords with special characters must be in single quotes.

#### Important Notes

* The `flyway-migration` container is a one-time initialization job. It runs, migrates the database, and exits. It does not need to remain running.
* Rerunning migration on an already-initialized database may cause errors. Run it only once per RDS database.
* All subsequent services use the application user credentials.<br>

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/ecr-access-configuration.md" class="button primary" data-icon="backward">Back to ECR Access Configuration</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/deployment-methods.md" class="button primary" data-icon="forward">Deployment Methods</a>
{% endcolumn %}
{% endcolumns %}