CLI configuration

SQL client provides easy ways to set, alter, show, and save configurations. This documentation will guide you through the commands of SQL client configuration management.

Set configurations

The SQL client has 2 kinds of configurations: arguments and query settings.

At the launch of an SQL client, you can set values for configurations in one of two ways: load a configuration file that contains all the configuration settings, or enter configuration flags.

For all the configurations that are not specified either in the configuration file or in the configuration flags, the default values will be used.

Load configuration file

Currently, the SQL client only supports TOML configuration file type.

Example:

# Configurations for arguments:

account_id = “0”

alt_hosts = “”

background = “true”

block_size = “65536”

cluster = “default”

compress = “false”

# Configurations for query settings:

TEST_KNOB = 0

active_role = “*”

add_http_cors_header = false

additional_background_pool_size = 8

aggregation_memory_efficient_merge_threads = 0

The order of configurations does not matter. The comments, beginning with “#’, are optional. For numeric and boolean values, the double quotes are optional.

Option 1: Load from customised file path (local)

We can load a configuration file at the launch of the client:

# Example

./gateway-client -config_file bytehouse_conf.toml

When successfully loaded, you’ll see a similar message as shown:

Option 2: Load from customised file path (online)

You can load from a configuration file on Gitlab by using this command:

# Example
./bytehouse_mac -private_token <your private token to gitlab> -config_file "https://<domain name>/api/v4/projects/<project id>/repository/files/<configuration file path>/raw"

When the client successfully loads configurations from online configuration file, you’ll see a similar message as shown:

Option 3: Load from the default file path

By default, if no configuration file is loaded, the SQL client will attempt to load 'bytehouse_conf.toml'. So a shortcut is:

# Example
./gateway-client

When the client successfully loads configurations from 'bytehouse_conf.toml', you’ll see a similar message as shown:

To use this shortcut, please ensure that you have named the configuration file 'bytehouse_conf.toml' and placed it in the root directory.
If the client fails to read from 'bytehouse_conf.toml', it will use the values provided in the configuration flags and default values, with no error thrown:

Enter configuration flag

Alternatively, you can set configurations by typing configuration flags, for example:

# Example
./gateway-client -pprof 'true'

When successfully configured according to the flags, you’ll see a similar message as shown:

The client allows multiple flags, and note that '-config_file' is also a flag, so we can set configurations by loading a configuration file and configuration flags at the same time:

# Example
./gateway-client -pprof 'true' -config_file 'bytehouse_conf.toml'

The order of precedence is configuration flag > configuration file > default settings. So when an argument is set different values by both configuration flag and configuration file, the value from flag will be taken.
The usage of load configuration file and enter configuration flags also applies to unix pipeline command:

Alter configurations

After the client is launched, you are allowed to alter the configurations. However, the alteration will not affect the running client's setting, it will only reflect on "show configuration" and "save configuration".

Alter arguments

You can alter the configurations using the following command:

# Example
set password = 'password'

If altered successfully, it will look like this:

You can only alter an existing configuration.

Show configurations

Option 1: Show password

You can use the following command to see all the configurations specified by you:

# Example
show configuration

The client will return a list of configurations:

Option 2: Hide password

You can also choose to hide your password using this command:

# Example
show configuration hide password

Then the client will not show the password:

Save configurations

Option 1: Customised saving

You can save the client's configurations using this command:

# Example
save configuration into outfile 'save_config.toml' format toml

For now, the client only supports saving configuration as a TOML file, so please ensure the format is "toml" and the file path ends with ".toml"
When saved successfully, it will look like this:

This is what save_config.toml looks like:

If a file called "save_config.toml" already exists, then the configuration will be saved to "save_config(x).toml" where x is the minimal positive integer that avoids a clash:

There is no "hide password" option for save configuration, so please keep your saved configuration file safe.
However, if you want the client to override the file path, you can use this command:

# Example
save configuration into outfile 'save_config.toml' format toml override

Then it will look like this:

Option 2: Default saving

The default outfile path is the loaded configuration file path (if the configuration file is not specified at the launch of the client, then the default path is "bytehouse_conf.toml") and the default format is toml, you can omit them in the command if you wish to adopt the default:

# Example
save configuration

This command is equivalent to:

# Example
save configuration into outfile <default file path> format toml