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 launching phase of a SQL Client, you can set values to configurations. There are two ways to set configurations: load a configuration file that contains all the configuration settings and 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 set.

Load Configuration File

For now, the SQL Client only supports TOML type of configuration file, here's an example of it:

# 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 started by "#' are optional.For numerics and booleans, the double quotes are optional.

Option 1: Load from Customised File Path (Local)

A configuration file can be loaded at the launching phase of the client:

# Example
./gateway-client -config_file bytehouse_conf.toml

When successfully loaded configurations from the file, it will look like this:

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, it will look like this:

Option 3: Load from the Default File Path

By default, the SQL Client will attempt to load 'bytehouse_conf.toml' if no configuration file is loaded, so a short cut is:

# Example
./gateway-client

When the client successfully loads configurations from 'bytehouse_conf.toml', it will look like this:

To use this short cut, please ensure that you have named the configuration file to be 'bytehouse_conf.toml' and placed it at the root directory.
If the client fails to read from 'bytehouse_conf.toml', the client 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, it will look like:

The client allows multiple flags, and notice 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 priority order 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 be reflected on "show configuration" and "save configuration".

Alter Arguments

You can alter the configurations by 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 you a list of configurations:

Option 2: Hide Password

You can also choose to hide your password by 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 by using this command:

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

For now, the client only supports to save configuration as a TOML type of 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 there is already a file called "save_config.toml", 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, then 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 did not specify the configuration file at the launching phase 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

Did this page help you?