MidPoint Upgrade Guide

Last modified 01 Sep 2026 11:44 UTC
Table of Contents

This document describes the steps required to upgrade a MidPoint installation.. It not only lists the usual steps but explains risks and consideration for upgrade, therefore it is quite comprehensive.

The document focuses on upgrades of production environments. Upgrades of evaluation, demo, development, and similar environments can often be simplified to just a handful of commands.

This guide focuses primarily on the principles and procedures of upgrading midPoint. It is written with standalone (package-based) deployments in mind, but many of the concepts apply to other deployment models as well.

For containerized deployments (Docker, Kubernetes, and similar environments), the exact upgrade procedure depends on the deployment architecture and tooling being used. While the upgrade principles remain the same, deployment-specific aspects such as container images, persistent volumes, orchestration, and rollout strategies should be considered when planning the upgrade.

Therefore, this guide should not be considered the sole source of upgrade instructions for containerized deployments.

For a more practical, command-oriented approach, see Upgrade with Ninja. MidPoint distributions include the ninja tool, which provides commands for verifying upgrade readiness, executing database upgrades, and performing other upgrade-related tasks.

Please read the entire guide before starting the upgrade. MidPoint is a highly flexible platform that is often deployed in a wide variety of environments. There may be variations and extra steps. Make sure that you understand the entire process and all the steps that you need to do in your particular environment. Otherwise you may end up with an unusable and inconsistent system.

Quick Upgrade Checklist

  1. Check the Upgrade Path

  2. Run the Pre-upgrade Checks

  3. Stop the System

  4. Create Backup

  5. Upgrade Binaries

  6. Upgrade Database Schema (repository and audit)

  7. Start midPoint

  8. Reindex Repository Objects

  9. Review connector versions and initial objects

  10. Test the system

  11. Return the System to Production

  12. Follow-Up

Pre-Upgrade Steps And Adjustments

The crucial part comes even before the upgrade itself. Measure twice, upgrade once. Proper preparation and backups are essential for a smooth upgrade.

Check the Upgrade Path

Check, whether the version you are upgrading to is supported, ideally one with a sufficient support lifetime remaining. Do not stop at a version that is already end-of-life (EOL), or one that is close to reaching EOL. If necessary, use such versions only as intermediate steps in the upgrade path to a fully supported release.

Make sure your upgrade path is supported. You can upgrade from one major/minor version to the subsequent one (4.9 → 4.10) Upgrade is only supported between consecutive major/minor versions.

  • 4.9 → 4.10 is supported.

  • 4.8 → 4.10 is not supported.

To get from 4.8 to 4.10, you will need to upgrade to 4.9 first.

It is possible to upgrade from one LTS version to the other.

  • 4.4 → 4.8 is supported, because it is an upgrade from one LTS to the subsequent one.

Upgrade to the latest maintenance version available for your release first! This is especially important for LTS to LTS upgrade (e.g. 4.0.x to 4.4.x) because pre-upgrade checks (like schema deprecation warnings) are likely not available in the maintenance versions before the new LTS (4.4) is released. For example, first upgrade your 4.0 LTS to 4.0.4 which was released shortly after 4.4 LTS release.

The Long-Term Support page provides general principles of midPoint upgradability, release notes provide specific details for each particular release.

Run the Pre-upgrade Checks

MidPoint deployment includes the built-in ninja tool which you can use to check for deprecated and removed functionality.

The recommended approach is to use the ninja version that corresponds to the target midPoint version you are upgrading to. However, if the upgrade path is officially supported, you can also use the ninja version from your current deployment. This applies, for example, when:

  • upgrading between subsequent releases of the same minor version (e.g. 4.9.1 → 4.9.2),

  • upgrading from the last maintenance release of one minor version to the first release of the next minor version.

Firstly, make sure that parts of your deployment are compatible with each other and upgradable via pre-upgrade-check. It verifies that the current midPoint repository version matches the expected source version for the upgrade.

ninja.sh pre-upgrade-check

There are two items being checked:

  • database schema version

  • midPoint cluster nodes version

For more information see Pre-upgrade check command documentation.

Check, that the repository object are compatible with the new version of midPoint via command verify.

ninja.sh verify

For more detail see verify command documentation.

The verify command only checks repository and configuration objects stored in the repository. However, deployment-specific customizations should be reviewed separately before the upgrade. This may include custom connectors, schema extensions, overlays, custom libraries, or other custom code. Verify that these customizations are compatible with the target midPoint version. Make sure to re-apply them after the upgrade.

The best practice is to avoid use of any deprecated functionality as soon as possible. Therefore we strongly recommend to re-configure the system not to use any deprecated functionality before the upgrade.

Upgrades of system that are using functionality that is planned for removal is not supported at all. Attempt to upgrade such system may result in incorrect data processing, data corruption or loss.

The purpose of the ninja tool is to identify potential upgrade risks and deprecated functionality. However, ninja cannot detect all possible issues. Release notes should always be reviewed carefully, as some upgrade-related changes require manual assessment and cannot be detected automatically.

