Provide values to configurable variables

The values for configurable variables can be provided through configuration files, command line arguments, and environment variables. The configuration values will be overridden in the following precedence order if the values are given through multiple ways when retrieving configurable values:

  • Command line arguments: The values can be configured through the command line arguments when executing the Ballerina program. The configurable value provided through a command line argument is expected to be the toString() representation of the intended value.

  • Configuration files: The values can be configured through the configuration files in the <a href="https://toml.io/en/v0.4.0" target="_blank">TOML(v0.4) format. The file location can be specified through an environment variable with the name BAL_CONFIG_FILES. Ballerina supports specifying multiple configuration files using this environment variable with the OS-specific separator. The file precedence order will be as specified in the environment variable. If an environment variable is not specified, the file will be located in the current working directory with the file name Config.toml by default.
    Configuration values for testing can be provided in a file named Config.toml located in the tests directory. For more details, see Define test-specific configurations.

  • Environment variables: Users can provide the configuration values through an environment variable with the name BAL_CONFIG_DATA in which the content is expected to be in the <a href="https://toml.io/en/v0.4.0" target="_blank">TOML(v0.4) format.

Note: Providing multiple configuration values through separate environment variables is not supported.

Provide via command line arguments

The following syntax can be used to provide values for the variables through the command line parameters:

-Ckey=value

Currently, the command line based configuration is only supported for configurable variables of types int, byte, float, boolean, string, decimal, enum and xml.

The following examples explain the way of providing command line arguments to configure variables of specific Ballerina types.

Ballerina typeBallerina exampleCommand line argument
int, byteconfigurable byte age = ?;
configurable int port = ?;
bal run -- -Cage=25 -Cport=9090
stringconfigurable string name = ?; bal run -- -Cname=John
float, decimalconfigurable float height = ?;
configurable decimal salary = ?;
bal run -- -Cheight=5.6 -Csalary=50500.65
booleanconfigurable boolean isAdmin = ?; bal run -- -CisAdmin=true
or
bal run -- -CisAdmin=1
xmlconfigurable xml book = ?; bal run -- -CxmlVar="<book>The Lost World</book>"
enumenum Country {
LK = "Sri Lanka",
US = "United States"
}
configurable Country country = ?;
bal run -- -Ccountry="Sri Lanka"
unionconfigurable float|int|string measurement = ?; bal run -- -Cmeasurement=5.0

Provide via TOML syntax

Ballerina defines a specific TOML syntax to be used when configuring the variables through the configuration files and environment variables. Depending on the type of the configurable variable, the way of providing values in the TOML content differs. Currently, TOML-based configuration is supported for configurable variables of int, float, boolean, string, xml, decimal, enum, the arrays of the respective types, map, record, table and the union of the respective types.

The mapping of Ballerina types to TOML types can be explained through the following examples:

Ballerina typeBallerina exampleTOML typeTOML example
int, byteconfigurable byte age = ?;
configurable int port = ?;
Integerage = 25
port = 9090
stringconfigurable string name = ?; Stringname = "John"
float, decimalconfigurable float height = ?;
configurable decimal salary = ?;
Floatheight = 5.6
salary = 50500.65
booleanconfigurable boolean isAdmin = ?;BooleanisAdmin = true
xmlconfigurable xml book = ?;Stringbook = "<book>The Lost World</book>"
enumenum Country {
LK = "Sri Lanka" ,
US = "United States"
}
configurable Country country = ?;
Stringcountry = "Sri Lanka"
unionconfigurable int|string code = ?;Relevant TOML type for the valuecode = "10001A"
int[] , byte[]configurable int[] ports = ?;Array of integersports = [9090, 9091]
string[]configurable string[] colors = ?;Array of stringscolors = ["Red", "Green", "Blue"]
float[], decimal[]configurable float[] rates = ?;Array of floatsrates = [55.4, 76.3, 38.5]
boolean[]configurable boolean[] switches = ?;Array of booleansswitches = [false, false, true]
tupleconfigurable [string, int, string[], map, int... ] student = ?;Array of respective typesstudent = ["Jane", 1101, ["Maths", "English"], {level = 4, class = "B"}, 98, 76, 88]
mapconfigurable map <string> person = ?; TOML table[person]
name = "Anna"
city = "London"
map[]configurable map <string>[] people = ?; Array of TOML tables[[people]]
name = "John"
city = "Paris"
[[people]]
name = "Jack"
city = "Colombo"
recordtype Person record {
string name;
int age;
};
configurable Person person = ?;
TOML table[person]
name = "John"
age = 45
record with record fieldtype Food record {
string name;
int cal;
};
type Diet record {
Food food;
int age;
};
configurable Diet input = ?;
TOML table - nested[input]
age = 20
food.name = "carrot"
food.cal = 41
record[]type Person record {
string name;
int age;
};
configurable Person[] peope = ?;
Array of TOML tables[[people]]
name = "John"
age = 45
[[people]]
name = "Jack"
age = 32
tableconfigurable table <map<string>> users = ?; Array of TOML tables[[users]]
name = "Tom"
occupation = "Software Engineer"
[[users]]
name = "Harry"
occupation = "Doctor"