= The load-balance Statement

.Syntax
[source,unlang]
----
load-balance [ <key> ] {
    [ statements ]
}
----

The `load-balance` section is similar to the `redundant` section
except that only one module in the subsection is ever called.

In general, the
xref:unlang/redundant-load-balance.adoc[redundant-load-balance] statement is
more useful than this one.

<key>:: An attribute reference or expansion which will be hashed in
order to select the statement to execute.
+
The hash will be used to pick a particular statement within the
`load-balance` section.  This "keyed" load-balance can be used to
deterministically shard requests across multiple modules.
+
When the `<key>` field is omitted, the module is chosen randomly, in a
"load balanced" manner.

[ statements ]:: One or more `unlang` commands.  Only one of the
statements is executed.

.Examples

[source,unlang]
----
load-balance &User-Name {
    sql1
    sql2
}
----

== load-balance Sections as Modules

It can be useful to use the same `load-balance` section in multiple
places.  Instead of copying the same text multiple times, a
`load-balance` section can be defined as a module in the `mods-enabled/`
directory.

For example, the following text can be placed into the file
`mods-enabled/sql_all`.  Once it is there, it can be used as a module
named `sql_all`, and used anywhere a module is allowed to use.

.Example of Load-Balance SQL module
[source,unlang]
----
load-balance sql_all {
    sql1
    sql2
    sql3
}
----

In previous versions of the server, this definition would be placed
into the `instantiate` section of `radiusd.conf.  This configuration
is no longer used, and the `sql_all` definition can just be placed as
a module definition into the `mods-enabled/` directory.

== Load-Balance Expansions

When the `sql_all` module is defined as above, it can also be used as
in a xref:xlat/index.adoc[dynamic expansion]:

.Example of Load-Balance SQL module
[source,unlang]
----
&Reply-Message := %sql_all("SELECT message FROM table WHERE name='%{User-Name}'")
}
----

The expansion works exactly like a `load-balance` block.  One of the
modules is chosen to run the expansion, in load-balance fashion.

// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
