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

# Database Migration

On-Prem Deployment Guide (Azure)

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

**Goal:** confirm `.env` currently holds Phase 1 (admin) credentials before running migration - running migration with the application user's limited privileges will fail.

**Prerequisites:** Environment Configuration completed with Phase 1 credentials; database created (Database Setup).

Before running migration, ensure .env file has admin/root credentials:

```
cd /opt/hivel-onprem
 
# Verify .env has admin credentials
cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD
 
# Should show:
# DB_USER=your_admin_username
# DB_PASSWORD='your_admin_password'
```

**If credentials are stored in Azure Key Vault:**

```
# Retrieve credentials from Key Vault
az keyvault secret show --vault-name <your-vault-name> --name <secret-name> --query value -o tsv
 
# Update .env file with admin credentials from Key Vault
```

### Step 2: Run Flyway Migration

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

{% hint style="warning" %}
**Important :** This must be done **ONCE** on VM only before deploying any services.
{% endhint %}

**Prerequisites:** admin credentials confirmed in .env (previous step).

**On VM:**

```
cd /opt/hivel-onprem
 
# Ensure .env has admin 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 default password: \<password> (unless customized)
* Initializes all required database objects

**Expected result:** the command completes and exits - see verification below for what "success" looks like.

**If it fails:** see Migration failed in [Troubleshooting](/self-managed-hivel-deployment/virtual-private-cloud/azure/hivel-on-premises-deployment-guide-azure/troubleshooting.md).

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

**Success indicators:**

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

**Failure indicators:**

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

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

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

**After migration succeeds, update the .env file to use the 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
```

**If you customized the password:**

* Ensure the password in .env matches what was set during migration

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

**Next step:** Deployment Methods.<br>

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

{% column %}

{% endcolumn %}

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