---
title: Using ALTER SYSTEM
slug: v4-7/using-alter-system
docTags: 
createdAt: 2024-06-24T15:43:58.795Z
---

`ALTER SYSTEM` is an advanced system performance tuning feature for configuring and retrieving *Ditto* *system settings*.

:::hint{type="danger"}
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.

# Tasks Overview

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](./#retrieving-values))             | `SHOW ALL`           |
| Retrieve current system settings for a specific configuration. ([Retrieving Values](./#retrieving-values))       | `SHOW`               |
| Change a specific system setting. ([Modifying Values](./#modifying-values))                                      | `ALTER SYSTEM SET`   |
| Reset system settings to default configurations. ([Resetting Values to Default](./#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:

:::CodeblockTabs
DQL

```mysql
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:

:::CodeblockTabs
DQL

```mysql
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`:

:::hint{type="info"}
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. 
:::

:::CodeblockTabs
DQL

```mysql
ALTER SYSTEM SET <setting> = <value>
```
:::

For example:

:::CodeblockTabs
DQL

```mysql
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](docId\:MCNaenaZXAokRd053tt-w))

:::hint{type="warning"}
Ditto stores configuration settings modified by `ALTER SYSTEM` in memory rather than persisting them to disk.&#x20;

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:

:::CodeblockTabs
DQL

```mysql
ALTER SYSTEM RESET ALL;
```
:::

- To reset a specific configuration setting:

:::CodeblockTabs
DQL

```mysql
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.&#x20;
- An internal error occurred while processing the query.