project-settings git:20260821.ff81a24A

Immutable. This exact content is served forever at /api/v1/blob/0d82ba75bc40acf2.

---
name: project-settings
description: "Read and change project settings in MDL — database configuration, constant overrides, after-startup and before-shutdown microflows, and the rest of Studio Pro's Settings dialog. Use when configuring a deployment or wiring a startup microflow."
---

# 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)

## Commands

### View Settings

```sql
-- Overview table of all settings parts
show settings;

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

### Modify Model Settings

```sql
alter settings model AfterStartupMicroflow = 'Module.MF_Startup';  -- must return Boolean (CE0142)
alter settings model BeforeShutdownMicroflow = 'Module.MF_Shutdown';
alter settings model HealthCheckMicroflow = 'Module.MF_HealthCheck';
alter settings model HashAlgorithm = 'BCrypt';
alter settings model BcryptCost = 12;
alter settings model JavaVersion = 'Java21';  -- or '21'; see note below
alter settings model RoundingMode = 'HalfUp';
alter settings model AllowUserMultipleSessions = true;
alter settings model ScheduledEventTimeZoneCode = 'Etc/UTC';
alter settings model DefaultTimeZoneCode = 'Europe/Amsterdam';
alter settings model FirstDayOfWeek = 'Monday';       -- Default, Monday..Sunday
alter settings model DecimalScale = 8;
alter settings model EnableDataStorageOptimisticLocking = true;
alter settings model UseDatabaseForeignKeyConstraints = true;
alter settings model UseOQLVersion2 = true;
alter settings model 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.

### Modify Configuration Settings

```sql
-- 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

```sql
-- View constant values across all configurations
show constant values;
show 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:

- `show 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

```sql
-- 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.

### Language and Workflow Settings

```sql
alter settings LANGUAGE DefaultLanguageCode = 'en_US';

alter settings workflows
  UserEntity = 'System.User',
  DefaultTaskParallelism = 3;
```

## Common Patterns

### PostgreSQL Configuration
```sql
alter settings configuration 'Default'
  DatabaseType = 'PostgreSql',
  DatabaseUrl = 'localhost:5432',
  DatabaseName = 'myapp',
  DatabaseUserName = 'mendix',
  DatabasePassword = 'mendix',
  HttpPortNumber = 8080;
```

### SQL Server Configuration
```sql
alter settings configuration 'Default'
  DatabaseType = 'SqlServer',
  DatabaseUrl = 'localhost:1433',
  DatabaseName = 'myapp',
  DatabaseUserName = 'sa',
  DatabasePassword = 'MyPassword',
  HttpPortNumber = 8080;
```

## Checklist

- [ ] Always run `show settings` or `describe settings` first to see current values
- [ ] Verify changes after modification with `show settings`
- [ ] There is always exactly one ProjectSettings document; it cannot be created or deleted
- [ ] Model setting key names are case-sensitive (e.g., `JavaVersion`, not `javaversion`)
- [ ] Configuration names are case-insensitive (e.g., `'default'` matches `'default'`)
- [ ] Integer / Boolean settings must parse — `mxcli check` reports MDL-SET01 / MDL-SET02 before the write