View Source Carbonite.Query (Carbonite v0.14.0)
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
@type changes_option() :: prefix_option() | preload_option() | {:table_prefix, prefix()}
@type current_transaction_option() :: prefix_option() | preload_option()
@type disabled() :: nil | false
@type outbox_done_option() :: prefix_option() | {:min_age, non_neg_integer() | disabled()}
@type outbox_queue_option() :: prefix_option() | preload_option() | {:min_age, non_neg_integer() | disabled()} | {:limit, non_neg_integer() | disabled()}
@type prefix() :: binary()
@type prefix_option() :: {:carbonite_prefix, prefix()}
@type preload_option() :: {:preload, boolean()}
@type transactions_option() :: prefix_option() | preload_option()
Functions
@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 recordpreload
can be used to preload the transaction
@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 tofalse
@spec outbox(Carbonite.Outbox.name(), [prefix_option()]) :: Ecto.Query.t()
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"
@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"
@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 totrue
@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 tofalse