ALTER SETTINGS

Synopsis

ALTER SETTINGS RUNTIME ( key: value, ... )

ALTER SETTINGS CONFIGURATION 'name' ( key: value, ... )

ALTER SETTINGS CONSTANT @Module.Name VALUE 'value' IN CONFIGURATION 'config'

ALTER SETTINGS DROP CONSTANT @Module.Name IN CONFIGURATION 'config'

CREATE CONFIGURATION 'name' [( key: value, ... )]

DROP CONFIGURATION 'name'

ALTER SETTINGS LANGUAGE ( key: value, ... )
ALTER SETTINGS LANGUAGE ADD [OR MODIFY] 'code' [( option: value, ... )]
ALTER SETTINGS LANGUAGE MODIFY 'code' ( option: value, ... )
ALTER SETTINGS LANGUAGE DROP 'code' 

ALTER SETTINGS WORKFLOWS ( key: value, ... )
ALTER SETTINGS WORKFLOWS ADD [OR MODIFY] GROUP 'name' [( Description: 'text' )]
ALTER SETTINGS WORKFLOWS MODIFY GROUP 'name' ( Description: 'text' )
ALTER SETTINGS WORKFLOWS DROP GROUP 'name'

ALTER SETTINGS WEBUI ( OptimizedClient: 'Yes' | 'No' | 'MigrationMode' )

Modifies project settings by category. Each category has its own syntax and available keys. Properties are written Key: value in a parenthesised list, as in every other MDL statement; the older key = value, ... without parentheses still runs and warns MDL-DEPR060, and mxcli fmt --upgrade rewrites it.

MODEL settings control application-level behavior such as the after-startup microflow, hashing algorithm, and Java version.

CONFIGURATION settings control named runtime configurations. Each project can have multiple configurations (e.g., default, staging, production). The keys are DatabaseType, DatabaseUrl, DatabaseName, DatabaseUserName, DatabasePassword, HttpPortNumber, ServerPortNumber, ApplicationRootUrl, ExtraJvmParameters (Studio Pro’s Server ▸ Extra JVM parameters) and MaxJavaHeapSize (Server ▸ Java heap ▸ Maximum size, in MB; 0 is Studio Pro’s “Default”). The configuration name must be enclosed in single quotes.

CONSTANT settings override the default value of a project constant within a specific runtime configuration. The constant is named as MDL names a constant everywhere, @Module.Name; the configuration name is enclosed in single quotes. The older quoted constant name (CONSTANT 'Module.Name') still parses and warns MDL-DEPR085; mxcli fmt --upgrade rewrites it.

LANGUAGE settings control localization: the default language code, and the list of enabled languages — the only ones a build emits translations for.

WORKFLOWS settings control the workflow engine, including the user entity used for workflow tasks and default task parallelism, and the workflow groups — the named buckets under App Settings ▸ Workflows ▸ Groups that a user task’s group targeting selects from. Groups need Mendix 11.2 or later.

WEBUI settings choose the client the app runs on: OptimizedClient: 'Yes' is the React client, 'No' the classic (Dojo) client, 'MigrationMode' Mendix’s mixed mode. The value is matched case-insensitively; anything else is rejected by mxcli check (MDL-SET03) and by the executor.

A section or key that does not exist is rejected by mxcli check (MDL-SET04) with the message the executor gives, so a script that cannot run does not pass the check.

Parameters

key: The setting name to modify. Available keys depend on the category.
value: The new value for the setting. String values must be enclosed in single quotes.
name (CONFIGURATION): The name of the configuration, enclosed in single quotes.
Module.Name (CONSTANT): The constant, written @Module.Name.
config (CONSTANT only): The name of the runtime configuration where the constant override applies, enclosed in single quotes.

Examples

Set the after-startup microflow

ALTER SETTINGS RUNTIME ( AfterStartupMicroflow: 'MyModule.ACT_Startup' );

The after-startup microflow must return Boolean. Mendix build fails with CE0142 if it has no return type. A common trip-up is wiring a void seed/demo-data microflow to after-startup — end it with return true so it returns a Boolean.

Configure database type

ALTER SETTINGS CONFIGURATION 'default' ( DatabaseType: 'POSTGRESQL' );

Set database URL for a configuration

ALTER SETTINGS CONFIGURATION 'production' ( DatabaseUrl: 'jdbc:postgresql://dbhost:5432/myapp' );

Pass extra JVM parameters

ALTER SETTINGS CONFIGURATION 'default' ( ExtraJvmParameters: '-Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8888' );

The value is stored as written and is what Studio Pro passes to the JVM when it runs the app. mxcli run --local and mxcli test --local pass it too, after -Xmx<n>m for a non-zero MaxJavaHeapSize, and print which options they pass (without -D values).