As a general rule, configuration changes that are known before the upgrade should be implemented before the upgrade. In some cases, adjustments may be easier to perform after the upgrade, and in rare situations they may not be possible beforehand. Such approaches should only be taken by experienced administrators who fully understand the implications. Whenever possible, the complete upgrade procedure should first be tested in a development or testing environment before it is performed in production.

Verify Environment Compatibility

In addition to verifying the repository state, ensure that the deployment environment satisfies the requirements of the target midPoint version. Newer releases may require newer versions of the Java runtime, the database server, or other infrastructure components. Verify these prerequisites before proceeding with the upgrade.

Stop the System

MidPoint upgrades require downtime. Plan for that. The technical upgrade itself usually takes only a few minutes, but post-upgrade verification and testing may take considerably longer. Use upgrades of test environments to estimate the expected downtime.

Before shutting down the system, consider disabling scheduled reconciliation and synchronization tasks. This is recommended because:

  • bundled connector versions may change during the upgrade, causing tasks to fail until resource configuration is updated,

  • automatic task execution can make troubleshooting more difficult by generating additional log noise,

  • in rare cases, tasks may rely on deprecated or removed functionality and produce unexpected results after the upgrade.

In deployments using a load balancer or reverse proxy, consider disabling user access before the upgrade. This prevents user interference and avoids confusion during the maintenance window. Ensure that administrators can still access the system through an alternative route.

Once preparations are complete, shut down all midPoint server processes. The database server should remain available for the upgrade process, but no midPoint instance should be accessing it.

In clustered deployments, all midPoint nodes must be shut down before starting the upgrade. Do not upgrade cluster nodes one by one while other nodes are still running an older version. Running different midPoint versions against the same repository is not supported during the upgrade process and may lead to inconsistent behavior or repository corruption.

Create Backup

A crucial step is to make sure that you have a fresh backup that can be restored. Regular backups and restore procedure testing should be part of your usual operational procedures. However, an upgrade process may pose a risk of mistakes that can damage your data. Therefore, it is worth double-checking that a fresh backup exists and is ready to be used if necessary.

Backing up the database after shutting down the server ensures that all recent changes have been written to the database and that no data is lost. Although the final backup should be created after stopping the midPoint server, creating an additional backup before running the upgrade checks is recommended. This provides a safe recovery point before any upgrade preparation begins.

A backup of the repository database is especially important. Database schema upgrades are generally not reversible, and the repository contains not only configuration, but also internal midPoint state and metadata that cannot be reconstructed directly from source systems. This includes, for example, shadow objects and their links to identities, synchronization state, tokens, and audit history.

A backup of the midPoint home directory is also strongly recommended. The home directory contains deployment-specific files that are not stored in the repository database, such as keystores, non-bundled connectors, and other custom configuration. Losing these files may prevent the upgraded deployment from starting correctly or from operating as expected. In midPoint versions up to 4.10, the home directory may also contain custom extension schema definitions.

Read the release notes very carefully. You should read the release notes for the version that you are upgrading to. Pay special attention to the Changes and Upgrade sections. All important upgrade-specific details are described there.

Upgrade Binaries

The exact procedure for upgrading midPoint binaries depends on the deployment type.

For traditional installations, midPoint is commonly installed in a directory such as /opt/midpoint. Upgrade the installation by replacing the existing binaries with the binaries from the new distribution package. At a minimum, this includes the contents of the bin and lib directories. It is also recommended to update documentation, samples, README files, and other files provided by the distribution.

For containerized deployments, the upgrade is typically performed by deploying a new midPoint container image. The exact procedure depends on the container platform and deployment tooling being used.

Regardless of the deployment type, preserve the midPoint home directory during the upgrade. The midPoint home directory contains deployment-specific data such as configuration files, log files, schema extensions, non-bundled connectors, and cryptographic material (for example the keystore). This directory should be backed up before the upgrade and should not be replaced by files from the new distribution package.

Upgrade Database Schema (repository and audit)

Each midPoint release usually extends database schema with new tables, columns, indexes and similar database configuration.

MidPoint is distributed with SQL scripts that alter the database schema as necessary. The scripts are located in the doc/config/sql/native subdirectory of the distribution package. See Native repository for more information about upgrade scripts.

To run those scripts, you can use:

Database upgrade is thoroughly described in this document. There are also deployment specific details to consider, e.g. is the audit in the same database?

If you created the schema objects as non-superuser as described here, be sure to run all the missing CREATE EXTENSION commands as a superuser first.

The upgrade script is non-destructive. It changes database schema, but it does not affect the data. Database schema changes between midPoint versions are usually backwards-compatible. Therefore, in a usual case, update of the database schema is all that is needed.

However, there may be rare cases when the model has changed in a non-compatible way. This is likely to happen for major midPoint releases (e.g. MidPoint 5.0). In such cases, additional steps may be necessary. In rare cases when the schema changes in a radical way, complete export and re-import of data may be needed. In such cases the release notes will provide specific guidance.

Post-Upgrade Steps

