Carbonite.Query (Carbonite v0.3.1) View Source

This module provides query functions for retrieving audit trails from the database.

Link to this section Summary

Functions

Returns an Ecto.Query that can be used to select changes for a single record.

Returns an Ecto.Query that can be used to select or delete the "current" transaction.

Returns an Ecto.Query that can be used to select transactions from the database.

Link to this section Types

Specs

changes_option() ::
  {:carbonite_prefix, prefix()}
  | {:table_prefix, prefix()}
  | {:preload, preload()}
Link to this type

current_transaction_option()

View Source

Specs

current_transaction_option() ::
  {:carbonite_prefix, prefix()} | {:preload, preload()}

Specs

prefix() :: binary() | atom()

Specs

preload() :: atom() | [atom()] | true

Specs

transactions_option() :: {:carbonite_prefix, prefix()} | {:preload, preload()}

Link to this section Functions

Link to this function

changes(record, opts \\ [])

View Source (since 0.2.0)

Specs

changes(record :: Ecto.Schema.t(), [changes_option()]) :: Ecto.Query.t()

Returns an Ecto.Query that can be used to select changes for a single record.

Given an Ecto.Schema struct, this function builds a query that fetches all changes recorded for it from the database, ordered ascending by their ID (i.e., roughly by insertion date descending).

Example

%MyApp.Rabbit{id: 1}
|> Carbonite.Query.changes()
|> MyApp.Repo.all()

Options

  • carbonite_prefix defines the audit trail's schema, defaults to "carbonite_default"
  • table_prefix allows to override the table prefix, defaults to schema prefix of the record
  • preload can be used to preload the transaction
Link to this function

current_transaction(opts \\ [])

View Source (since 0.2.0)

Specs

current_transaction([current_transaction_option()]) :: Ecto.Query.t()

Returns an Ecto.Query that can be used to select or delete the "current" transaction.

This function is useful when your tests run in a database transaction using Ecto's SQL sandbox.

Example: Asserting on the current transaction

When you insert your Carbonite.Transaction record somewhere inside your domain logic, you do not wish to return it to the caller only to be able to assert on its attributes in tests. This example shows how you could assert on the metadata inserted.

# Test running inside Ecto's SQL sandbox.
test "my test" do
  some_operation_with_a_transaction()

  assert current_transaction_meta() == %{"type" => "some_operation"}
end

defp current_transaction_meta do
  Carbonite.Query.current_transaction()
  |> MyApp.Repo.one!()
  |> Map.fetch(:meta)
end

Options

  • carbonite_prefix defines the audit trail's schema, defaults to "carbonite_default"
  • preload can be used to preload the changes
Link to this function

transactions(opts \\ [])

View Source (since 0.3.1)

Specs

transactions([transactions_option()]) :: Ecto.Query.t()

Returns an Ecto.Query that can be used to select transactions from the database.

Examples

Carbonite.Query.transactions()
|> MyApp.Repo.all()

# Preload changes
Carbonite.Query.transactions(preload: :changes)
|> MyApp.Repo.all()

# Same
Carbonite.Query.transactions(preload: true)
|> MyApp.Repo.all()

Options

  • carbonite_prefix defines the audit trail's schema, defaults to "carbonite_default"
  • preload can be used to preload the changes