View Source Carbonite.Migrations (Carbonite v0.12.1)

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.

Allows to update a trigger configuration option for a given table.

Runs one of Carbonite's migrations.

Types

Link to this type

create_trigger_option()

View Source (since 0.1.0)
@type create_trigger_option() ::
  trigger_option() | {:initially, :deferred | :immediate}
Link to this type

down_option()

View Source (since 0.1.0)
@type down_option() :: {:carbonite_prefix, prefix()} | {:drop_schema, boolean()}
Link to this type

insert_migration_transaction_option()

View Source (since 0.1.0)
@type insert_migration_transaction_option() ::
  {:carbonite_prefix, prefix()} | {:meta, map()}
Link to this type

outbox_name()

View Source (since 0.1.0)
@type outbox_name() :: String.t()
Link to this type

outbox_option()

View Source (since 0.1.0)
@type outbox_option() :: {:carbonite_prefix, prefix()}
@type patch() :: non_neg_integer()
Link to this type

prefix()

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

table_name()

View Source (since 0.1.0)
@type table_name() :: binary() | atom()
Link to this type

trigger_config_key()

View Source (since 0.1.0)
@type trigger_config_key() ::
  :table_prefix
  | :primary_key_columns
  | :excluded_columns
  | :filtered_columns
  | :mode
  | :store_changed_from
Link to this type

trigger_option()

View Source (since 0.1.0)
@type trigger_option() :: {:table_prefix, prefix()} | {:carbonite_prefix, prefix()}
Link to this type

up_option()

View Source (since 0.1.0)
@type up_option() :: {:carbonite_prefix, prefix()}

Functions

Link to this function

create_outbox(outbox_name, opts \\ [])

View Source (since 0.4.0)
@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"
Link to this function

create_trigger(table_name, opts \\ [])

View Source (since 0.4.0)
@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 in
  • carbonite_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.

Link to this function

down(patch_or_range, opts \\ [])

View Source (since 0.4.0)
@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
Link to this function

drop_outbox(outbox_name, opts \\ [])

View Source (since 0.4.0)
@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"
Link to this function

drop_trigger(table_name, opts \\ [])

View Source (since 0.4.0)
@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 in
  • carbonite_prefix is the schema of the audit trail, defaults to "carbonite_default"
Link to this function

insert_migration_transaction(name, opts \\ [])

View Source (since 0.1.0)
@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
Link to this macro

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
Link to this function

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 captures
  • filtered_columns is a list of columns that appear as '[FILTERED]' in the data
  • store_changed_from is a boolean defining whether the changed_from field should be filled
  • mode 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 in
  • carbonite_prefix is the schema of the audit trail, defaults to "carbonite_default"
Link to this function

up(patch_or_range, opts \\ [])

View Source (since 0.4.0)
@spec up(patch() | Range.t(), [up_option()]) :: :ok

Runs one of Carbonite's migrations.

Migration patchlevels

Make sure that you run all migrations in your host application.

  • Initial patch: 1
  • Current patch: 8

Options

  • carbonite_prefix defines the audit trail's schema, defaults to "carbonite_default"