At this point, the system should be ready for a careful start-up. Start midPoint server process. The users should be ideally still kept out, e.g. keeping the path through load balancer or reverse proxy disabled. Consider doing the following steps:

Reindex Repository Objects

After the database schema upgrade, it is recommended to run the Reindex Repository Objects task (GUI → About → Reindex Repository Objects). Reindexing recomputes repository-specific indexed and derived data for existing objects, ensuring that all objects are fully populated according to the repository schema used by the upgraded version.

Review Connector Versions

Most midPoint releases bring new versions of bundled connectors. This means that new connector versions appear in midPoint after the first post-upgrade startup, and the old connector versions will no longer work. Connector references (connectorRef) in affected resources need to be updated to point to the new connector versions.

Review Initial Objects

Many midPoint releases bring new and updated initial objects. Initial objects are automatically imported into the midPoint repository during the first post-upgrade startup. However, if the repository already contains an object with the same OID, midPoint does not overwrite it and leaves it unchanged. Initial objects are just initial configuration of midPoint, and many of them are expected to be customized. Therefore, midPoint cannot blindly overwrite them. Release notes for each midPoint release list initial objects that were added or updated. It is strongly recommended to review that list and consider manually updating the corresponding objects after the upgrade. The initial objects provided by a new release can be found in the doc/config/initial-objects/ subdirectory of the midPoint distribution package.

Re-enable Scheduled Tasks

When the necessary configuration adjustments are done, it is time to bring the system to full operation. If scheduled midPoint server tasks were disabled before the upgrade, now it is the right time to re-enable them. It is recommended to proceed gradually, enabling tasks one by one and watching for issues.

It may be a good idea to manually recompute or reconcile selected users before re-enabling scheduled processing. Problems are easier to diagnose on a single user than during large-scale task execution.

Restart the System

Before starting broader testing, it may be a good idea to restart the system. This provides an opportunity to verify that the upgraded system starts cleanly without errors or warnings. A planned maintenance window is often the best time for this verification.

Perform Post-upgrade Testing

Test the functionality of your system using your usual routines and tools. Execute prepared test scenarios and verify critical business processes. Critical issues may require immediate fixes or, in extreme cases, a rollback of the upgrade. In most cases, however, issues can be documented and addressed after the upgrade.

Return the System to Production

Re-enable the load balancer or reverse proxy and allow users to access the system again. Because no testing is perfect, continue monitoring system logs after the upgrade. Keep in mind that log messages may differ from the previous version, so existing alerting patterns may not work immediately.

Additional monitoring and manual review are often useful during the first days after the upgrade.

Follow-Up

Now that the release was successful, we know that we will not need to roll back the release. There is a couple of recommended steps to clean up the installation. These steps do not need to happen immediately after upgrade. However, do not procrastinate for too long, as these minor issues may turn into big problems in a long run.

An easy task is to delete old connector objects in midPoint repository. Objects that represent old connector versions will just get into your way, causing import errors as connector version is no longer unambiguous. Simply delete the objects using menu:Repository objects[] page.

Now it is the time to fix non-critical issues that were discovered during post-upgrade testing. MidPoint is running, there is no downtime, this is much less stressful than trying to fix them during upgrade.

Finally, use ninja and read through release note again to find out which functionality was deprecated in midPoint version that you are running. Make a plan to stop using that functionality and migrate to newer mechanisms. Doing that now rather than waiting for the next upgrade will open up new opportunities and configuration options. It will save a lot of time and head-scratching before your next midPoint upgrade.

Q&A

How Do I Roll Back?

The recommended rollback procedure is based on restoring backups taken before the upgrade.

Database schema upgrades are generally not reversible. Upgrade scripts are not intended to be used as downgrade scripts, and there is usually no supported way to revert the repository schema to a previous version.

If a rollback is required:

  1. Stop all running midPoint instances.

  2. Restore the repository database from a backup or snapshot taken before the upgrade.

  3. Restore the previous midPoint binaries (or deploy the previous container image version).

  4. Restore the midPoint home directory and any other deployment-specific persistent data if they were modified during the upgrade.

  5. Start the original version of midPoint and verify that the system operates correctly.

For this reason, it is strongly recommended to create and verify database backups before performing any repository upgrade.

It is possible to merge multiple updates to a single process?

Yes, it is. For example, when upgrading from 4.7 to 4.10, you may deploy the 4.10 binaries directly instead of performing separate binary upgrades through 4.8 and 4.9.

However, all intermediate upgrade steps still need to be considered. In particular:

  • Apply all database upgrade scripts in the correct order. Database schema upgrades are cumulative, so it is not possible to skip directly from 4.8 to 4.10 by executing only the 4.10 upgrade script.

  • Review the release notes for every intermediate version.

  • Perform any required configuration changes described in those release notes.

This approach can significantly reduce upgrade time because testing is performed only once. However, it also increases risk. Intermediate pre-upgrade checks are not performed, and diagnosing issues may be more difficult because the root cause can originate from any skipped version.

For this reason, grouped upgrades are recommended only for experienced midPoint administrators.

See Also

Was this page helpful?
YES NO
Thanks for your feedback