@spec create_outbox(outbox_name(), [create_outbox_option()]) :: :ok

Inserts an outbox record into the database.

Options

• carbonite_prefix is the schema of the audit trail, defaults to "carbonite_default"
• last_transaction_id allows to start the outbox processing after the given transaction id

@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.

@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(), [drop_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 in
• carbonite_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("some-data-migration")

    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-migration")

    execute("INSERT ...")
  end

  def down do
    insert_migration_transaction("some-data-migration")

    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

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.DataMigration do
  defmacro __using__ do
    quote do
      use Ecto.Migration

      import Carbonite.Migrations
      insert_migration_transaction_after_begin()
    end
  end
end

@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"

@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: 12

Options

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