Upgrade Infisical Instance

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>