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

# Upgrade and Rollback

## **Upgrade**

**Goal:** Move an existing deployment to a newer Hivel release without losing data, and revert cleanly if needed.

### Pre-Upgrade Steps

Before starting any upgrade:

1. **Take a manual RDS snapshot** (see [Backup and Restore](/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/backup-and-restore.md)). This provides a known-good restore point if the upgrade fails.
2. **Learn what's changing:** Contact your Hivel account contact or email <support@hivel.ai> to get:
   * Which service image tags are changing
   * Whether this release includes a new database migration
   * Any additional steps required for this specific release
3. **Note the migration status:** Record whether a new migration is included. This determines Step 3 of the upgrade

## Upgrade Execution

### **Step 1: Stop Services**

On the VM:

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

### **Step 2: Update Images**

On the VM:

```
./deploy.sh --update
```

### **Step 3: Run Database Migration (if included)**

**Only if Hivel confirmed a new migration is included.**

a. Switch to Phase 1 (root/master) credentials in `config/.env` (Environment Configuration). Migrations require elevated privileges and will fail against the application-user credentials left from your last install.

b. Run the migration:

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

c. Once migration completes successfully, switch `config/.env` back to Phase 2 (application-user) credentials before continuing.

**Skip this entire step if no new migration is included.**

### **Step 4: Restart Services**

On the VM:

```
./deploy.sh --start
```

### **Step 5: Validate the Upgrade**

Run verification commands on the VM:

```
./deploy.sh --status
./deploy.sh --health
```

Both commands should show every service as Up/healthy. Re-run the full checklist from Verification and Access: endpoints, UI, and integrations should all pass.

**Note: Additional Steps May Apply**

Confirm with <support@hivel.ai> whether your specific release requires additional steps beyond the steps above.

\
Rollback (If Upgrade Fails)
---------------------------

### **Step 1: Assess the Situation**

* Did this release include a database migration? (Check your pre-upgrade notes or contact Hivel.)
* Are services failing validation or health checks?

### **Step 2: Revert Application Code**

1. Revert to the previous service image tags (undo the tags you updated in Step 2 of upgrade)
2. Redeploy:

```
   ./deploy.sh --update
```

Or for individual services:

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

### **Step 3: Restore Database (if migration was included)**

**Skip this step if no migration was included in the release.**

If the release included a database migration, reverting application code alone is insufficient. Flyway migrations cannot be easily reversed.

1. **Contact Hivel support before proceeding:** running older application code against an already-migrated schema can behave unpredictably
2. Restore the pre-upgrade RDS snapshot you took in Pre-Upgrade Steps (see Backup and Restore)
3. Re-run the Validation Checklist to confirm the rollback succeeded

<br>

{% columns %}
{% column %} <a href="/self-managed-hivel-deployment/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/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/virtual-private-cloud/aws/hivel-on-premises-deployment-guide-aws/uninstall-and-cleanup.md" class="button primary" data-icon="forward">Uninstall and Cleanup</a>
{% endcolumn %}
{% endcolumns %}