> 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/archive/generic/hivel-on-premises-deployment-guide-generic/7.-database-migration.md).

# 7. Database Migration

On-Prem Deployment Guide (Generic)

**Goal:** initialize the Hivel database schema and create the application user, exactly once, before any services start.

**Prerequisites:** Environment Configuration Step 2 completed with Phase 1 (root/master) credentials currently in .env; the "insightly" database created (Database Setup, Step 3).

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

```
cd /opt/docker-onprem-installer

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

If your credentials live in a secrets manager:

```
# Retrieve credentials from your secrets manager, e.g.:
aws secretsmanager get-secret-value --secret-id <your-secret-name> --query SecretString --output text

# Update .env file with root credentials
```

### Step 2: Run Flyway Migration

**Note:** This must be done ONCE on VM1 only before deploying any services.

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

What flyway-migration does:

* Creates all Hivel database schemas and tables
* Creates the application user: \<user>
* Sets up the default password: \<password> (unless customized)
* Initializes all required database objects

### Step 3: Verify Migration Completed

Wait for migration to complete (usually 1–2 minutes):

```
# 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
```

**Expected result** (success indicators):

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

**If it fails (failure indicators):**

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

See Migration failed in [Troubleshooting](/archive/generic/hivel-on-premises-deployment-guide-generic/11.-troubleshooting.md).

**Warning:** Do not proceed until migration is successful.

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

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

# Save and exit
```

Verify the update:

```
cat config/.env | grep DB_USER
# Should show: DB_USER=<user>
```

**Note:** The flyway-migration service is a one-time job. It runs, initializes the database, and exits - it does not need to stay running.

**Next step:** Deployment Methods - bring up the actual Hivel services.

<br>

{% columns %}
{% column %} <a href="/archive/generic/hivel-on-premises-deployment-guide-generic/6.-environment-configuration.md" class="button primary" data-icon="backward">Environment Configuration</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/archive/generic/hivel-on-premises-deployment-guide-generic/8.-deployment-methods.md" class="button primary" data-icon="forward">Deployment Methods</a>
{% endcolumn %}
{% endcolumns %}