View Source Carbonite.Query (Carbonite v0.12.1)

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

Summary

Functions

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

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

Returns an Ecto.Query.t/0 that selects a outbox by name.

Returns an Ecto.Query.t/0 that selects all completely processed transactions.

Returns an Ecto.Query.t/0 that selects the next batch of transactions for an outbox.

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

Types

Link to this type

changes_option()

View Source (since 0.2.0)
@type changes_option() ::
  prefix_option() | preload_option() | {:table_prefix, prefix()}
Link to this type

current_transaction_option()

View Source (since 0.2.0)
@type current_transaction_option() :: prefix_option() | preload_option()
Link to this type

disabled()

View Source (since 0.2.0)
@type disabled() :: nil | false
Link to this type

outbox_done_option()

View Source (since 0.2.0)
@type outbox_done_option() ::
  prefix_option() | {:min_age, non_neg_integer() | disabled()}
Link to this type

outbox_queue_option()

View Source (since 0.2.0)
@type outbox_queue_option() ::
  prefix_option()
  | preload_option()
  | {:min_age, non_neg_integer() | disabled()}
  | {:limit, non_neg_integer() | disabled()}
Link to this type

prefix()

View Source (since 0.2.0)
@type prefix() :: binary()
Link to this type

prefix_option()

View Source (since 0.2.0)
@type prefix_option() :: {:carbonite_prefix, prefix()}
Link to this type

preload_option()

View Source (since 0.2.0)
@type preload_option() :: {:preload, boolean()}
Link to this type

transactions_option()

View Source (since 0.2.0)
@type transactions_option() :: prefix_option() | preload_option()

Functions

Link to this function

changes(record, opts \\ [])

View Source (since 0.2.0)
@spec changes(record :: Ecto.Schema.t(), [changes_option()]) :: Ecto.Query.t()

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

Given an Ecto.Schema.t/0 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)
@spec current_transaction([current_transaction_option()]) :: Ecto.Query.t()

Returns an Ecto.Query.t/0 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, defaults to false
Link to this function

outbox(outbox_name, opts \\ [])

View Source (since 0.4.0)

Returns an Ecto.Query.t/0 that selects a outbox by name.

Options

  • carbonite_prefix - defines the audit trail's schema, defaults to "carbonite_default"
Link to this function

outbox_done(opts \\ [])

View Source (since 0.4.0)
@spec outbox_done([outbox_done_option()]) :: Ecto.Query.t()

Returns an Ecto.Query.t/0 that selects all completely processed transactions.

  • If no outbox exists, this query returns all transactions.
  • If one or more outboxes exist, this query returns all transactions with an ID less than the minimum of the last_transaction_id attributes of the outboxes.
  • Transactions are not ordered.

Options

  • min_age - the minimum age of a record, defaults to 300 seconds (set nil to disable)
  • carbonite_prefix - defines the audit trail's schema, defaults to "carbonite_default"
Link to this function

outbox_queue(outbox, opts \\ [])

View Source (since 0.4.0)
@spec outbox_queue(Carbonite.Outbox.t(), [outbox_queue_option()]) :: Ecto.Query.t()

Returns an Ecto.Query.t/0 that selects the next batch of transactions for an outbox.

  • Transactions are ordered by their ID ascending, so roughly in order of insertion.

Options

  • min_age - the minimum age of a record, defaults to 300 seconds (set nil to disable)
  • limit - limits the query in size, defaults to 100 (set nil to disable)
  • carbonite_prefix - defines the audit trail's schema, defaults to "carbonite_default"
  • preload - can be used to preload the changes, defaults to true
Link to this function

transactions(opts \\ [])

View Source (since 0.3.1)
@spec transactions([transactions_option()]) :: Ecto.Query.t()

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

Examples

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

# Preload changes
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, defaults to false