= The transaction Statement

.Syntax
[source,unlang]
----
transaction {
    [ statements ]
}
----

The `transaction` statement collects a series of statements into a
single transaction.  If the block returns an error such as `fail`,
`reject`, `invalid`, or `disallow`, any attribute changes which have
been made will be reverted.

[ statements ]:: The `unlang` commands which will be executed.

== Caveats

The `transaction` sets its own action defaults for return codes
`fail`, `invalid`, and `disallow`.  The priority for those return
codes is set to `1`, instead of the default `return`.  This behavior
allows for the caller to edit attributes, but continue processing if
something goes wrong.

The main limitation of `transaction` is that it can only revert
attribute editing which is done via the xref:unlang/edit.adoc[edit]
statements.  If a module performs attribute editing (e.g. `sql`,
`files`, etc.), then those edits are not reverted.

Similarly, a `transaction` cannot undo operations on external
databases.  For example, any data which was inserted into `sql` during
a `transaction` statement will remain in `sql`.

.Example

In this example, if the SQL `select` statement fails, then the
`&reply.Framed-IP-Address` attribute is _not_ updated, and the
`transaction` section returns `fail`.

[source,unlang]
----
transaction {
    &reply.Filter-Id := %sql("SELECT ...")
    &reply.Framed-IP-Address := 192.0.2.1
}
----

The last entry in a `transaction` section can also be an
xref:unlang/actions.adoc[actions] subsection.  If set, those actions
over-ride any previously set defaults.

== Grouping Edits

The `transaction` keyword can be used to group multiple
xref:unlang/edit.adoc[edit] instructions.  When edit instructions are
grouped, then the edits are done in an atomic transaction.  That is,
either all of the edits succeed, or none of them do.

For now, the only purpose of `transaction` is to group edits.  None of
the modules support transactions.  If a module is used inside of a
transaction, the server will return an error, and will not start.

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