> 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/upgrade-and-rollback.md).

# Upgrade and Rollback

Upgrade to a new Hivel version or roll back to a previous version

## Upgrade to a new Hivel version

### Step 1: Check for New Version

Hivel does not currently publish a public changelog or allow self-serve browsing of the ECR registry.

**Do this first:** Contact your Hivel representative or email <support@hivel.ai> to:

* Confirm a new version is available
* Obtain the new image tag
* Learn what the release contains
* Ask if the release includes a database migration

### Step 2: Take a Fresh Backup

Before upgrading, take a fresh backup of the PostgreSQL database. See [Backup and Restore](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/backup-and-restore).

### Step 3: Stop Services

On the host, run:

```bash
./deploy.sh --stop
```

### Step 4: Pull New Image Tags

**Application/Location:** Host

Pull the new image tags for the target version from ECR using the instructions your Hivel contact provided.

### Step 5: Redeploy

On the host, run:

```bash
./deploy.sh --vm
```

Or, for a targeted redeploy of a specific service:

```bash
./deploy.sh --service <name>
```

### Step 6: Run Database Migration (if applicable)

If your Hivel contact indicates the release includes a new database migration, complete this step. Otherwise, skip to Step 7.

**6a: Switch to Superuser Credentials**

Update `config/.env` to use Phase 1 (superuser) credentials. See [Environment Configuration](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/environment-configuration).

Migration requires elevated privileges and will fail against application-user credentials. See Migration Failed in [Troubleshooting](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/troubleshooting).

**6b: Run the Migration**

On the host, run:

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

Wait for the migration to complete successfully.

**6c: Switch Back to Application-User Credentials**

Update `config/.env` back to Phase 2 (application-user) credentials before continuing.

### Step 7: Restart Services

On the host, run:

```bash
./deploy.sh --restart
```

### Step 8: Verify the Upgrade

**Application/Location:** Host (via SSH)

Complete the validation checklist from [Verification and Access](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/verification-and-access) to confirm the upgrade succeeded.

## Rollback to Previous Version

If you need to revert to the previous image tag:

**Application/Location:** Host (via SSH)

1. Revert to the previous image tag using the steps above (Steps 3–8)

{% hint style="warning" %}
**Important:** If the upgrade included a database migration, redeploying the old image tag alone may not be sufficient. Flyway migrations are not easily reversible. You may need to restore the pre-upgrade backup. See [Backup and Restore](https://docs.hivel.ai/self-managed-hivel-deployment/on-premises/backup-and-restore).
{% endhint %}

**Contact Hivel support (**[**support@hivel.ai**](mailto:support@hivel.ai)**) before attempting to roll back a release that included a migration.**

***

#### Additional Considerations

`./deploy.sh --update` pulls new images, but a specific release may require additional steps beyond image pulling. Confirm with Hivel support at the time you perform the upgrade whether anything else applies to your release.

<br>

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/on-premises-generic/hivel-on-premises-deployment-guide-generic/backup-and-restore.md" class="button primary" data-icon="backward">Back to Backup and Restore</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

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