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

# Database Migration

**Goal:** Initialize the database schema and create the application user (run exactly once, before any services start)

### Prerequisites

Before proceeding, confirm:

✓ [Environment Configuration](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/environment-configuration) Step 2 completed with Phase 1 (superuser) credentials in `.env`

✓ PostgreSQL database created in [Database Setup](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/database-setup-self-managed-postgresql)

✓ You are on the host where Docker is installed

***

### Step 1: Verify Superuser Credentials in `.env`

Run:

```
cat config/.env | grep DB_USER
cat config/.env | grep DB_PASSWORD
```

### Step 2: Ensure Docker Is Ready

Docker group membership from [Server Infrastructure Setup](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/server-infrastructure-setup) only takes effect in a new shell session. Prepare Docker for this session:

{% code expandable="true" %}

```
# creates the docker group, in case it wasn't already created during Docker installation
sudo groupadd docker

# adds the current user to the docker group so Docker commands can run without sudo      
sudo usermod -aG docker $USER

# refreshes the current session's group membership immediately, without needing to log out
newgrp docker

# verifies Docker is actually reachable and working in this session                     
docker run hello-world
​
```

{% endcode %}

**Success:** `docker run hello-world` completes without error\
**Failure:** If `docker run hello-world` still fails, log out and back in (instead of using `newgrp docker`), then retry

### Step 3: Run the Migration

Run:

```
./deploy.sh --service flyway-migration
```

### Step 4: Verify Migration Succeeded

Wait 1–2 minutes, then run:

```
docker logs flyway-migration
docker inspect flyway-migration --format='{{.State.ExitCode}}'
docker ps -a | grep flyway-migration
```

**Success:**

* Exit code is `0`
* Logs show "Successfully applied X migration(s)" and application user created
* Status shows `Exited (0)`

**Failure:** Non-zero exit code, error messages, or `Exited (1)`. See Migration failed in [Troubleshooting](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/troubleshooting). Do not proceed until this succeeds.<br>

### Step 5: Update `.env` to Application User Credentials (Phase 2)

The Flyway migration created the application user. Update `.env` with the application user credentials:

```
nano config/.env
```

Set these two values in the file:

```
DB_USER=<user>
DB_PASSWORD='<your app-user password>'
```

{% hint style="info" %}
**Note:** `flyway-migration` is a one-time job-it runs, initializes the schema, creates the application user, and exits. It will not run again.
{% endhint %}

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

{% column %}

{% endcolumn %}

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