ALTER SYSTEM is an advanced system performance tuning feature for configuring and retrieving system settings for your peer-to-peer mesh network.

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.

​
Tasks Overview

The following table provides an overview of the various tasks you can perform with the ALTER SYSTEM statement:

TaskQuery
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

​
Retrieving Values

Fetch current setting values for either the entire mesh network or a specific setting:

  • To return system-wide configurations, use a SHOW ALL statement:
SHOW ALL;
  • 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:
SHOW REPLICATION_GC_STARTUP_DELAY_SECONDS;

​
Executing SHOW and SHOW ALL

To invoke your statement, call the Execute API method on the ditto.store namespace:

For example, in Swift:

Swift
let result = try await ditto.store.execute(query: "SHOW ALL")
result.items[0].value["example_parameter"] as? Int

​
Modifying Values

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.

ALTER SYSTEM SET <setting> = <value>

For example:

ALTER SYSTEM SET REPLICATION_GC_STARTUP_DELAY_SECONDS = 10;

​
Executing SET

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:

Swift
var result = try await ditto.store.execute(query: "ALTER SYSTEM SET example_parameter = 321")
result.items[0].value["example_parameter"] as? Int // 321

​
Resetting Values to Default

To return peer-to-peer system configuration settings to default values, do either of the following:

  • To reset all configuration settings:

    For example:

ALTER SYSTEM RESET ALL;
  • To reset a specific configuration setting:
ALTER SYSTEM RESET <setting>

Once executed, Ditto returns a document containing current values, identified by their setting name.

​
Troubleshooting

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.

ALTER SYSTEM is an advanced system performance tuning feature for configuring and retrieving system settings for your peer-to-peer mesh network.

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.

​
Tasks Overview

The following table provides an overview of the various tasks you can perform with the ALTER SYSTEM statement:

TaskQuery
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

​
Retrieving Values

Fetch current setting values for either the entire mesh network or a specific setting:

  • To return system-wide configurations, use a SHOW ALL statement:
SHOW ALL;
  • 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:
SHOW REPLICATION_GC_STARTUP_DELAY_SECONDS;

​
Executing SHOW and SHOW ALL

To invoke your statement, call the Execute API method on the ditto.store namespace:

For example, in Swift:

Swift
let result = try await ditto.store.execute(query: "SHOW ALL")
result.items[0].value["example_parameter"] as? Int

​
Modifying Values

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.

ALTER SYSTEM SET <setting> = <value>

For example:

ALTER SYSTEM SET REPLICATION_GC_STARTUP_DELAY_SECONDS = 10;

​
Executing SET

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:

Swift
var result = try await ditto.store.execute(query: "ALTER SYSTEM SET example_parameter = 321")
result.items[0].value["example_parameter"] as? Int // 321

​
Resetting Values to Default

To return peer-to-peer system configuration settings to default values, do either of the following:

  • To reset all configuration settings:

    For example:

ALTER SYSTEM RESET ALL;
  • To reset a specific configuration setting:
ALTER SYSTEM RESET <setting>

Once executed, Ditto returns a document containing current values, identified by their setting name.

​
Troubleshooting

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.