Goblin.Tx protocol (Goblin v0.5.0)

View Source

Transaction helpers for working with Goblin database transactions.

Usage

Goblin.transaction(db, fn tx ->
  user = Goblin.Tx.get(tx, :user_123)

  if user do
    updated = Map.update!(user, :login_count, &(&1 + 1))
    tx = Goblin.Tx.put(tx, :user_123, updated)
    {:commit, tx, :ok}
  else
    :abort
  end
end)

Goblin.read(db, fn tx -> 
  key1 = Goblin.Tx.get(tx, :start, 0)
  key2 = Goblin.Tx.get(tx, key1)
  {key1, key2}
end)

Summary

Types

return()
t()

Functions

get(tx, key, default \\ nil)

Retrieves a value within a transaction.

get_multi(tx, keys)

Retrieves key-value pairs associated with the provided list of keys.

put(tx, key, value)

Writes a key-value pair within a transaction.

put_multi(tx, pairs)

Writes key-value pairs within a transaction.

remove(tx, key)

Removes a key within a transaction.

remove_multi(tx, keys)

Removes keys within a transaction.

select(tx, opts \\ [])

Retrieves a stream over key-value pairs sorted in ascending order by key.

Types

return()

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

t()

@type t() :: t()

Functions

get(tx, key, default \\ nil)

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

Retrieves a value within a transaction.

Parameters

  • tx - The transaction struct
  • key - The key to look up
  • default - A default value if the key is not found, defaults to nil

Returns

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

Examples

counter = Goblin.Tx.get(tx, :counter, 0)

get_multi(tx, keys)

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

Retrieves key-value pairs associated with the provided list of keys.

Parameters

  • tx - The transaction struct
  • keys - A list of keys to look up

Returns

  • Key-value pairs

Examples

[user1: %{name: "Alice"}, user2: %{name: "Bob"}] = Goblin.Tx.get_multi(tx, [:user1, :user2])

put(tx, key, value)

@spec put(t(), Goblin.db_key(), Goblin.db_value()) :: 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

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.put(tx, :user, %{name: "Alice"})

put_multi(tx, pairs)

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

Writes key-value pairs within a transaction.

Parameters

  • tx - The transaction struct
  • pairs - The key-value pairs

Returns

  • Updated transaction structj

Examples

tx = Goblin.Tx.put_multi(tx, [user1: %{name: "Alice"}, user2: %{name: "Bob"}])

remove(tx, key)

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

Removes a key within a transaction.

Parameters

  • tx - The transaction struct
  • key - The key to remove

Returns

  • Updated transaction struct

Examples

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

remove_multi(tx, keys)

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

Removes keys within a transaction.

Parameters

  • tx - The transaction struct
  • keys - The list of keys to remove

Returns

  • Updated transaction struct

Examples

tx = Goblin.Tx.remove_multi(tx, [:user1, :user2])

select(tx, opts \\ [])

@spec select(
  t(),
  keyword()
) :: Enumerable.t({Goblin.db_key(), Goblin.db_value()})

Retrieves a stream over key-value pairs sorted in ascending order by key.

Parameters

  • tx - The transaction struct
  • opts - A keyword list with two options:
    • :min - The minimum key to range over
    • :max - The maximum key to range over

Examples

[user1: %{name: "Alice"}, user2: %{name: "Bob"}] = Goblin.Tx.select(tx) |> Enum.to_list()

[user1: %{name: "Alice"}] = Goblin.Tx.select(tx, max: :user1) |> Enum.to_list()

[user2: %{name: "Bob"}] = Goblin.Tx.select(tx, min: :user2) |> Enum.to_list()

[user1: %{name: "Alice"}, user2: %{name: "Bob"}] = Goblin.Tx.select(tx, min: :user1, max: :user2) |> Enum.to_list()