Override a constant in a configuration

ALTER SETTINGS CONSTANT @MyModule.ApiBaseUrl VALUE 'https://api.staging.example.com' IN CONFIGURATION 'staging';

An override’s value is either shared — stored in the model, and so in version control — or private, stored on the developer’s own workstation and kept out of the repository (the usual choice for development API tokens).

MDL preserves that choice but never changes it. ALTER SETTINGS CONSTANT ... VALUE applies to shared values only; on a private override it is refused, because setting a value would convert it to a shared one, publish a deliberately-local value into version control, and break the developer’s local binding. Change the constant to a shared value in Studio Pro first, or drop the override. DESCRIBE SETTINGS reports a private override as a comment rather than a re-executable statement, for the same reason.

Set the default language

The code must already be enabled; ALTER SETTINGS LANGUAGE DefaultLanguageCode is validated against the enabled list.

ALTER SETTINGS LANGUAGE ( DefaultLanguageCode: 'en_US' );

Enable, change and disable a language

mdl 1;
ALTER SETTINGS LANGUAGE ADD 'de_DE';
ALTER SETTINGS LANGUAGE ADD 'ar_SD' (CheckCompleteness: true, CustomDateFormat: 'yyyy-MM-dd');
ALTER SETTINGS LANGUAGE ADD OR MODIFY 'de_DE' (CheckCompleteness: true);
ALTER SETTINGS LANGUAGE MODIFY 'de_DE' (CustomDateFormat: 'dd.MM.yyyy');
ALTER SETTINGS LANGUAGE DROP 'de_DE';

Options: CheckCompleteness (report errors for texts with no translation in this language — the default language is always checked regardless), CustomDateFormat, CustomTimeFormat, CustomDateTimeFormat.

MODIFY touches only the options it names, so turning on the completeness check cannot clear a custom format set elsewhere. ADD OR MODIFY is the upsert and is what DESCRIBE SETTINGS emits.

Removing the default language is refused. Removing any other language does not delete its translations — they stay in the model, stop being built, and the run reports how many source strings are affected.

Configure workflow user entity

ALTER SETTINGS WORKFLOWS ( UserEntity: 'Administration.Account' );

Manage workflow groups

mdl 1;
ALTER SETTINGS WORKFLOWS ADD GROUP 'Approvers' (Description: 'Primary approval group');
ALTER SETTINGS WORKFLOWS ADD GROUP 'Reviewers';

-- the upsert, and what DESCRIBE SETTINGS emits
ALTER SETTINGS WORKFLOWS ADD OR MODIFY GROUP 'Approvers' (Description: 'Approves budget requests');

-- changes only the options it names
ALTER SETTINGS WORKFLOWS MODIFY GROUP 'Reviewers' (Description: 'Second-line review');

ALTER SETTINGS WORKFLOWS DROP GROUP 'Reviewers';

Description is the only option, because a workflow group stores a name and a description and nothing else. The name is the group’s identity, which is what MODIFY and REMOVE address; adding a second group whose name differs only in case is refused rather than creating one no statement could address unambiguously.

Changing a description keeps the group’s stored identity, so the System.WorkflowGroup row the runtime maintains for it is updated in place — group memberships and already-assigned user tasks survive the edit.

REMOVE has no dangling reference to check for: nothing in the model points at a settings group, since a user task targets groups through a microflow or an XPath returning System.WorkflowGroup objects. The coupling is at runtime, where the removed group’s row simply stops being maintained.

List the groups with LIST WORKFLOW GROUPS.

Set Java version

ALTER SETTINGS RUNTIME ( JavaVersion: '17' );

Switch to the classic web client

ALTER SETTINGS WEBUI ( OptimizedClient: 'No' );

Stored as UseOptimizedClient on the Web UI settings part (Mendix 9.10 and later). DESCRIBE SETTINGS emits the statement, and LIST SETTINGS shows the value as OptimizedClient.

Remove a constant override from a configuration

ALTER SETTINGS DROP CONSTANT @MyModule.ApiBaseUrl IN CONFIGURATION 'staging';

Create a new configuration

CREATE CONFIGURATION 'Staging' (
  DatabaseType: 'PostgreSql',
  DatabaseUrl: 'staging-db:5432',
  HttpPortNumber: 8080
);

DatabaseType must name a Mendix database type — Db2, Hsqldb, MySql, Oracle, PostgreSql, SapHana or SqlServer. The value is matched case-insensitively and stored in the spelling above; anything else is rejected by mxcli check and by the executor. A configuration created without properties gets Studio Pro’s defaults: Hsqldb, runtime port 8080, admin port 8090.

Drop a configuration

DROP CONFIGURATION 'Staging';

mxcli Documentation