Project Settings

Project Settings

When to Use This Skill

Use this skill when the user wants to:

• Configure database connections (PostgreSQL, SQLServer, etc.)
• Set up Kafka endpoints or other constant overrides
• Change the after-startup or before-shutdown microflows
• Modify hash algorithms, Java versions, or rounding modes
• View or modify language settings
• Configure workflow settings (user entity, parallelism, groups)

Commands

View Settings

-- Overview table of all settings parts
list settings;

-- Full MDL output (round-trippable ALTER SETTINGS statements)
describe settings;

Modify Model Settings

mdl 1;
alter settings runtime ( AfterStartupMicroflow: 'Module.MF_Startup' );  -- must return Boolean (CE0142)
alter settings runtime ( BeforeShutdownMicroflow: 'Module.MF_Shutdown' );
alter settings runtime ( HealthCheckMicroflow: 'Module.MF_HealthCheck' );
alter settings runtime ( HashAlgorithm: 'BCrypt' );
alter settings runtime ( BcryptCost: 12 );
alter settings runtime ( JavaVersion: 'Java21' );  -- or '21'; see note below
alter settings runtime ( RoundingMode: 'HalfUp' );
alter settings runtime ( AllowUserMultipleSessions: true );
alter settings runtime ( ScheduledEventTimeZoneCode: 'Etc/UTC' );
alter settings runtime ( DefaultTimeZoneCode: 'Europe/Amsterdam' );
alter settings runtime ( FirstDayOfWeek: 'Monday' );       -- Default, Monday..Sunday
alter settings runtime ( DecimalScale: 8 );
alter settings runtime ( EnableDataStorageOptimisticLocking: true );
alter settings runtime ( UseDatabaseForeignKeyConstraints: true );
alter settings runtime ( UseOQLVersion2: true );
alter settings runtime ( SslCertificateAlgorithm: 'PKIX' );   -- PKIX or SunX509

Not every project stores every setting. Mendix adds model settings over time — a blank 9.24 project stores 12 of them, a blank 11.13 project stores 17. mxcli refuses an alter naming one the project does not store rather than introducing it, because Studio Pro refuses to open a model carrying a property its type does not define (and mx check does not catch that). describe settings emits only what the project actually stores, so its output always replays.

UseSystemContextForBackgroundTasks is read but not writable. Mendix withdrew it: mx check on 11.13 rejects a project holding true with CE9436 "The project setting 'System context tasks' is not supported anymore." mxcli preserves whatever the project stores and offers no way to change it.

Optimistic locking is App Settings → Runtime → Optimistic locking in Studio Pro. With it on, the runtime tracks an MxObjectVersion on every persistable entity and a commit whose version no longer matches the database throws ConcurrentModificationRuntimeException.

Reach for it when a microflow reads a value, decides on it, and writes it back — the classic "check the balance, then debit it" shape. A microflow is one transaction, so each run is atomic, but that does not make two concurrent runs serialisable: both can pass the check and the second overwrites the first. With optimistic locking on, the second commit fails and its whole microflow rolls back instead of silently overdrawing the account.

It detects, it does not retry. Mendix's guidance is that the handler must catch the exception, reload the object, re-apply and re-commit — "trying to commit the same object without reloading always results in an optimistic locking error." Without that the user sees a failure rather than a transfer that works. The money is safe either way, which is the half that matters.

JavaVersion spelling. Mendix renamed this property between versions: up to 11.6 it stores JavaVersion = 'Java21', from 11.12 it stores JavaMajorVersion = '21'. Write either spelling — mxcli reads which one the project uses and stores the value in that dialect. Getting this wrong is not a cosmetic difference: 11.12 parses the bare major and rejects the project outright with ArgumentOutOfRangeException: majorVersion is an unsupported value: Java21. describe settings always emits the project's own spelling, so its output replays cleanly.

describe settings never prints DatabasePassword. Describe output is what gets committed and reviewed, so the password is omitted and a comment says it is set. Replaying the output leaves the stored password unchanged (create or modify configuration only touches the keys it names); on a project that lacks the configuration, add DatabasePassword = '…' yourself.

Modify Configuration Settings

mdl 1;
-- Full database configuration
alter settings configuration 'Default' (
  DatabaseType: 'PostgreSql',
  DatabaseUrl: 'localhost:5432',
  DatabaseName: 'mydb',
  DatabaseUserName: 'mendix',
  DatabasePassword: 'mendix',
  HttpPortNumber: 8080,
  ServerPortNumber: 8090
);

-- Update a single field
alter settings configuration 'Default' (
  DatabaseUrl: 'newhost:5432'
);

HttpPortNumber, ServerPortNumber, BcryptCost, DefaultTaskParallelism and WorkflowEngineParallelism and DecimalScale are Integer-typed; AllowUserMultipleSessions, EnableDataStorageOptimisticLocking, UseDatabaseForeignKeyConstraints and UseOQLVersion2 are Boolean; FirstDayOfWeek and SslCertificateAlgorithm are enumerations, matched case-insensitively and stored in Mendix's own spelling (MDL-SET03 rejects a non-member rather than writing it through — an unresolvable enum value is what makes Studio Pro throw "Sequence contains no matching element"). An unparseable value is rejected by mxcli check (MDL-SET01 / MDL-SET02) and by the write itself — it is no longer silently ignored. Quoted numbers are fine: HttpPortNumber = '8080' and HttpPortNumber = 8080 are equivalent.

Constant Overrides

mdl 1;
-- View constant values across all configurations
list constant values;
list constant values in MyModule;    -- Filter by module

-- Override a constant value in a configuration
alter settings constant @BusinessEvents.ServerUrl value 'kafka:9092'
  in configuration 'Default';

-- Without IN CONFIGURATION (uses first configuration)
alter settings constant @MyModule.ApiKey value 'abc123';

-- Remove a constant override (reset to default)
alter settings drop constant @MyModule.ApiKey in configuration 'Default';

Shared vs private values

A constant override's value is either shared — stored in the model and therefore in version control, where every developer gets it — or private, stored on the developer's own workstation and deliberately kept out of the repository. Development API tokens are the usual reason to make one private.

MDL preserves that choice but never changes it. The two statements above operate on shared values only:

• list constant values reports a private override as (private) rather than a blank cell — the value is not in the project, so mxcli cannot show it.
• describe settings reports a private override as a comment, not as a re-executable alter settings constant line — replaying that line would publish into the shared model a value the developer chose to keep local.
• alter settings constant ... value ... on a private override is refused, with a pointer to change it in Studio Pro first. Setting a value would convert it to a shared one and break the developer's local binding.
• alter settings drop constant ... is allowed: it removes the whole override, private marker included, which is what was asked for.

Create / Drop Configurations

mdl 1;
-- Create a new server configuration
create configuration 'Staging';

-- Create with properties
create configuration 'Production' (
  DatabaseType: 'PostgreSql',
  DatabaseUrl: 'prod-db:5432',
  HttpPortNumber: 8080
);

-- Drop a configuration
drop configuration 'Staging';

DatabaseType must name a Mendix database type — Db2, Hsqldb, MySql, Oracle, PostgreSql, SapHana or SqlServer — matched case-insensitively and stored in that spelling. Any other value is rejected; a configuration stored with one Mendix does not recognise cannot be opened in Studio Pro.