mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
123 lines
6.1 KiB
Plaintext
123 lines
6.1 KiB
Plaintext
---
|
|
|
|
title: "Upgrade Infisical Instance"
|
|
description: "How to upgrade Infisical self-hosted 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](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:**
|
|
- Use our [Upgrade Path Tool](https://app.infisical.com/upgrade-path) to analyze your upgrade path between your current version and target version.
|
|
- The tool will show you:
|
|
- **Breaking changes** that require action before upgrading
|
|
- **Database migrations** that may require additional settings or precautions
|
|
- **Step-by-step upgrade path** with intermediate versions if needed
|
|
- Review any breaking changes and plan necessary configuration updates before proceeding.
|
|
- Visit the [Infisical releases page](https://github.com/Infisical/infisical/releases) for a complete list of available versions.
|
|
|
|
|
|
|
|
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>
|