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 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, a file namedConfig.toml
will be sought in the current working directory.
Configuration values for testing can be provided in a file namedConfig.toml
located in thetests
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 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 type | Ballerina example | Command-line argument |
---|---|---|
boolean | configurable boolean isAdmin = ?; | bal run -- -CisAdmin=true or bal run -- -CisAdmin=1 |
int, byte | configurable byte age = ?; configurable int port = ?; | bal run -- -Cage=25 -Cport=9090 |
float, decimal | configurable float height = ?; configurable decimal salary = ?; | bal run -- -Cheight=5.6 -Csalary=50500.65 |
string | configurable string name = ?; | bal run -- -Cname=John |
xml | configurable xml book = ?; | bal run -- -CxmlVar="<book>The Lost World</book>" |
enum | enum Country { LK = "Sri Lanka", US = "United States" } configurable Country country = ?; | bal run -- -Ccountry="Sri Lanka" |
union | configurable 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 type | Ballerina example | TOML type | TOML example |
---|---|---|---|
nil | configurable 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. | |
boolean | configurable boolean isAdmin = ?; | Boolean | isAdmin = true |
int, byte | configurable byte age = ?; configurable int port = ?; | Integer | age = 25 port = 9090 |
float, decimal | configurable float height = ?; configurable decimal salary = ?; | Float | height = 5.6 salary = 50500.65 |
string | configurable string name = ?; | String | name = "John" |
xml | configurable xml book = ?; | String | book = "<book>The Lost World</book>" |
boolean[] | configurable boolean[] switches = ?; | Array of booleans | switches = [false, false, true] |
int[] , byte[] | configurable int[] ports = ?; | Array of integers | ports = [9090, 9091] |
float[], decimal[] | configurable float[] rates = ?; | Array of floats | rates = [55.4, 76.3, 38.5] |
string[] | configurable string[] colors = ?; | Array of strings | colors = ["Red", "Green", "Blue"] |
tuple | configurable [string, int, string[], map | Array of respective types | student = ["Jane", 1101, ["Maths", "English"], {level = 4, class = "B"}, 98, 76, 88] |
map | configurable 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" |
record | type Person record { string name; int age; }; configurable Person person = ?; | TOML table | [person] name = "John" age = 45 |
record with record field | type 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 |
table | configurable 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 tables | userTeams = [[{name = "Tom", team = "Dev"}, {name = "Harry", team = "Dev"}], [{name = "Anna", team = "Finance"}]] |
enum | enum Country { LK = "Sri Lanka" , US = "United States" } configurable Country country = ?; | String | country = "Sri Lanka" |
union, anydata, json | configurable int|string code = ?; configurable anydata data = ?; configurable json payload = ?; | Relevant TOML type for the value | code = "10001A" data = 123 payload = {name = "Jane"} |