Upgrading the Private Mendix Platform

Last modified: September 25, 2026

Introduction

If you have installed Private Mendix Platform before, you can upgrade it by doing the following steps, depending on whether you are running the upgrade through the installer GUI, or through a Helm chart.

Select the upgrade method based on the original installation method. That is to say, if you installed Private Mendix Platform in GUI mode, upgrade it in the same way. It is not possible to upgrade GUI installs by using Helm charts. A clean install would be necessary instead.

Upgrading Private Mendix Platform in GUI Mode

Ensure that your Mendix Operator is upgraded to a version compatible with the version of Private Mendix Platform to which you are upgrading.

For information about the required Mendix Operator version, refer to the Private Mendix Platform Release Notes for your target release, for example, 2.8.1. The required version of the Mendix Operator is listed in the Updates: Other Platform Components section.
If required, use the mxpc-cli configuration tool to upgrade your Mendix Operator. For more information about accessing the tool, see Install Private Mendix Platform in GUI Mode.

If you are upgrading from version 1.24 LTS to 2.8 LTS, make a backup of the Private Mendix Platform database by using the following command. The backup is required if you need to roll back the upgrade.

Private Mendix Platform does not support direct upgrades from versions older than 1.24 LTS. To upgrade from a version older than 1.24 LTS, upgrade first to version 1.24, and then upgrade to version 2.8 LTS by following the instructions below.

pg_dump -h <DB host> -U <DB mster username> -d <database name like mendix_mxplatform_database_xxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxx> -Fc  -f <local path like /tmp/pmp_db_backup.dump>

A pg_dump tool with a version equal to or higher than database POSTGRES version is required.

If you are working within a pod that contains pg_dump, make sure to use the kubectl cp command to copy the backup to your local computer. This helps prevent the loss of the backup if the pod is deleted:

kubectl cp -n <psql-client-pod namespace> psql-client-pod-name:/tmp/pmp_backup.dump ./pmp_backup.dump

To obtain the database name, use the following command:

kubectl get secret mxplatform-database -n <namespace for installing PMP> -o jsonpath='{.data.config}' | base64 -d

Ensure that the number of replicas is no higher than 1. If you have manually changed the default value, make sure you revert it to 1 before attempting the upgrade.
Run the command ./installer platform -n=<namespace name>, where -n indicates the namespace where your Private Mendix Platform is installed.
Click Upgrade Namespace.
Verify the following settings:
- Persist Config - When enabled, this setting locks the Private Mendix Platform configuration, so that it can no longer be modified from the user interface.
- Project Management - Recommended. Enables you to create and manage your app projects. Enables app projects and related settings across the portal. Must be enabled for CI/CD capabilities.
- Marketplace - Recommended. Enables you to use the Private Platform's Marketplace capabilities to upload, import and manage Marketplace contents. The Marketplace enabled here is hosted entirely within your Private Mendix Platform.
- Marketplace Approvals - Optional. If enabled, contents that users publish to the private Marketplace require administrator approval before publishing.
- Marketplace Import - Optional. Enables content import with an external source.
- IdP - Optional. Enable users to login using SSO by configuring your IdP integration.
- Webhook - Optional. Webhooks allow to send information between platform and external systems, and can be triggered by events around Apps, Users, Groups, Marketplace and CI/CD.
Click Run Upgrade.

Upgrading Private Mendix Platform in Helmfile Mode

Update the values file with new registry details as follows:
- Operator charts - registry.mendix.com/private-cloud
- PMP charts - registry.mendix.com/private-platform
- Maia charts - registry.mendix.com/maia
- svix server - svix/svix-server
- docgen - registry.mendix.com/docgen
Update the tags in the values file for images.
Remove the following lines from mx-privatecloud-operator-versions:
```
mx_m2ee_metrics:
  tag: *mx_m2ee_metrics_tag
```
Download the new Operator chart from the OCI registry by performing the following steps:
1. Create PAT on In the User Settings, create a Personal Access Token (PAT) the following scope: mx:registry:access (Access OCI Registry).
2. Run the following command: oras login -u pat -p <pat-xxx> registry.mendix.com.
3. Run the following command: helm pull oci://registry.mendix.com/private-cloud/charts/mx-privatecloud-operator-installer --version 0.2.43

