Upgrade Infisical 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 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 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>