Using ALTER SYSTEM
ALTER SYSTEM is an advanced system performance tuning feature for configuring and retrieving Ditto system settings.
Only use when recommended by the Ditto Customer Experience team. For information on specific configs supported via ALTER SYSTEM reach out to the Ditto team member.
System settings consist of values the Ditto library uses to configure specific behaviors, such as timeouts, resource limits, and so on.
This article provides a high-level overview of the ALTER SYSTEM Ditto Query Language (DQL) statement, as well as instructions on how to use it, once offered, to set, reset, and query peer-to-peer system settings.
The following table provides an overview of the various tasks you can perform with the ALTER SYSTEM statement:
Task | Query |
|---|---|
Retrieve current system settings for all configurations. (Retrieving Values) | SHOW ALL |
Retrieve current system settings for a specific configuration. (Retrieving Values) | SHOW |
Change a specific system setting. (Modifying Values) | ALTER SYSTEM SET |
Reset system settings to default configurations. (Resetting Values to Default) | ALTER SYSTEM RESET |
Fetch current setting values for either the entire mesh network or a specific setting:
- To return system-wide configurations, use a SHOW ALL statement:
- To return only the value for a specific setting, pass the setting you want to retrieve a value for in a SHOW statement. For example:
To invoke your statement, call the Execute API method on the ditto.store namespace:
For example, in Swift:
To modify a system setting, use ALTER SYSTEM SET:
Similar to PostgresSQL, DQL supports both the = and TO syntax for setting system configurations.
Regardless of the syntax you use in your ALTER SYSTEM SET query, the documents Ditto returns contain the current value of the setting, identified by the setting name.
For example:
Similar to the execution pattern recommended when configuring transports in your app, invoke your statement modifying system configurations immediately after initializing the ditto object. (See Customizing Transports Configurations)
Ditto stores configuration settings modified by ALTER SYSTEM in memory rather than persisting them to disk.
So, while you can execute your statement to modify a setting at any point during your app’s lifecycle, changing certain settings within your app may not result in immediate effects.
To invoke the SET statement, add a call to the Execute API method on the ditto.store namespace. For example, in Swift:
To return peer-to-peer system configuration settings to default values, do either of the following:
- To reset all configuration settings: For example:
- To reset a specific configuration setting:
Once executed, Ditto returns a document containing current values, identified by their setting name.
Ditto throws an error when an ALTER SYSTEM query operation fails to execute due to various issues, including:
- Syntax mistakes, such as a typo, causing parsing of the DQL statement to fail.
- Using an unrecognized setting name in the query (often due to a typo).
- Attempting to set a value outside the acceptable bounds for a setting in an ALTER SYSTEM SET query.
- An internal error occurred while processing the query.