Create the registry secret:

kubectl create secret docker-registry private-registry-secret \
    --docker-server=registry.mendix.com \
    --docker-username=pat \
    --docker-password="$PAT" \
    --namespace=<ns-name> \
    --dry-run=client -o yaml > registry-secret.yaml

kubectl apply -f registry-secret.yaml

Add the created secret as follows to Operator value file:

imagePullSecrets:
    - name: private-registry-secret

7. Upgrade the Operator CRDS by running the following command: `kubectl apply -f mx-privatecloud-operator-crd/crds/`.
8. Upgrade the Operator release by performing the following command: `helm upgrade operator mx-privatecloud-operator-installer-0.2.43.tgz -f <operatorValues file> --namespace <ns-name>`.
9. After the Operator is upgraded, fetch the image from `registry.mendix.com` by running the following command: `oras pull registry.mendix.com/private-platform/installer-helmfile:2.8.1`.
10. Unzip the Helm chart and upgrade the Private Mendix Platform release by running the following command: `helmfile  --file ./oras-artifact/helmfile-config/helmfile.d/helmfile.yaml  --state-values-file ../../../<pmp values yaml file> apply`.
11 Add `imagePullSecret` to the Private Mendix Platform *values* file:

```text
global:
    imageRegistry:
        pullSecrets:
            - private-registry-secret

Post-Upgrade Steps

After upgrading your Private Mendix Platform, you may need to perform some additional steps, depending on your starting and target releases. For more information about these post-upgrade considerations, refer to the sections below.

Pipeline Changes When Upgrading to Version 2.8.1 and Newer

Private Mendix Platform versions older than 2.8.1 used a single, unnamed pipeline for all apps. Version 2.8.1 adds the option to designate multiple draft pipelines, in addition to the main pipeline. For more information, see Configuring the Pipeline Type.

When upgrading to Private Mendix Platform 2.8.1 or newer, the following changes are made automatically:

Pipelines must now have names, so the existing pipeline is given the placeholder name (No name).
The existing pipeline becomes the main pipeline for all apps. Apps continue to build and deploy through it with no interruption.

You can rename the pipeline at any time (for example to Production-Build). You can also create draft pipelines for individual apps while MAIN continues to serve everything else. Builds or deployments already in progress during the upgrade either complete or fail gracefully and can be re-triggered.

Role Permissions Change When Upgrading to Version 2.8.0 and Newer

Private Mendix Platform version 2.8.0 adds the option to configure dynamic role management on a more granular level than before. Because of that, you may encounter an issue where previously created environments are not visible after an upgrade from a version older than 2.8.0.

This issue is caused by missing deployment-related permissions for custom CI/CD roles after the upgrade. To fix it, reassig the required deployment permissions.

Rolling Back An Upgrade

To restore the Private Mendix Platform database to version 1.24 LTS and downgrade Private Mendix Platform from version 2.8 LTS to 1.24 LTS, perform the following steps:

Take note of the current number of Private Mendix Platform replicas, and then scale the number down to 0.
Ensure that the Private Mendix Platform pods have been terminated.
For security, back up your Private Mendix Platform 2.8 database (mendix_mxplatform_database_xxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxx).
Delete the Private Mendix Platform 2.8 database and create a new database with the same name by using the following commands:
1. DROP DATABASE mendix_mxplatform_database_xxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxx;
2. CREATE DATABASE mendix_mxplatform_database_xxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxx;

Restore the Private Mendix Platform 1.24 database by using the following command:

pg_restore -U <DB master user> -h <DB host> -d <database name like mendix_mxplatform_database_xxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxx> -v /tmp/pmp_db_backup.dump

Connect to the mendix_mxplatform_database_xxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxx database, and verify that all required Private Mendix Platform tables are present and have been successfully restored.
Use the Private Mendix Platform 1.24 installer to change the Private Mendix Platform image from 2.8 to 1.24.
Scale the number of Private Mendix Platform replicas to the previous value, ensure that at least one Private Mendix Platform pod is running.
Check the Private Mendix Platform pod status and logs.
If any permissions are missing after rebuilding the database, manually reconfigure the Database Owner and the required Database, Schema, Table, and Sequence permissions.