Goblin.Tx protocol (Goblin v0.6.0)

View Source

Protocol for reading and writing within a transaction.

Used inside Goblin.transaction/2 (read-write) and Goblin.read/2 (read-only).

Goblin.transaction(db, fn tx ->
  counter = Goblin.Tx.get(tx, :counter, default: 0)
  tx = Goblin.Tx.put(tx, :counter, counter + 1)
  {:commit, tx, :ok}
end)

Goblin.read(db, fn tx ->
  Goblin.Tx.get(tx, :alice)
end)

Summary

Types

return()
t()

Functions

get(tx, key, opts \\ [])

Retrieves a value within a transaction.

get_multi(tx, keys, opts \\ [])

Retrieves values for multiple keys within a transaction.

put(tx, key, value, opts \\ [])

Writes a key-value pair within a transaction.

put_multi(tx, pairs, opts \\ [])

Writes multiple key-value pairs within a transaction.

remove(tx, key, opts \\ [])

Removes a key within a transaction.

remove_multi(tx, keys, opts \\ [])

Removes multiple keys within a transaction.

Types

return()

@type return() :: {:commit, t(), term()} | :abort

t()

@type t() :: t()

Functions

get(tx, key, opts \\ [])

@spec get(t(), Goblin.db_key(), keyword()) :: Goblin.db_value()

Retrieves a value within a transaction.

Parameters

  • tx - The transaction struct
  • key - The key to look up
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the key is namespaced under
    • :default - Value to return if key is not found (default: nil)

Returns

  • The value associated with the key, or default if not found

Examples

Goblin.Tx.get(tx, :alice)
# => "Alice"

Goblin.Tx.get(tx, :nonexistent, default: :not_found)
# => :not_found

get_multi(tx, keys, opts \\ [])

@spec get_multi(t(), [Goblin.db_key()], keyword()) :: [
  {Goblin.db_key(), Goblin.db_value()}
]

Retrieves values for multiple keys within a transaction.

Keys not found are excluded from the result.

Parameters

  • tx - The transaction struct
  • keys - A list of keys to look up
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the keys are namespaced under

Returns

  • A list of {key, value} tuples for keys found, sorted by key

Examples

[{:alice, "Alice"}, {:bob, "Bob"}] = Goblin.Tx.get_multi(tx, [:alice, :bob])

put(tx, key, value, opts \\ [])

@spec put(t(), Goblin.db_key(), Goblin.db_value(), keyword()) :: t()

Writes a key-value pair within a transaction.

Parameters

  • tx - The transaction struct
  • key - Any Elixir term to use as the key
  • value - Any Elixir term to store
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag to namespace the key under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.put(tx, :alice, "Alice")

put_multi(tx, pairs, opts \\ [])

Writes multiple key-value pairs within a transaction.

Parameters

  • tx - The transaction struct
  • pairs - A list of {key, value} tuples
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag to namespace the keys under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.put_multi(tx, [{:alice, "Alice"}, {:bob, "Bob"}])

remove(tx, key, opts \\ [])

@spec remove(t(), Goblin.db_key(), keyword()) :: t()

Removes a key within a transaction.

Parameters

  • tx - The transaction struct
  • key - The key to remove
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the key is namespaced under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.remove(tx, :alice)

remove_multi(tx, keys, opts \\ [])

@spec remove_multi(t(), [Goblin.db_key()], keyword()) :: t()

Removes multiple keys within a transaction.

Parameters

  • tx - The transaction struct
  • keys - A list of keys to remove
  • opts - A keyword list with the following options (default: []):
    • :tag - Tag the keys are namespaced under

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.remove_multi(tx, [:alice, :bob])