Provide values to configurable variables

You can provide values for configurable variables through multiple methods, as described below.

Note: If the configuration values are given in multiple ways, they will be overridden in the following order when retrieving them.

  1. Environment variables: Configure the values through separate environment variables for each configurable variable.

  2. Command-line arguments: Configure the values through command-line arguments executed when running the Ballerina program.

  3. Configuration using TOML content:

    • Define the values using the TOML syntax and configure them through configuration files.
    • Define the values using the TOML syntax and configure them through environment variables.

Provide via environment variables

Note This feature was introduced with Ballerina Swan Lake Update 9 (2201.9.0). If you are using an older version, consider providing TOML content via environment variables.

Use the syntax below to provide values for the variables through environment variables.

BAL_CONFIG_VAR_key=value

Note The configurable value provided through an environment variable is expected to be in the toString() representation of the intended value. Currently, the environment-variable-based configuration supports only the configurable variables of types int, byte, float, boolean, string, decimal, enum, and xml.

The following examples explain how to provide environment variables to configure variables of specific Ballerina types.

Ballerina typeBallerina exampleSetting environment variable for WindowsSetting environment variable for Linux/macOS
booleanconfigurable boolean isAdmin = ?; $ set BAL_CONFIG_VAR_ISADMIN=true
or
$ set BAL_CONFIG_VAR_ISADMIN=1		$ export BAL_CONFIG_VAR_ISADMIN=true
or
$ export BAL_CONFIG_VAR_ISADMIN=1
byteconfigurable byte age = ?; $ set BAL_CONFIG_VAR_AGE=25$ export BAL_CONFIG_VAR_AGE=25
intconfigurable int port = ?; $ set BAL_CONFIG_VAR_PORT=9090$ export BAL_CONFIG_VAR_PORT=9090
floatconfigurable float height = ?; $ set BAL_CONFIG_VAR_HEIGHT=5.11$ export BAL_CONFIG_VAR_HEIGHT=5.11
decimalconfigurable decimal salary = ?; $ set BAL_CONFIG_VAR_SALARY=50500.65$ export BAL_CONFIG_VAR_SALARY=50500.65
stringconfigurable string name = ?; $ set BAL_CONFIG_VAR_NAME=John$ export BAL_CONFIG_VAR_NAME=John
xmlconfigurable xml book = ?; $ set BAL_CONFIG_VAR_BOOK="<book>The Lost World</book>"$ export BAL_CONFIG_VAR_BOOK="<book>The Lost World</book>"
enumenum Country {
  LK = "Sri Lanka",
  US = "United States"
}
configurable Country country = ?; 		$ set BAL_CONFIG_VAR_COUNTRY="Sri Lanka"$ export BAL_CONFIG_VAR_COUNTRY="Sri Lanka"
unionconfigurable float|int|string measurement = ?; $ set BAL_CONFIG_VAR_MEASUREMENT="5 feet"$ export BAL_CONFIG_VAR_MEASUREMENT="5 feet"

Provide via command-line arguments

Use the syntax below to provide values for the variables through command-line arguments.

-Ckey=value

Note The configurable value provided through a command-line argument is expected to be in the toString() representation of the intended value. Currently, the command-line-based configuration supports only the configurable variables of types int, byte, float, boolean, string, decimal, enum, and xml.

The following examples explain how to provide command-line arguments to configure variables of specific Ballerina types.

Ballerina typeBallerina exampleCommand-line argument
booleanconfigurable boolean isAdmin = ?; $ bal run -- -CisAdmin=true
or
$ bal run -- -CisAdmin=1
int, byteconfigurable byte age = ?;
configurable int port = ?;		$ bal run -- -Cage=25 -Cport=9090
float, decimalconfigurable float height = ?;
configurable decimal salary = ?;		$ bal run -- -Cheight=5.6 -Csalary=50500.65
stringconfigurable string name = ?; $ bal run -- -Cname=John
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 feet"

Provide using TOML content

Provide via configuration files

