> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Infisical Instance

> How to upgrade Infisical self-hosted instance

<Tip>
  Planning an upgrade? Use the [Infisical Upgrade Tool](https://upgrade.infisical.com/) to map out your upgrade path and review notable changes between your current and target versions.
</Tip>

Keeping your Infisical instance up to date is key to making sure you receive the latest performance improvements, security patches, and feature updates.
We release updates approximately once a week, which may include new features, bug fixes, performance enhancements, and critical security patches.

Since secrets management is a critical component of your infrastructure, we aim to avoid disruptive changes that will impact fetching secrets in downstream clients.
If a release requires specific attention, a note will be attached to the corresponding [release](https://github.com/Infisical/infisical/releases) version.

During an upgrade, two key components are updated:

* **Infisical Application:** The core application code is updated.
* **PostgreSQL Database Schema:** Schema migrations run automatically to ensure your database remains in sync with the updated application.

> **Before You Upgrade:**\
> **Always back up your database.** While our automated migration system is robust, having a backup ensures you can recover quickly in the event of an issue.

## Automated Schema Migrations

In previous versions (prior to `v0.111.0-postgres`), schema migrations had to be executed manually before starting the application.
Now, migrations run automatically during boot-up. This improvement streamlines the upgrade process, reduces manual steps, and minimizes the risk of inconsistencies between your database schema and application code.

### Benefits of Automated Migrations

* **Seamless Integration:**\
  Migrations are now part of the boot-up process, removing the need for manual intervention.

* **Synchronous Upgrades:**\
  In multi-instance deployments, one instance acquires a lock and performs the migration while the others wait. This ensures that if a migration fails, the rollout is halted to prevent inconsistencies.

* **Reduced Room for Error:**\
  Automatic migrations help ensure that your database schema always remains in sync with your application code.

## Upgrade Steps

1. **Back Up Your Data:**
   * Ensure you have a complete backup of your Postgres database.
   * Verify that your backup is current and accessible.

2. **Plan Your Upgrade Path:**
   * Head over to the [Infisical releases page](https://github.com/Infisical/infisical/releases) and review the releases between your current version and the one you're upgrading to.
   * Keep an eye out for breaking changes or migration notes — these will tell you if any extra steps or configuration changes are needed before you proceed.

3. **Start the Upgrade Process:**
   * Launch the new version of Infisical. During startup, the application will automatically compare the current database schema with the updated schema in the code.
   * If any differences are detected, Infisical will apply the necessary migrations automatically.

4. **Multi-Instance Coordination:**
   * In environments with multiple instances, one instance will acquire a lock and perform the migration while the other instances wait.
   * Once the migration is complete, all instances will operate with the updated schema.

5. **Verify the Upgrade:**
   * Review the logs for any migration errors or warnings.
   * Test basic functionality to ensure the upgrade was successful.

## Troubleshooting

### UI Caching Issues After Upgrade

After upgrading your Infisical instance, you may encounter UI-related issues such as:

* Strange loading behavior
* Components not rendering correctly
* Unexpected errors in the browser console
* Features appearing broken or unresponsive

These issues are often caused by browser caching of the previous version's static assets.

**Solution:**

1. **Try a private/incognito browser window first** - This is the quickest way to test if the issue is cache-related.
2. **Clear your browser cache** if the private window works correctly:
   * **Chrome/Edge:** Press `Ctrl+Shift+Delete` (Windows/Linux) or `Cmd+Shift+Delete` (Mac)
   * **Firefox:** Press `Ctrl+Shift+Delete` (Windows/Linux) or `Cmd+Shift+Delete` (Mac)
   * **Safari:** Press `Cmd+Option+E` or go to Develop menu > Empty Caches
3. **Hard refresh the page** by pressing `Ctrl+F5` (Windows/Linux) or `Cmd+Shift+R` (Mac)

<Note>
  Caching issues are temporary and typically resolve themselves as the cache expires, but manually clearing the cache provides immediate resolution.
</Note>

## Downgrade Considerations

While we recommend staying up-to-date with the latest version, there may be scenarios where you need to downgrade your Infisical instance.

<Warning>
  **Database Compatibility:** Downgrading can be complex due to database schema changes. Always ensure you have proper backups before attempting any version changes.
</Warning>

### Safe Downgrade Process

1. **Prepare Database Snapshot:**
   * Create a database snapshot/backup **before** upgrading to the target version
   * Ensure the snapshot is from a version compatible with your desired downgrade target

2. **Stop Infisical Services:**
   * Gracefully shut down all Infisical instances to prevent data corruption

3. **Restore Database:**
   * Restore your database from the pre-upgrade snapshot
   * **Critical:** Do not attempt to downgrade with a database that has run migrations from a newer version

4. **Deploy Previous Version:**
   * Deploy the previous Infisical version
   * Verify that the version matches the database schema in your snapshot

5. **Verify Functionality:**
   * Test critical functionality to ensure the downgrade was successful
   * Monitor logs for any compatibility issues

<Note>
  The safest approach for downgrades is to restore to a known good state (both application and database) rather than attempting to reverse individual migrations.
</Note>