khepri_tx (khepri v0.6.0)
Khepri API for transactional queries and updates.
Transactions are anonymous functions which take no arguments, much like what Mnesia supports. However, unlike with Mnesia, transaction functions in Khepri are restricted:
- Calls to BIFs and other functions is limited to a set of whitelisted APIs. See
khepri_tx_adv:is_remote_call_valid/3
for the complete list. - Sending or receiving messages is denied.
The reason is that the transaction function must always have the exact same outcome given its inputs. Indeed, the transaction function is executed on every Ra cluster members participating in the consensus. The function must therefore modify the Khepri state (the database) identically on all Ra members. This is also true for Ra members joining the cluster later or catching up after a network partition.
To achieve that:- The code of the transaction function is extracted from the its initial Erlang module. This way, the transaction function does not depend on the initial module availability and is not affected by a module reload. See
khepri_fun
) - The code is verified to make sure it does not perform any denied operations.
- The extracted transaction function is stored as a Khepri state machine command in the Ra journal to be replicated on all Ra members.
khepri_tx_adv
module.
Link to this section Summary
Types
Functions
Aborts the transaction.
Deletes the payload of all tree nodes matching the given path pattern.
Deletes the payload of all tree nodes matching the given path pattern.
Deletes the payload of the tree node pointed to by the given path pattern.
Deletes the payload of the tree node pointed to by the given path pattern.
Updates an existing tree node with the given payload only if its data matches the given pattern.
Updates an existing tree node with the given payload only if its data matches the given pattern.
Counts all tree nodes matching the given path pattern.
Counts all tree nodes matching the given path pattern.
Creates a tree node with the given payload.
Creates a tree node with the given payload.
Deletes the tree node pointed to by the given path pattern.
Deletes the tree node pointed to by the given path pattern.
Deletes all tree nodes matching the given path pattern.
Deletes all tree nodes matching the given path pattern.
Indicates if the tree node pointed to by the given path exists or not.
Indicates if the tree node pointed to by the given path exists or not.
Returns a map for which predicate Pred
holds true in tree nodes matching the given path pattern.
Returns a map for which predicate Pred
holds true in tree nodes matching the given path pattern.
Calls Fun
on successive tree nodes matching the given path pattern, starting with Acc
.
Calls Fun
on successive tree nodes matching the given path pattern, starting with Acc
.
Calls Fun
for each tree node matching the given path pattern.
Calls Fun
for each tree node matching the given path pattern.
Returns the payload of the tree node pointed to by the given path pattern.
Returns the payload of the tree node pointed to by the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
Indicates if the tree node pointed to by the given path has data or not.
Indicates if the tree node pointed to by the given path has data or not.
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
Produces a new map by calling Fun
for each tree node matching the given path pattern.
Produces a new map by calling Fun
for each tree node matching the given path pattern.
Runs the stored procedure pointed to by the given path and returns the result.
Runs the stored procedure pointed to by the given path and returns the result.
Sets the payload of all the tree nodes matching the given path pattern.
Sets the payload of all the tree nodes matching the given path pattern.
Updates an existing tree node with the given payload.
Updates an existing tree node with the given payload.
Link to this section Types
tx_abort/0
-type tx_abort() :: khepri:error(any()).
tx_fun/0
-type tx_fun() :: fun().
tx_fun_result/0
-type tx_fun_result() :: any() | no_return().
Link to this section Functions
abort(Reason)
-spec abort(Reason) -> no_return() when Reason :: any().
Aborts the transaction.
Any changes so far are not committed to the store.
khepri:transaction/1
and friends will return tx_abort()
.
clear_many_payloads(PathPattern)
-spec clear_many_payloads(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the payload of all tree nodes matching the given path pattern.
This is the same askhepri:clear_many_payloads/2
but inside the context of a transaction function.See also: khepri:clear_many_payloads/2.
clear_many_payloads(PathPattern, Options)
-spec clear_many_payloads(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Deletes the payload of all tree nodes matching the given path pattern.
This is the same askhepri:clear_many_payloads/3
but inside the context of a transaction function.See also: khepri:clear_many_payloads/3.
clear_payload(PathPattern)
-spec clear_payload(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the payload of the tree node pointed to by the given path pattern.
This is the same askhepri:clear_payload/2
but inside the context of a transaction function.See also: khepri:clear_payload/2.
clear_payload(PathPattern, Options)
-spec clear_payload(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Deletes the payload of the tree node pointed to by the given path pattern.
This is the same askhepri:clear_payload/3
but inside the context of a transaction function.See also: khepri:clear_payload/3.
compare_and_swap(PathPattern, DataPattern, Data)
-spec compare_and_swap(PathPattern, DataPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Updates an existing tree node with the given payload only if its data matches the given pattern.
This is the same askhepri:compare_and_swap/4
but inside the context of a transaction function.See also: khepri:compare_and_swap/4.
compare_and_swap(PathPattern, DataPattern, Data, Options)
-spec compare_and_swap(PathPattern, DataPattern, Data, Options) -> Ret when PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Updates an existing tree node with the given payload only if its data matches the given pattern.
This is the same askhepri:compare_and_swap/5
but inside the context of a transaction function.See also: khepri:compare_and_swap/5.
count(PathPattern)
-spec count(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:ok(Count) | khepri:error(), Count :: non_neg_integer().
Counts all tree nodes matching the given path pattern.
This is the same askhepri:count/2
but inside the context of a transaction function.See also: khepri:count/2.
count(PathPattern, Options)
-spec count(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), Ret :: khepri:ok(Count) | khepri:error(), Count :: non_neg_integer().
Counts all tree nodes matching the given path pattern.
This is the same askhepri:count/3
but inside the context of a transaction function.See also: khepri:count/3.
create(PathPattern, Data)
-spec create(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Creates a tree node with the given payload.
This is the same askhepri:create/3
but inside the context of a transaction function.See also: khepri:create/3.
create(PathPattern, Data, Options)
-spec create(PathPattern, Data, Options) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Creates a tree node with the given payload.
This is the same askhepri:create/4
but inside the context of a transaction function.See also: khepri:create/4.
delete(PathPattern)
-spec delete(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the tree node pointed to by the given path pattern.
This is the same askhepri:delete/2
but inside the context of a transaction function.See also: khepri:delete/2.
delete(PathPattern, Options)
-spec delete(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), Ret :: khepri:minimal_ret().
Deletes the tree node pointed to by the given path pattern.
This is the same askhepri:delete/3
but inside the context of a transaction function.See also: khepri:delete/3.
delete_many(PathPattern)
-spec delete_many(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes all tree nodes matching the given path pattern.
This is the same askhepri:delete_many/2
but inside the context of a transaction function.See also: khepri:delete_many/2.
delete_many(PathPattern, Options)
-spec delete_many(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), Ret :: khepri:minimal_ret().
Deletes all tree nodes matching the given path pattern.
This is the same askhepri:delete_many/3
but inside the context of a transaction function.See also: khepri:delete_many/3.
exists(PathPattern)
-spec exists(PathPattern) -> Exists when PathPattern :: khepri_path:pattern(), Exists :: boolean().
Indicates if the tree node pointed to by the given path exists or not.
This is the same askhepri:exists/2
but inside the context of a transaction function.See also: khepri:exists/2.
exists(PathPattern, Options)
-spec exists(PathPattern, Options) -> Exists when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), Exists :: boolean().
Indicates if the tree node pointed to by the given path exists or not.
This is the same askhepri:exists/3
but inside the context of a transaction function.See also: khepri:exists/3.
filter(PathPattern, Pred)
-spec filter(PathPattern, Pred) -> Ret when PathPattern :: khepri_path:pattern(), Pred :: khepri:filter_fun(), Ret :: khepri:many_payloads_ret().
Returns a map for which predicate Pred
holds true in tree nodes matching the given path pattern.
khepri:filter/3
but inside the context of a transaction function.See also: khepri:filter/3.
filter(PathPattern, Pred, Options)
-spec filter(PathPattern, Pred, Options) -> Ret when PathPattern :: khepri_path:pattern(), Pred :: khepri:filter_fun(), Options :: khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns a map for which predicate Pred
holds true in tree nodes matching the given path pattern.
khepri:filter/4
but inside the context of a transaction function.See also: khepri:filter/4.
fold(PathPattern, Fun, Acc)
-spec fold(PathPattern, Fun, Acc) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:fold_fun(), Acc :: khepri:fold_acc(), Ret :: khepri:ok(NewAcc) | khepri:error(), NewAcc :: Acc.
Calls Fun
on successive tree nodes matching the given path pattern, starting with Acc
.
khepri:fold/4
but inside the context of a transaction function.See also: khepri:fold/4.
fold(PathPattern, Fun, Acc, Options)
-spec fold(PathPattern, Fun, Acc, Options) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:fold_fun(), Acc :: khepri:fold_acc(), Options :: khepri:tree_options(), Ret :: khepri:ok(NewAcc) | khepri:error(), NewAcc :: Acc.
Calls Fun
on successive tree nodes matching the given path pattern, starting with Acc
.
khepri:fold/5
but inside the context of a transaction function.See also: khepri:fold/5.
foreach(PathPattern, Fun)
-spec foreach(PathPattern, Fun) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:foreach_fun(), Ret :: ok | khepri:error().
Calls Fun
for each tree node matching the given path pattern.
khepri:foreach/3
but inside the context of a transaction function.See also: khepri:foreach/3.
foreach(PathPattern, Fun, Options)
-spec foreach(PathPattern, Fun, Options) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:foreach_fun(), Options :: khepri:tree_options(), Ret :: ok | khepri:error().
Calls Fun
for each tree node matching the given path pattern.
khepri:foreach/4
but inside the context of a transaction function.See also: khepri:foreach/4.
get(PathPattern)
-spec get(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:payload_ret().
Returns the payload of the tree node pointed to by the given path pattern.
This is the same askhepri:get/2
but inside the context of a transaction function.See also: khepri:get/2.
get(PathPattern, Options)
-spec get(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), Ret :: khepri:payload_ret().
Returns the payload of the tree node pointed to by the given path pattern.
This is the same askhepri:get/3
but inside the context of a transaction function.See also: khepri:get/3.
get_many(PathPattern)
-spec get_many(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern.
This is the same askhepri:get_many/2
but inside the context of a transaction function.See also: khepri:get_many/2.
get_many(PathPattern, Options)
-spec get_many(PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern.
This is the same askhepri:get_many/3
but inside the context of a transaction function.See also: khepri:get_many/3.
get_many_or(PathPattern, Default)
-spec get_many_or(PathPattern, Default) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
This is the same askhepri:get_many_or/3
but inside the context of a transaction function.See also: khepri:get_many_or/3.
get_many_or(PathPattern, Default, Options)
-spec get_many_or(PathPattern, Default, Options) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
This is the same askhepri:get_many_or/4
but inside the context of a transaction function.See also: khepri:get_many_or/4.
get_or(PathPattern, Default)
-spec get_or(PathPattern, Default) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Ret :: khepri:payload_ret().
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
This is the same askhepri:get_or/3
but inside the context of a transaction function.See also: khepri:get_or/3.
get_or(PathPattern, Default, Options)
-spec get_or(PathPattern, Default, Options) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: khepri:tree_options(), Ret :: khepri:payload_ret().
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
This is the same askhepri:get_or/4
but inside the context of a transaction function.See also: khepri:get_or/4.
has_data(PathPattern)
-spec has_data(PathPattern) -> HasData | Error when PathPattern :: khepri_path:pattern(), HasData :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path has data or not.
This is the same askhepri:has_data/2
but inside the context of a transaction function.See also: khepri:has_data/2.
has_data(PathPattern, Options)
-spec has_data(PathPattern, Options) -> HasData | Error when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), HasData :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path has data or not.
This is the same askhepri:has_data/3
but inside the context of a transaction function.See also: khepri:has_data/3.
is_sproc(PathPattern)
-spec is_sproc(PathPattern) -> IsSproc | Error when PathPattern :: khepri_path:pattern(), IsSproc :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
This is the same askhepri:is_sproc/2
but inside the context of a transaction function.See also: khepri:is_sproc/2.
is_sproc(PathPattern, Options)
-spec is_sproc(PathPattern, Options) -> IsSproc | Error when PathPattern :: khepri_path:pattern(), Options :: khepri:tree_options(), IsSproc :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
This is the same askhepri:is_sproc/3
but inside the context of a transaction function.See also: khepri:is_sproc/3.
is_transaction()
-spec is_transaction() -> boolean().
map(PathPattern, Fun)
-spec map(PathPattern, Fun) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:map_fun(), Ret :: khepri:ok(Map) | khepri:error(), Map :: #{khepri_path:native_path() => khepri:map_fun_ret()}.
Produces a new map by calling Fun
for each tree node matching the given path pattern.
khepri:map/3
but inside the context of a transaction function.See also: khepri:map/3.
map(PathPattern, Fun, Options)
-spec map(PathPattern, Fun, Options) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:map_fun(), Options :: khepri:tree_options(), Ret :: khepri:ok(Map) | khepri:error(), Map :: #{khepri_path:native_path() => khepri:map_fun_ret()}.
Produces a new map by calling Fun
for each tree node matching the given path pattern.
khepri:map/4
but inside the context of a transaction function.See also: khepri:map/4.
put(PathPattern, Data)
-spec put(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Runs the stored procedure pointed to by the given path and returns the result.
This is the same askhepri:put/3
but inside the context of a transaction function.See also: khepri:put/3.
put(PathPattern, Data, Options)
-spec put(PathPattern, Data, Options) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Runs the stored procedure pointed to by the given path and returns the result.
This is the same askhepri:put/4
but inside the context of a transaction function.See also: khepri:put/4.
put_many(PathPattern, Data)
-spec put_many(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Sets the payload of all the tree nodes matching the given path pattern.
This is the same askhepri:put_many/3
but inside the context of a transaction function.See also: khepri:put_many/3.
put_many(PathPattern, Data, Options)
-spec put_many(PathPattern, Data, Options) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Sets the payload of all the tree nodes matching the given path pattern.
This is the same askhepri:put_many/4
but inside the context of a transaction function.See also: khepri:put_many/4.
update(PathPattern, Data)
-spec update(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Updates an existing tree node with the given payload.
This is the same askhepri:update/3
but inside the context of a transaction function.See also: khepri:update/3.
update(PathPattern, Data, Options)
-spec update(PathPattern, Data, Options) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret().
Updates an existing tree node with the given payload.
This is the same askhepri:update/4
but inside the context of a transaction function.See also: khepri:update/4.