View Source Carbonite.Migrations (Carbonite v0.14.2)
Functions to setup Carbonite audit trails in your migrations.
Summary
Functions
Inserts an outbox record into the database.
Installs a change capture trigger on a table.
Rollback a migration.
Removes an outbox record.
Removes a change capture trigger from a table.
Inserts a transaction for a data migration.
Defines a Ecto.Migration.after_begin/0
implementation for a data migration.
Allows to update a trigger configuration option for a given table.
Runs one of Carbonite's migrations.
Types
@type create_trigger_option() :: trigger_option() | {:initially, :deferred | :immediate}
@type outbox_name() :: String.t()
@type outbox_option() :: {:carbonite_prefix, prefix()}
@type patch() :: non_neg_integer()
@type prefix() :: binary()
@type trigger_config_key() ::
:table_prefix
| :primary_key_columns
| :excluded_columns
| :filtered_columns
| :mode
| :store_changed_from
@type up_option() :: {:carbonite_prefix, prefix()}
Functions
@spec create_outbox(outbox_name(), [outbox_option()]) :: :ok
Inserts an outbox record into the database.
Options
carbonite_prefix
is the schema of the audit trail, defaults to"carbonite_default"
@spec create_trigger(table_name(), [create_trigger_option()]) :: :ok
Installs a change capture trigger on a table.
Options
table_prefix
is the name of the schema the table lives incarbonite_prefix
is the schema of the audit trail, defaults to"carbonite_default"
initially
can be either of:immediate
or:deferred
, defaults to:immediate
Deferred triggers
You may create the trigger with initially: :deferred
option to make it run at the end of your
database transactions. In combination with application logic that only conditionally inserts
the Carbonite.Transaction
, this can be used to avoid storing "empty" transactions, i.e.
Carbonite.Transaction
records without associated Carbonite.Change
.
Please be aware that this is not recommended by the Carbonite team. Instead we recommend to retain the empty transactions and optionally remove them in a preprocessing step or your outbox mechanism. Make sure you know how deferred triggers work before using this option.
@spec down(patch() | Range.t(), [down_option()]) :: :ok
Rollback a migration.
Options
carbonite_prefix
defines the audit trail's schema, defaults to"carbonite_default"
drop_schema
controls whether the initial migration deletes the schema during rollback
@spec drop_outbox(outbox_name(), [outbox_option()]) :: :ok
Removes an outbox record.
Options
carbonite_prefix
is the schema of the audit trail, defaults to"carbonite_default"
@spec drop_trigger(table_name(), [trigger_option()]) :: :ok
Removes a change capture trigger from a table.
Options
table_prefix
is the name of the schema the table lives incarbonite_prefix
is the schema of the audit trail, defaults to"carbonite_default"
@spec insert_migration_transaction(name :: String.t(), [ insert_migration_transaction_option() ]) :: :ok
Inserts a transaction for a data migration.
The transaction's meta
attribute is populated with
{"type": "migration", direction: "up"}
... and additionally the name
from the parameters.
Example
defmodule MyApp.Repo.Migrations.SomeDataMigration do
use Ecto.Migration
import Carbonite.Migrations
def change do
insert_migration_transaction()
execute("UPDATE ...", "...")
end
end
This works the same for up/0
/down/0
-style migrations:
defmodule MyApp.Repo.Migrations.SomeDataMigration do
use Ecto.Migration
import Carbonite.Migrations
def up do
insert_migration_transaction("some-data-migrated")
execute("INSERT ...")
end
def down do
insert_migration_transaction("some-data-rolled-back")
execute("DELETE ...")
end
end
Options
carbonite_prefix
is the schema of the audit trail, defaults to"carbonite_default"
meta
is a map with additional meta information to store on the transaction
insert_migration_transaction_after_begin(opts \\ [])
View Source (since 0.5.0) (macro)Defines a Ecto.Migration.after_begin/0
implementation for a data migration.
See insert_migration_transaction/1
for options.
This determines the name
of the transaction from the migration's module name.
{"direction": "up","name": "my_app/repo/migrations/example", "type": "migration"}
Example
defmodule MyApp.Repo.Migrations.SomeDataMigration do
use Ecto.Migration
import Carbonite.Migrations
insert_migration_transaction_after_begin()
def change do
execute("UPDATE ...")
end
end
Alternatively, if you define your own migration template module:
defmodule MyApp.Migration do
defmacro __using__ do
quote do
use Ecto.Migration
import Carbonite.Migrations
insert_migration_transaction_after_begin()
end
end
end
put_trigger_config(table_name, key, value, opts \\ [])
View Source (since 0.4.0)@spec put_trigger_config(table_name(), trigger_config_key(), any(), [trigger_option()]) :: :ok
Allows to update a trigger configuration option for a given table.
This function builds an SQL UPDATE statement that can be used within a database migration to
update a setting stored in Carbonite's triggers
table without using the Carbonite.Trigger
schema or other application-level code that is prone to change over time. This helps to ensure
that your data migrations continue to function, regardless of future updates to Carbonite.
Configuration values
primary_key_columns
is a list of columns that form the primary key of the table(defaults to `["id"]`, set to `[]` to disable)
excluded_columns
is a list of columns to exclude from change capturesfiltered_columns
is a list of columns that appear as '[FILTERED]' in the datastore_changed_from
is a boolean defining whether thechanged_from
field should be filledmode
is either:capture
or:ignore
and defines the default behaviour of the trigger
Example
Carbonite.Migrations.put_trigger_config("rabbits", :excluded_columns, ["name"])
Options
table_prefix
is the name of the schema the table lives incarbonite_prefix
is the schema of the audit trail, defaults to"carbonite_default"
Runs one of Carbonite's migrations.
Migration patchlevels
Make sure that you run all migrations in your host application.
- Initial patch: 1
- Current patch: 11
Options
carbonite_prefix
defines the audit trail's schema, defaults to"carbonite_default"