khepri
khepri v0.6.0

khepri_import_export behaviour (khepri v0.6.0)

Wrapper around Mnesia Backup & Restore callback modules.

Khepri uses the same callback module as Mnesia to implement its import and export feature. The Mnesia Backup & Restore API is described in the Mnesia documentation.

Mnesia doesn't provide an Erlang behavior module to ease development. This module can be used as the behavior instead. For example:
  -module(my_export_module).
  -behavior(khepri_import_export).
 
  -export([open_write/1,
           write/2,
           commit_write/1,
           abort_write/1,
 
           open_read/1,
           read/1,
           close_read/1]).

There are two sets of callback functions to implement: one used during export (or "backup" in Mnesia terms), one used during import (or "restore" in Mnesia terms).

export-callback-api

 Export callback API

  1. open_write/1

    This function is called at the beginning of an export. It is responsible for any initialization and must return an {ok, ModulePriv} tuple. ModulePriv is a private state passed to the following functions.

  2. write/2

    This function is called for each subset of the items to export.

    BackupItems is a list of opaque Erlang terms. The callback module can't depend on the structure of these Erlang terms. Only the fact that it is a list is guarantied.

    An empty list of BackupItems means this is the last call to write/2. Otherwise, the way all items to export are split into several subsets and thus several calls to write/2 is undefined.

    At the end of each call, the function must return {ok, NewModulePriv}. This new private state is passed to the subsequent calls.

  3. commit_write/1

    This function is called after successful calls to write/2. It is responsible for doing any cleanup.

    This function can return ok or {ok, Ret} if it wants to return some Erlang terms to the caller.

  4. abort_write/1

    This function is called after failed call to write/2, or if reading from the Khepri store fails. It is responsible for doing any cleanup.

    This function can return ok or {ok, Ret} if it wants to return some Erlang terms to the caller.

import-callback-api

 Import callback API

  1. open_read/1

    This function is called at the beginning of an import. It is responsible for any initialization and must return an {ok, ModulePriv} tuple. ModulePriv is a private state passed to the following functions.

  2. read/1

    This function is one or more times until there is nothing left to import.

    The function must return {ok, BackupItems, NewModulePriv}. This new private state is passed to the subsequent calls.

    BackupItems is a list of opaque Erlang terms. The callback module can't depend on the structure of these Erlang terms. The backup items must be returned exactly as they were at the time of the export and in the same order.

    An empty list of BackupItems means this is the last batch. read/1 won't be called anymore. close_read/1 will be called next instead.

  3. c:close_read(ModulePriv)

    This function is called after the last call to read/1, successful or not, or if the actual import into the Khepri store fails. It is responsible for doing any cleanup.

    This function can return ok or {ok, Ret} if it wants to return some Erlang terms to the caller.

available-callback-modules

 Available callback modules

Khepri comes with khepri_export_erlang. This module offers to export Khepri tree nodes in a plain text file where backup items are formatted as Erlang terms.

Link to this section Summary

Types

backup_item/0

An opaque term passed in a list to write/2 and returned by read/1.

module_priv/0

Private data passed to open_write/1 or open_read/1 initially.

Callbacks

abort_write/1
close_read/1
commit_write/1
open_read/1
open_write/1
read/1
write/2

Link to this section Types

Link to this type

backup_item/0

-type backup_item() :: term().

An opaque term passed in a list to write/2 and returned by read/1.

The callback module must not depend on the content of this term.
Link to this type

module_priv/0

-type module_priv() :: any().

Private data passed to open_write/1 or open_read/1 initially.

The actual term is specific to the callback module implementation. The callback can use this term however it wants. It is returned from most callback functions and passed to the next one.

Link to this section Callbacks

Link to this callback

abort_write/1

-callback abort_write(ModulePriv) -> Ret
               when ModulePriv :: khepri_import_export:module_priv(), Ret :: ok | {error, any()}.
Link to this callback

close_read/1

-callback close_read(ModulePriv) -> Ret
              when
                  ModulePriv :: khepri_import_export:module_priv(),
                  Ret :: ok | {ok, ModulePriv} | {error, any()}.
Link to this callback

commit_write/1

-callback commit_write(ModulePriv) -> Ret
                when
                    ModulePriv :: khepri_import_export:module_priv(),
                    Ret :: ok | {ok, ModulePriv} | {error, any()}.
Link to this callback

open_read/1

-callback open_read(ModulePriv) -> Ret
             when
                 ModulePriv :: khepri_import_export:module_priv(),
                 Ret :: {ok, ModulePriv} | {error, any()}.
Link to this callback

open_write/1

-callback open_write(ModulePriv) -> Ret
              when
                  ModulePriv :: khepri_import_export:module_priv(),
                  Ret :: {ok, ModulePriv} | {error, any()}.
Link to this callback

read/1

-callback read(ModulePriv) -> Ret
        when
            ModulePriv :: khepri_import_export:module_priv(),
            Ret :: {ok, BackupItems, ModulePriv} | {error, any()},
            BackupItems :: [khepri_import_export:backup_item()].
Link to this callback

write/2

-callback write(ModulePriv, BackupItems) -> Ret
         when
             ModulePriv :: khepri_import_export:module_priv(),
             BackupItems :: [khepri_import_export:backup_item()],
             Ret :: {ok, ModulePriv} | {error, any()}.