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:

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:
  1. 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)
  2. The code is verified to make sure it does not perform any denied operations.
  3. The extracted transaction function is stored as a Khepri state machine command in the Ra journal to be replicated on all Ra members.
Functions in this module have simplified return values to cover most frequent use cases. If you need more details about the queried or modified tree nodes, like the ability to distinguish a non-existent tree node from a tree node with no payload, you can use the khepri_tx_adv module.

Link to this section Summary

Types

Return value after a transaction function aborted.
Transaction function signature.
Return value of a transaction function.

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.

Indicates if the calling function runs in the context of a transaction function.

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

-type tx_abort() :: khepri:error(any()).
Return value after a transaction function aborted.
-type tx_fun() :: fun().
Transaction function signature.
Link to this type

tx_fun_result/0

-type tx_fun_result() :: any() | no_return().
Return value of a transaction function.

Link to this section Functions

-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().
Link to this function

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 as khepri:clear_many_payloads/2 but inside the context of a transaction function.

See also: khepri:clear_many_payloads/2.

Link to this function

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 as khepri:clear_many_payloads/3 but inside the context of a transaction function.

See also: khepri:clear_many_payloads/3.

Link to this function

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 as khepri:clear_payload/2 but inside the context of a transaction function.

See also: khepri:clear_payload/2.

Link to this function

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 as khepri:clear_payload/3 but inside the context of a transaction function.

See also: khepri:clear_payload/3.

Link to this function

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 as khepri:compare_and_swap/4 but inside the context of a transaction function.

See also: khepri:compare_and_swap/4.

Link to this function

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 as khepri:compare_and_swap/5 but inside the context of a transaction function.

See also: khepri:compare_and_swap/5.

Link to this function

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 as khepri:count/2 but inside the context of a transaction function.

See also: khepri:count/2.

Link to this function

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 as khepri:count/3 but inside the context of a transaction function.

See also: khepri:count/3.

Link to this function

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 as khepri:create/3 but inside the context of a transaction function.

See also: khepri:create/3.

Link to this function

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 as khepri:create/4 but inside the context of a transaction function.

See also: khepri:create/4.

Link to this function

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 as khepri:delete/2 but inside the context of a transaction function.

See also: khepri:delete/2.

Link to this function

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 as khepri:delete/3 but inside the context of a transaction function.

See also: khepri:delete/3.

Link to this function

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 as khepri:delete_many/2 but inside the context of a transaction function.

See also: khepri:delete_many/2.

Link to this function

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 as khepri:delete_many/3 but inside the context of a transaction function.

See also: khepri:delete_many/3.

Link to this function

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 as khepri:exists/2 but inside the context of a transaction function.

See also: khepri:exists/2.

Link to this function

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 as khepri:exists/3 but inside the context of a transaction function.

See also: khepri:exists/3.

Link to this function

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.

This is the same as khepri:filter/3 but inside the context of a transaction function.

See also: khepri:filter/3.

Link to this function

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.

This is the same as khepri:filter/4 but inside the context of a transaction function.

See also: khepri:filter/4.

Link to this function

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.

This is the same as khepri:fold/4 but inside the context of a transaction function.

See also: khepri:fold/4.

Link to this function

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.

This is the same as khepri:fold/5 but inside the context of a transaction function.

See also: khepri:fold/5.

Link to this function

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.

This is the same as khepri:foreach/3 but inside the context of a transaction function.

See also: khepri:foreach/3.

Link to this function

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.

This is the same as khepri:foreach/4 but inside the context of a transaction function.

See also: khepri:foreach/4.

Link to this function

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 as khepri:get/2 but inside the context of a transaction function.

See also: khepri:get/2.

Link to this function

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 as khepri:get/3 but inside the context of a transaction function.

See also: khepri:get/3.

Link to this function

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 as khepri:get_many/2 but inside the context of a transaction function.

See also: khepri:get_many/2.

Link to this function

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 as khepri:get_many/3 but inside the context of a transaction function.

See also: khepri:get_many/3.

Link to this function

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 as khepri:get_many_or/3 but inside the context of a transaction function.

See also: khepri:get_many_or/3.

Link to this function

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 as khepri:get_many_or/4 but inside the context of a transaction function.

See also: khepri:get_many_or/4.

Link to this function

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 as khepri:get_or/3 but inside the context of a transaction function.

See also: khepri:get_or/3.

Link to this function

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 as khepri:get_or/4 but inside the context of a transaction function.

See also: khepri:get_or/4.

Link to this function

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 as khepri:has_data/2 but inside the context of a transaction function.

See also: khepri:has_data/2.

Link to this function

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 as khepri:has_data/3 but inside the context of a transaction function.

See also: khepri:has_data/3.

Link to this function

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 as khepri:is_sproc/2 but inside the context of a transaction function.

See also: khepri:is_sproc/2.

Link to this function

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 as khepri:is_sproc/3 but inside the context of a transaction function.

See also: khepri:is_sproc/3.

Link to this function

is_transaction()

-spec is_transaction() -> boolean().
Indicates if the calling function runs in the context of a transaction function.
Link to this function

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.

This is the same as khepri:map/3 but inside the context of a transaction function.

See also: khepri:map/3.

Link to this function

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.

This is the same as khepri:map/4 but inside the context of a transaction function.

See also: khepri:map/4.

Link to this function

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 as khepri:put/3 but inside the context of a transaction function.

See also: khepri:put/3.

Link to this function

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 as khepri:put/4 but inside the context of a transaction function.

See also: khepri:put/4.

Link to this function

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 as khepri:put_many/3 but inside the context of a transaction function.

See also: khepri:put_many/3.

Link to this function

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 as khepri:put_many/4 but inside the context of a transaction function.

See also: khepri:put_many/4.

Link to this function

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 as khepri:update/3 but inside the context of a transaction function.

See also: khepri:update/3.

Link to this function

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 as khepri:update/4 but inside the context of a transaction function.

See also: khepri:update/4.