You can provide configuration values via one or more configuration files in which the content is expected to comply with the TOML syntax.

  1. Specify the path of the configuration file via the BAL_CONFIG_FILES environment variable.

  2. Ballerina also supports specifying multiple configuration files using the BAL_CONFIG_FILES environment variable with the OS-specific separator. The file precedence order will be as specified in the environment variable.

  3. If an environment variable is not specified, a file named Config.toml will be sought in the current working directory, and this will be used by default when a Ballerina program is executed using the bal run command.

  4. 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.

Note: Once the environment variable is specified, the Config.toml will not be considered for the configuration values by default. Therefore, if you are required to use the Config.toml file along with others, you need to specify all of them via BAL_CONFIG_FILES in the order in which they should be executed.

For example, consider a scenario in which the configurable variables are defined in the following way,

Copy
configurable int port = 9090;
configurable float maxPayload = ?;
configurable string username = ?;
configurable boolean verbose = true

and the values are provided in two files, an info.tomlfile, which is a user-defined configuration file and Config.toml file as follows.

info.toml

Copy
maxPayload = 1.0
verbose = true

Config.toml

Copy
port = 9000
username = "admin-user"

Accordingly, execute the commands below to provide the values via the BAL_CONFIG_FILES environment variable based on your operating system.

For Windows:

Copy
$ set BAL_CONFIG_FILES=<path-to-info.toml>;<path-to-Config.toml>

For Linux/macOS:

Copy
$ export BAL_CONFIG_FILES=<path-to-info.toml>:<path-to-Config.toml>

Provide via environment variables

You can also provide configuration values through an environment variable named BAL_CONFIG_DATA in which the content is expected to comply with the TOML syntax.

For example, consider a scenario in which the configurable variables are defined in the following way,

Copy
configurable int port = 9000;
configurable float maxPayload = ?;
configurable string username = ?;
configurable boolean verbose = ?;

Accordingly, execute the commands below to configure the values via an environment variable based on your operating system.

For Windows:

Copy
$ set BAL_CONFIG_DATA=maxPayload=1.0\nusername="user1"\nverbose=true

For Linux/macOS:

Copy
$ export BAL_CONFIG_DATA='maxPayload=1.0\nusername="user1"\nverbose = true'

TOML syntax

Ballerina defines a specific TOML syntax based on the TOML(v0.4) format to be used when configuring the variables through the configuration files and environment variables.

Info: The way of providing values in the TOML content differs depending on the type of the configurable variable. Currently, the TOML-based configuration supports configurable variables of types int, float, boolean, string, xml, decimal, enum, the arrays of the respective types, map, record, table, and the union of the respective types.

The examples below explain the mapping of Ballerina types to TOML types.

Ballerina typeBallerina exampleTOML typeTOML example
nilconfigurable string? city = "London";
type Address record {
  string? city =  "Paris";
};
configurable Address address = {};		No TOML type is specified for the () value. A default value is expected when a configurable variable contains a nil type.N/A
booleanconfigurable boolean isAdmin = ?;BooleanisAdmin = true
int, byteconfigurable byte age = ?;
configurable int port = ?;		Integerage = 25
port = 9090
float, decimalconfigurable float height = ?;
configurable decimal salary = ?;		Floatheight = 5.6
salary = 50500.65
stringconfigurable string name = ?; Stringname = "John"
xmlconfigurable xml book = ?;Stringbook = "<book>The Lost World</book>"
boolean[]configurable boolean[] switches = ?;Array of booleansswitches = [false, false, true]
int[] , byte[]configurable int[] ports = ?;Array of integersports = [9090, 9091]
float[], decimal[]configurable float[] rates = ?;Array of floatsrates = [55.4, 76.3, 38.5]
string[]configurable string[] colors = ?;Array of stringscolors = ["Red", "Green", "Blue"]
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[] people = ?;		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"
table[]configurable table <map<string>>[] userTeams = ?; 2D Array of inline-TOML tablesuserTeams = [[{name = "Tom", team = "Dev"}, {name = "Harry", team = "Dev"}], [{name = "Anna", team = "Finance"}]]
enumenum Country {
  LK = "Sri Lanka" ,
  US = "United States"
}
configurable Country country = ?;		Stringcountry = "Sri Lanka"
union, anydata, jsonconfigurable int|string code = ?;
configurable anydata data = ?;
configurable json payload = ?;		Relevant TOML type for the valuecode = "10001A"
data = 123
payload = {name = "Jane"}