From b6dbfee6795a047c57d4dc442b3e74f85be1132c Mon Sep 17 00:00:00 2001 From: ClydeW Date: Thu, 13 Aug 2026 14:08:12 +0200 Subject: [PATCH 1/5] Document self-service PostgreSQL server parameter tuning for Mendix on Azure Customers can now tune PostgreSQL server parameters on the shared Flexible Server via the Azure Portal or CLI (deny-assignment restriction lifted, MXFORAZURE-717). Adds a new page covering safe parameters, dangerous parameters to avoid, and testing/troubleshooting guidance, and cross-links it from the configuration overview and support pages. --- .../mx-azure/configuration/_index.md | 1 + .../mx-azure-postgresql-parameter-tuning.md | 209 ++++++++++++++++++ .../deployment/mx-azure/mx-azure-support.md | 3 + 3 files changed, 213 insertions(+) create mode 100644 content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md diff --git a/content/en/docs/deployment/mx-azure/configuration/_index.md b/content/en/docs/deployment/mx-azure/configuration/_index.md index cb5ceb1d683..dab3f11b7aa 100644 --- a/content/en/docs/deployment/mx-azure/configuration/_index.md +++ b/content/en/docs/deployment/mx-azure/configuration/_index.md @@ -93,6 +93,7 @@ The following configurations can be modified directly through the [Microsoft Azu | Deploy Private Link Service to expose Mendix apps in other Azure virtual networks | For more information, see [Using Private Link Service to expose Mendix apps in other Azure virtual networks](/developerportal/deploy/mendix-on-azure/configuration/interconnecting-networks/#pls). | | Deploy Private Endpoints to establish connectivity between Mendix apps and other services | For more information, see [Accessing private services via Private Endpoints](/developerportal/deploy/mendix-on-azure/configuration/interconnecting-networks/#pe-internal). | | Override DNS configuration on the vNet hosting Mendix on Azure | For more information, see [DNS name resolution towards resources in other networks](/developerportal/deploy/mendix-on-azure/configuration/interconnecting-networks/#name-resolution-dns-override). | +| Tune server parameters on the shared PostgreSQL Flexible Server | For more information, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). | ### The Mendix on Azure Managed Resource Group {#mrg} diff --git a/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md b/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md new file mode 100644 index 00000000000..87fcfa6d553 --- /dev/null +++ b/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md @@ -0,0 +1,209 @@ +--- +title: "Tuning PostgreSQL Server Parameters" +url: /developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/ +description: "Describes how to tune PostgreSQL server parameters for a Mendix on Azure cluster, and which parameters must not be changed." +weight: 50 +--- + +## Introduction + +Every Mendix on Azure cluster stores the data of all its Mendix app environments in a single shared Azure Database for PostgreSQL Flexible Server. You can change the server parameters of that server yourself, either in the Microsoft Azure Portal or with the Azure CLI. This is useful when the default configuration does not suit your workload, for example when complex [OQL](/refguide/oql/) queries spill sorts and hash joins to disk instead of keeping them in memory. + +This document describes how to change these parameters, which parameters are safe to tune, and which parameters you must leave alone. + +Tuning the database for your own apps is a customer responsibility under the [shared responsibility model for Mendix on Azure](/developerportal/deploy/mendix-on-azure/support/#shared-responsibility-model-for-mendix-on-azure). You choose the values, you validate them against your own workload, and you own the result. Mendix and Microsoft remain responsible for operating the underlying PostgreSQL service itself. + +{{% alert color="warning" %}} +Azure role-based access control cannot grant write access to individual server parameters. As a result, you have write access to all PostgreSQL server parameters of the shared server, including parameters that can crash the server, cause data loss, or weaken its security posture. Mendix does not validate the values you set. Change only the parameters listed in [Parameters You Can Tune](#tunable), and never change the parameters listed in [Parameters You Must Not Change](#dangerous). +{{% /alert %}} + +## Prerequisites + +Before you begin, make sure to fulfill the following prerequisites: + +* Ensure that you have the Owner or Contributor role on the Mendix on Azure Managed Application, so that you can open the resources in the [Managed Resource Group of your Mendix on Azure environment](/developerportal/deploy/mendix-on-azure/configuration/#mrg). +* Ensure that you have a representative test cluster available. Validate every change there before you apply it to a production cluster. +* Ensure that you know which apps share the server. All app environments in the cluster use the same PostgreSQL server, so a parameter change affects all of them. + +## Changing Parameters in the Microsoft Azure Portal {#portal} + +To change a server parameter in the Microsoft Azure Portal, perform the following steps: + +1. Sign in to the [Microsoft Azure Portal](https://portal.azure.com). +2. Go to the [Managed Resource Group of your Mendix on Azure environment](/developerportal/deploy/mendix-on-azure/configuration/#mrg). +3. Select the PostgreSQL server resource (type: Azure Database for PostgreSQL Flexible Server). +4. Go to **Settings > Server parameters**. +5. Search for the parameter name, set the new value, and click **Save**. + +If the parameter requires a restart, the Azure Portal marks it as pending restart and the new value only takes effect after you restart the server. + +{{% alert color="info" %}} +Restarting the PostgreSQL server interrupts all database connections from all app environments in the cluster. Plan restarts in a maintenance window. To request a fixed maintenance window for the server, raise a support ticket as described in [Configuring Mendix on Azure](/developerportal/deploy/mendix-on-azure/configuration/). +{{% /alert %}} + +## Changing Parameters with the Azure CLI {#cli} + +To set a parameter with the Azure CLI, use the following command: + +```bash +az postgres flexible-server parameter set \ + --resource-group \ + --server-name \ + --name work_mem \ + --value 131072 +``` + +Memory parameters are expressed in kilobytes, so the value `131072` sets `work_mem` to 128 MB. + +To check whether a parameter you changed is waiting for a server restart, use the following command: + +```bash +az postgres flexible-server parameter show \ + --resource-group \ + --server-name \ + --name max_worker_processes \ + --query isConfigPendingRestart +``` + +## Changing Parameters with SQL {#sql} + +Some parameters can also be set from a PostgreSQL session, without touching the server configuration at all. This takes effect immediately and affects nothing outside the session or role you change. + +{{% alert color="info" %}} +Network access to the primary PostgreSQL server is restricted by [Network Security Group](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) rules, as described in [Direct App Database Access](/developerportal/deploy/mendix-on-azure/configuration/direct-database-access/). If you cannot open a session against the server, use the [Microsoft Azure Portal](#portal) or the [Azure CLI](#cli) instead. +{{% /alert %}} + +To set a parameter for the current session only, use the following statements: + +```sql +SET work_mem = '128MB'; +SET hash_mem_multiplier = 3.0; +SET max_parallel_workers_per_gather = 4; +``` + +To set a parameter for a database role, so that it applies to every new session opened by that role, use the following statements: + +```sql +ALTER ROLE mendix SET work_mem = '128MB'; +ALTER ROLE mendix SET hash_mem_multiplier = 3.0; +ALTER ROLE mendix SET max_parallel_workers_per_gather = 4; +``` + +To verify the values that are in effect, use the following statements: + +```sql +SHOW work_mem; +SELECT name, setting, source FROM pg_settings WHERE source <> 'default'; +``` + +{{% alert color="info" %}} +Only parameters with the `USERSET` context can be set with SQL. Parameters with a `SIGHUP` context, such as `max_parallel_workers`, and parameters with a `POSTMASTER` context, such as `max_worker_processes`, are server-level settings. Change those in the [Microsoft Azure Portal](#portal) or with the [Azure CLI](#cli). To see the context of a parameter, query `SELECT name, context FROM pg_settings WHERE name = '';`. +{{% /alert %}} + +## Parameters You Can Tune {#tunable} + +The following parameters are validated for use on Mendix on Azure. The context of a parameter determines how you can change it and whether a restart is needed. + +| Parameter | Context | How to Change | Restart Required | +| --- | --- | --- | --- | +| `work_mem` | `USERSET` | SQL, Azure Portal, or Azure CLI | No | +| `hash_mem_multiplier` | `USERSET` | SQL, Azure Portal, or Azure CLI | No | +| `max_parallel_workers_per_gather` | `USERSET` | SQL, Azure Portal, or Azure CLI | No | +| `max_parallel_workers` | `SIGHUP` | Azure Portal or Azure CLI | Only if you also raise `max_worker_processes` to accommodate the new value | +| `max_worker_processes` | `POSTMASTER` | Azure Portal or Azure CLI only, not SQL | Yes, always | +| `random_page_cost` | `USERSET` | SQL, Azure Portal, or Azure CLI | No | + +{{% alert color="warning" %}} +`max_worker_processes` is a postmaster-context parameter. It cannot be set from a SQL session, and a new value only takes effect after a full restart of the PostgreSQL server, which drops the database connections of every app environment in the cluster. Raise it only when you have first confirmed that `max_parallel_workers` cannot be raised far enough without it, and only during a maintenance window. +{{% /alert %}} + +### Recommended Values by Workload + +The following values are starting points, not targets. Measure the effect on your own queries before you keep a value. + +| Parameter | Transactional Apps | Reporting and Analytical Queries | Purpose | +| --- | --- | --- | --- | +| `work_mem` | 32-64 MB | 128-256 MB | Memory available per sort or hash operation before it spills to disk | +| `hash_mem_multiplier` | 2.0 | 3.0 | Multiplier applied to `work_mem` for hash-based operations | +| `max_parallel_workers_per_gather` | 2-4 | 4-8 | Parallel workers a single query may use | +| `max_parallel_workers` | 4 | 8-16 | Parallel workers available across all queries, capped by `max_worker_processes` | +| `max_worker_processes` | 8 (default) | 16 | Total background worker slots on the server, raise only to make room for a higher `max_parallel_workers` | +| `random_page_cost` | 1.1 | 1.1 | Cost estimate for random reads, lowered because the server uses SSD storage | + +{{% alert color="warning" %}} +`work_mem` is allocated per sort or hash operation, not per connection, so a single query can consume several multiples of it and each parallel worker adds its own allocation. Keep `work_mem` multiplied by the expected number of concurrent connections and parallel workers per query well below half of the server memory. Setting `work_mem` too high is the most common cause of out-of-memory conditions on the shared server, which affects all app environments in the cluster. +{{% /alert %}} + +## Parameters You Must Not Change {#dangerous} + +{{% alert color="warning" %}} +Changing any of the parameters below can crash the shared PostgreSQL server, cause permanent data loss, break the automated nightly backups and the read replica, or weaken the security posture of the server. Mendix cannot restore data lost this way, and support requests caused by these changes fall outside the [Mendix support coverage](/developerportal/deploy/mendix-on-azure/support/#example-unsupported-scenarios) for Mendix on Azure. +{{% /alert %}} + +| Parameter | Impact of Changing It | +| --- | --- | +| `shared_buffers` | Out-of-memory conditions and server crashes. The value is sized to the compute tier of the server. | +| `max_connections` | Memory exhaustion, or app environments that can no longer connect. The value is sized to the compute tier of the server. | +| `shared_preload_libraries` | Loads untrusted code into the server process at startup, and can prevent the server from starting at all. | +| `fsync`, `synchronous_commit` | Permanent and unrecoverable data loss if the server or the underlying host fails. | +| `wal_level` | Breaks the read replica and the automated backup and point-in-time restore capability of the server. | +| `max_wal_size`, `checkpoint_timeout` | Long recovery times after a failure, and unpredictable restart behavior. | + +To change the compute tier or the storage performance tier of the server instead, use the **Edit Cluster** flow in the Mendix on Azure Portal, as described in [Configuring Mendix on Azure](/developerportal/deploy/mendix-on-azure/configuration/). + +## Testing a Change + +To measure whether a parameter change helps, perform the following steps: + +1. Establish a baseline. In your SQL client, enable timing: + + ```sql + \timing on + ``` + +2. Capture the query plan before the change: + + ```sql + EXPLAIN (ANALYZE, BUFFERS) SELECT ...; + ``` + +3. Apply the tuning in the current session only: + + ```sql + SET work_mem = '128MB'; + SET max_parallel_workers_per_gather = 4; + ``` + +4. Run the same query again and compare the execution time and the plan. Look for the disappearance of external merge or disk-based hash operations, and for the appearance of `Parallel` nodes in the plan. +5. Keep the change only if the improvement is repeatable across several runs. Then apply it at role level or at server level. + +## Troubleshooting + +The following table lists common outcomes and how to address them. + +| Symptom | What to Check | +| --- | --- | +| The query is not faster after raising `max_parallel_workers_per_gather` | Run `SHOW max_parallel_workers;`. If it is `0` or too low, the server has no worker slots to hand out, and `max_parallel_workers` needs raising first. Confirm with `EXPLAIN` that the plan contains `Parallel` nodes at all, because not every query can be parallelized. | +| The query still spills to disk | Raise `work_mem` further in a session and re-run `EXPLAIN (ANALYZE, BUFFERS)`. Sort and hash nodes report whether they used memory or disk. | +| Apps report out-of-memory errors or dropped connections after a change | Lower `work_mem` immediately and reset any other memory-related change. The shared server is used by every app environment in the cluster. | +| A new value does not take effect | Check whether the parameter is waiting for a restart, as described in [Changing Parameters with the Azure CLI](#cli). | +| You need to undo a session or role change | Run `RESET work_mem;` for the current session, or `ALTER ROLE mendix RESET work_mem;` for a role. | +| You need to undo a server change | Set the parameter back to its default value in **Settings > Server parameters** in the Microsoft Azure Portal. | + +## Best Practices + +Apply the following practices when tuning server parameters: + +* Change one parameter at a time, so that you can attribute any change in behavior to it. +* Test in a non-production cluster first, then at session level, then at role level, and only then at server level. +* Prefer session-level and role-level changes over server-level changes. They are reversible without a restart and they do not affect other app environments. +* Record the original value of every parameter you change, so that you can revert it. +* Monitor CPU, memory, and connection metrics for at least 24 hours after a change. +* Avoid parameter changes as a first response to slow queries. Missing indexes and inefficient OQL are more common causes, and fixing those in the app benefits every environment. + +## Read More + +* [Direct App Database Access](/developerportal/deploy/mendix-on-azure/configuration/direct-database-access/) +* [Support for Mendix on Azure](/developerportal/deploy/mendix-on-azure/support/) +* [Server parameters in Azure Database for PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-server-parameters) +* [Resource Consumption](https://www.postgresql.org/docs/current/runtime-config-resource.html) diff --git a/content/en/docs/deployment/mx-azure/mx-azure-support.md b/content/en/docs/deployment/mx-azure/mx-azure-support.md index 862b647b657..79d17eb40a3 100644 --- a/content/en/docs/deployment/mx-azure/mx-azure-support.md +++ b/content/en/docs/deployment/mx-azure/mx-azure-support.md @@ -96,6 +96,8 @@ The following customizations are related to establishing connectivity to and fro * Configure Private Link Service to expose Mendix apps in other Azure virtual networks. * Configure Private Endpoints to establish connectivity between Mendix apps and other services. +You can also tune the server parameters of the shared Azure Database for PostgreSQL Flexible Server directly in the Microsoft Azure Portal or with the Azure CLI. Only a small set of parameters is safe to change, and some parameters can cause server crashes or permanent data loss. Before changing any parameter, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). + Mendix limits customization to what is described above to ensure a consistent, predictable, and scalable customer experience. ## Access to your Environment by Mendix @@ -179,6 +181,7 @@ Mendix does not provide technical support in the following example scenarios: * Requests to make configuration changes to underlying Azure services beyond what is offered as self-service in the Mendix on Azure and Mendix on Kubernetes Portal. Since such changes are not possible with this service, customer may consider to adopt Mendix on Kubernetes (formerly Mendix for Private Cloud) instead. * Requests for any other type of customization on the resources deployed in the customer's Azure subscription. Since such customization is not possible with this service, customer may consider to adopt Mendix for Kubernetes (formerly Mendix for Private Cloud) instead. * Requests to fix security vulnerabilities in one of the managed components beyond what is automatically pushed during the weekly and quarterly update cycles. +* Requests to diagnose or restore service after a customer changed PostgreSQL server parameters on the shared database server. Choosing and validating these values is a customer responsibility. For more information, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). {{% alert color="warning" %}} The state of the resources in the customer subscription nor overall service availability are proactively monitored by Mendix. As a consequence, any degradation in service will only reactively be addressed by Mendix after customer has notified Mendix of such degradation by filing a support ticket. From 1b0c9638482847b62254dc0c249f808193fd7044 Mon Sep 17 00:00:00 2001 From: ClydeW Date: Thu, 13 Aug 2026 14:10:39 +0200 Subject: [PATCH 2/5] Make PostgreSQL tuning mention a bullet item in the customization list --- content/en/docs/deployment/mx-azure/mx-azure-support.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/deployment/mx-azure/mx-azure-support.md b/content/en/docs/deployment/mx-azure/mx-azure-support.md index 79d17eb40a3..5ce49a37781 100644 --- a/content/en/docs/deployment/mx-azure/mx-azure-support.md +++ b/content/en/docs/deployment/mx-azure/mx-azure-support.md @@ -95,8 +95,7 @@ The following customizations are related to establishing connectivity to and fro * Override DNS configuration on the subnet hosting AKS nodes. * Configure Private Link Service to expose Mendix apps in other Azure virtual networks. * Configure Private Endpoints to establish connectivity between Mendix apps and other services. - -You can also tune the server parameters of the shared Azure Database for PostgreSQL Flexible Server directly in the Microsoft Azure Portal or with the Azure CLI. Only a small set of parameters is safe to change, and some parameters can cause server crashes or permanent data loss. Before changing any parameter, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). +* Tune server parameters of the shared Azure Database for PostgreSQL Flexible Server. Only a small set of parameters is safe to change, and some parameters can cause server crashes or permanent data loss. Before changing any parameter, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). Mendix limits customization to what is described above to ensure a consistent, predictable, and scalable customer experience. From 9e66ec8b17bbd01ef0a5c5c5a238d9a1ecb261b7 Mon Sep 17 00:00:00 2001 From: ClydeW Date: Thu, 13 Aug 2026 14:13:07 +0200 Subject: [PATCH 3/5] Mention best-effort support ticket option for uncertain PostgreSQL parameters --- .../configuration/mx-azure-postgresql-parameter-tuning.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md b/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md index 87fcfa6d553..312d768d699 100644 --- a/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md +++ b/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md @@ -17,6 +17,10 @@ Tuning the database for your own apps is a customer responsibility under the [sh Azure role-based access control cannot grant write access to individual server parameters. As a result, you have write access to all PostgreSQL server parameters of the shared server, including parameters that can crash the server, cause data loss, or weaken its security posture. Mendix does not validate the values you set. Change only the parameters listed in [Parameters You Can Tune](#tunable), and never change the parameters listed in [Parameters You Must Not Change](#dangerous). {{% /alert %}} +{{% alert color="info" %}} +If you are unsure whether a parameter not listed on this page can be safely changed, raise a support ticket through the Mendix on Azure Portal as described in [Support for Mendix on Azure](/developerportal/deploy/mendix-on-azure/support/#raising-support-tickets). Mendix processes these tickets on a best-effort basis. +{{% /alert %}} + ## Prerequisites Before you begin, make sure to fulfill the following prerequisites: From caddc3fbf740de6d68bc10371a9b74926e930541 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Thu, 13 Aug 2026 14:55:50 +0200 Subject: [PATCH 4/5] Update mx-azure-postgresql-parameter-tuning.md --- .../mx-azure-postgresql-parameter-tuning.md | 71 +++++++++++++++---- 1 file changed, 56 insertions(+), 15 deletions(-) diff --git a/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md b/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md index 312d768d699..36cf10383f9 100644 --- a/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md +++ b/content/en/docs/deployment/mx-azure/configuration/mx-azure-postgresql-parameter-tuning.md @@ -71,12 +71,14 @@ az postgres flexible-server parameter show \ ## Changing Parameters with SQL {#sql} -Some parameters can also be set from a PostgreSQL session, without touching the server configuration at all. This takes effect immediately and affects nothing outside the session or role you change. +Some parameters can also be set from a PostgreSQL session, without modifying the server configuration. This takes effect immediately and affects nothing outside the session or role you change. {{% alert color="info" %}} Network access to the primary PostgreSQL server is restricted by [Network Security Group](https://learn.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) rules, as described in [Direct App Database Access](/developerportal/deploy/mendix-on-azure/configuration/direct-database-access/). If you cannot open a session against the server, use the [Microsoft Azure Portal](#portal) or the [Azure CLI](#cli) instead. {{% /alert %}} +### Setting a Parameter for the Current Session + To set a parameter for the current session only, use the following statements: ```sql @@ -85,6 +87,8 @@ SET hash_mem_multiplier = 3.0; SET max_parallel_workers_per_gather = 4; ``` +### Setting a Parameter for a Database Role + To set a parameter for a database role, so that it applies to every new session opened by that role, use the following statements: ```sql @@ -93,6 +97,8 @@ ALTER ROLE mendix SET hash_mem_multiplier = 3.0; ALTER ROLE mendix SET max_parallel_workers_per_gather = 4; ``` +### Verifying Values + To verify the values that are in effect, use the following statements: ```sql @@ -118,7 +124,7 @@ The following parameters are validated for use on Mendix on Azure. The context o | `random_page_cost` | `USERSET` | SQL, Azure Portal, or Azure CLI | No | {{% alert color="warning" %}} -`max_worker_processes` is a postmaster-context parameter. It cannot be set from a SQL session, and a new value only takes effect after a full restart of the PostgreSQL server, which drops the database connections of every app environment in the cluster. Raise it only when you have first confirmed that `max_parallel_workers` cannot be raised far enough without it, and only during a maintenance window. +The `max_worker_processes` parameter is a postmaster-context parameter. It cannot be set from a SQL session, and a new value only takes effect after a full restart of the PostgreSQL server, which drops the database connections of every app environment in the cluster. Raise it only when you have first confirmed that `max_parallel_workers` cannot be raised far enough without it, and only during a maintenance window. {{% /alert %}} ### Recommended Values by Workload @@ -135,7 +141,7 @@ The following values are starting points, not targets. Measure the effect on you | `random_page_cost` | 1.1 | 1.1 | Cost estimate for random reads, lowered because the server uses SSD storage | {{% alert color="warning" %}} -`work_mem` is allocated per sort or hash operation, not per connection, so a single query can consume several multiples of it and each parallel worker adds its own allocation. Keep `work_mem` multiplied by the expected number of concurrent connections and parallel workers per query well below half of the server memory. Setting `work_mem` too high is the most common cause of out-of-memory conditions on the shared server, which affects all app environments in the cluster. +The `work_mem` parameter is allocated per sort or hash operation, not per connection, so a single query can consume several multiples of it and each parallel worker adds its own allocation. Keep `work_mem` multiplied by the expected number of concurrent connections and parallel workers per query well below half of the server memory. Setting `work_mem` too high is the most common cause of out-of-memory conditions on the shared server, which affects all app environments in the cluster. {{% /alert %}} ## Parameters You Must Not Change {#dangerous} @@ -159,19 +165,19 @@ To change the compute tier or the storage performance tier of the server instead To measure whether a parameter change helps, perform the following steps: -1. Establish a baseline. In your SQL client, enable timing: +1. Establish a baseline. In your SQL client, enable timing by running the following command: ```sql \timing on ``` -2. Capture the query plan before the change: +2. Capture the query plan before the change by running the following command: ```sql EXPLAIN (ANALYZE, BUFFERS) SELECT ...; ``` -3. Apply the tuning in the current session only: +3. Apply the tuning in the current session only by running the following command: ```sql SET work_mem = '128MB'; @@ -183,16 +189,51 @@ To measure whether a parameter change helps, perform the following steps: ## Troubleshooting -The following table lists common outcomes and how to address them. +The following section lists common outcomes and how to address them. -| Symptom | What to Check | -| --- | --- | -| The query is not faster after raising `max_parallel_workers_per_gather` | Run `SHOW max_parallel_workers;`. If it is `0` or too low, the server has no worker slots to hand out, and `max_parallel_workers` needs raising first. Confirm with `EXPLAIN` that the plan contains `Parallel` nodes at all, because not every query can be parallelized. | -| The query still spills to disk | Raise `work_mem` further in a session and re-run `EXPLAIN (ANALYZE, BUFFERS)`. Sort and hash nodes report whether they used memory or disk. | -| Apps report out-of-memory errors or dropped connections after a change | Lower `work_mem` immediately and reset any other memory-related change. The shared server is used by every app environment in the cluster. | -| A new value does not take effect | Check whether the parameter is waiting for a restart, as described in [Changing Parameters with the Azure CLI](#cli). | -| You need to undo a session or role change | Run `RESET work_mem;` for the current session, or `ALTER ROLE mendix RESET work_mem;` for a role. | -| You need to undo a server change | Set the parameter back to its default value in **Settings > Server parameters** in the Microsoft Azure Portal. | +### Raising `Max_parallel_workers_per_gather` Does Not Increase Speed + +The query is not faster after raising the value of the`max_parallel_workers_per_gather` parameter. + +#### Solution + +Run `SHOW max_parallel_workers;`. If it is `0` or too low, the server has no worker slots to hand out, and `max_parallel_workers` needs raising first. Confirm with `EXPLAIN` that the plan contains `Parallel` nodes at all, because not every query can be parallelized. + +### Query Spills + +The query still spills to disk. + +#### Solution + +Raise `work_mem` further in a session and re-run `EXPLAIN (ANALYZE, BUFFERS)`. Sort and hash nodes report whether they used memory or disk. + +### Out-of-Memory Errors + +Apps report out-of-memory errors or dropped connections after a change + +#### Solution + +Lower `work_mem` immediately and reset any other memory-related change. The shared server is used by every app environment in the cluster. + +### Value Does Not Take Effect + +A new value does not take effect. + +#### Solution + +Check whether the parameter is waiting for a restart, as described in [Changing Parameters with the Azure CLI](#cli). + +### Undo Change + +You need to undo a session, role, or server change. + +#### Solution + +Perform one of the following actions, depending on the type of change that you want to undo: + +* To undo a change to the current session, run `RESET work_mem;`. +* To undo a role change, run `ALTER ROLE mendix RESET work_mem;`. +* To undo a server change, set the parameter back to its default value in **Settings > Server parameters** in the Microsoft Azure Portal. ## Best Practices From 8c7410601faa4bcca4cc294113d4725fa880520e Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Thu, 13 Aug 2026 14:56:58 +0200 Subject: [PATCH 5/5] Update mx-azure-support.md --- content/en/docs/deployment/mx-azure/mx-azure-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/deployment/mx-azure/mx-azure-support.md b/content/en/docs/deployment/mx-azure/mx-azure-support.md index 5ce49a37781..5afd47753c0 100644 --- a/content/en/docs/deployment/mx-azure/mx-azure-support.md +++ b/content/en/docs/deployment/mx-azure/mx-azure-support.md @@ -95,7 +95,7 @@ The following customizations are related to establishing connectivity to and fro * Override DNS configuration on the subnet hosting AKS nodes. * Configure Private Link Service to expose Mendix apps in other Azure virtual networks. * Configure Private Endpoints to establish connectivity between Mendix apps and other services. -* Tune server parameters of the shared Azure Database for PostgreSQL Flexible Server. Only a small set of parameters is safe to change, and some parameters can cause server crashes or permanent data loss. Before changing any parameter, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). +* Tune the server parameters of the shared Azure Database for PostgreSQL Flexible Server. Only a small set of parameters is safe to change, and some parameters can cause server crashes or permanent data loss. Before changing any parameters, see [Tuning PostgreSQL Server Parameters](/developerportal/deploy/mendix-on-azure/configuration/postgresql-parameter-tuning/). Mendix limits customization to what is described above to ensure a consistent, predictable, and scalable customer experience.