ALTER SYSTEM

The ALTER SYSTEM statement allows you to modify configuration parameters at runtime without restarting your Ditto instance.

ALTER SYSTEM is available in SDK v5+.

The ALTER SYSTEM statement provides runtime configuration management, allowing you to change system parameters dynamically.

Syntax

DQL

ALTER SYSTEM SET parameter_name TO value
ALTER SYSTEM SET parameter_name = value
ALTER SYSTEM RESET parameter_name
ALTER SYSTEM RESET ALL

SET Parameter

Change a configuration parameter to a specific value:

DQL

-- Using TO syntax
ALTER SYSTEM SET DQL_STRICT_MODE TO false

-- Using = syntax (equivalent)
ALTER SYSTEM SET DQL_STRICT_MODE = false

Set to DEFAULT

Reset a parameter to its default value using the DEFAULT keyword:

DQL

ALTER SYSTEM SET parameter_name TO DEFAULT

RESET Parameter

Reset a configuration parameter to its default value:

DQL

-- Reset single parameter
ALTER SYSTEM RESET DQL_STRICT_MODE

-- Reset all parameters to defaults
ALTER SYSTEM RESET ALL

Parameter Values

Parameter values can be:

• Literals: Numbers, strings, booleans
  • Boolean: true, false
  • Integer: 100, 5000
  • String: 'value' or "value"
• DEFAULT keyword: Resets to the default value

Available DQL Configuration Parameters

DQL_STRICT_MODE

Type: Boolean Default: true

Controls whether strict mode is enabled for collection type definitions.

DQL

ALTER SYSTEM SET DQL_STRICT_MODE TO false

See Strict Mode for more information.

DQL_DEFAULT_DIRECTIVES

Type: Object (JSON) Default: {}

Sets default query directives that apply to all queries. Individual query directives can override these defaults.

DQL

-- Set default directives for development
ALTER SYSTEM SET DQL_DEFAULT_DIRECTIVES = {"#reprepare": true, "#max_serial_ranges": 2}

-- Reset to no default directives
ALTER SYSTEM SET DQL_DEFAULT_DIRECTIVES = {}

See Directives for more information.

DQL_CONCURRENT_REQUEST_LIMIT

Type: Integer Default: System-dependent

Limits the number of concurrent DQL requests that can execute simultaneously. When the limit is reached, additional requests are queued until capacity becomes available.

DQL

-- Limit to 10 concurrent requests
ALTER SYSTEM SET DQL_CONCURRENT_REQUEST_LIMIT TO 10

-- Reset to default (no limit)
ALTER SYSTEM RESET DQL_CONCURRENT_REQUEST_LIMIT

This parameter helps prevent resource exhaustion under heavy query load by controlling the maximum number of queries running at once.

DQL_SLOW_REQUEST_WARN_SECONDS

Type: Integer (seconds) Default: 60

Sets the threshold, in seconds, after which a still-running DQL request is considered slow. Once a request has been executing for this long, Ditto writes a warning log entry containing the request’s details — the same information reported by system:active_requests — and repeats the warning every DQL_SLOW_REQUEST_WARN_SECONDS seconds for as long as the request keeps running.

DQL

-- Warn about requests still running after 30 seconds
ALTER SYSTEM SET DQL_SLOW_REQUEST_WARN_SECONDS TO 30

Set to 0 to disable slow-request warnings entirely.

DQL_REQUEST_TIMEOUT_SECONDS

Type: Integer (seconds) Default: 0 (disabled)

Limits how long, in seconds, a DQL request is permitted to run before it is cancelled. When a request exceeds this limit, its execution pipeline is signalled to stop and the request fails with a timeout error; a warning log entry containing the request’s details is also written.

DQL

-- Cancel requests that run longer than 45 seconds
ALTER SYSTEM SET DQL_REQUEST_TIMEOUT_SECONDS TO 45

Set to 0 (the default) to disable the timeout, allowing requests to run for as long as they need.

Cancellation is cooperative rather than immediate: the currently executing operator is not interrupted mid-step, so execution may continue briefly past the configured limit before it actually stops.

Available Transport Configuration Parameters

tcp_server_bind_mdns_server_port

Type: Integer Default: Random port

Specifies the port that a Small Peer SDK instance uses for mDNS announcements and incoming LAN (TCP) connections on the local device. Setting an explicit port is useful when you need to traverse a VLAN or firewall by scanning for open ports, or when you need a deterministic port for network policy.

Leaving the parameter unset preserves the default behavior of binding to a random port.

DQL

ALTER SYSTEM SET tcp_server_bind_mdns_server_port TO 1234

If you run multiple Ditto applications on the same device — for example a debug or TestFlight build alongside a production build — each application must use a unique port. Otherwise only one application will be able to establish LAN connections at a time.

tcp_server_bind_mdns_server_port must be set before sync is started for the value to take effect.

Swift

let result = try await ditto.store.execute(
  query: "ALTER SYSTEM SET tcp_server_bind_mdns_server_port TO 1234"
)

See Local Area Network for the underlying mDNS, TCP, and firewall behavior this parameter affects.

Common Use Cases

Enable/Disable Strict Mode

DQL

-- Disable strict mode to allow flexible type definitions
ALTER SYSTEM SET DQL_STRICT_MODE TO false

-- Re-enable strict mode
ALTER SYSTEM SET DQL_STRICT_MODE TO true

Configure Default Query Directives

DQL

-- Set default directives during development
ALTER SYSTEM SET DQL_DEFAULT_DIRECTIVES = {"#reprepare": true}

-- Clear default directives for production
ALTER SYSTEM SET DQL_DEFAULT_DIRECTIVES = {}

Control Concurrent Query Execution

DQL

-- Limit concurrent queries to prevent overload
ALTER SYSTEM SET DQL_CONCURRENT_REQUEST_LIMIT TO 20

-- Remove limit
ALTER SYSTEM RESET DQL_CONCURRENT_REQUEST_LIMIT

Reset All Configuration

DQL

-- Reset all parameters to their default values
ALTER SYSTEM RESET ALL

Examples

Swift

// Set strict mode
await ditto.store.execute(
  query: "ALTER SYSTEM SET DQL_STRICT_MODE TO false"
)

// Reset parameter
await ditto.store.execute(
  query: "ALTER SYSTEM RESET DQL_STRICT_MODE"
)

// Reset all parameters
await ditto.store.execute(
  query: "ALTER SYSTEM RESET ALL"
)

Checking Current Values

To verify the current value of a parameter after changing it, use the SHOW statement:

DQL

-- Set parameter
ALTER SYSTEM SET DQL_STRICT_MODE TO false

-- Verify the change
SHOW DQL_STRICT_MODE

Configuration changes made with ALTER SYSTEM are runtime only and do not persist across restarts. To apply settings on every startup, set the parameters in your Ditto instance configuration before starting.

See Also

• SHOW - Display configuration parameter values
• Strict Mode - Understanding DQL_STRICT_MODE parameter
• Virtual Collections - Inspect currently executing and completed requests