edeliver_fork v1.4.5 Edeliver.Relup.RunnableInstruction behaviour

This module can be used to provide custom instructions executed during the upgrade.

They can be used in implementations of the Edeliver.Relup.Modification behaviours. A runnable instruction must implement a Edeliver.Relup.RunnableInstruction.run/1 function which will be executed during the upgrade on the nodes.

Example:

defmodule Acme.Relup.PingNodeInstruction do
  use Edeliver.Relup.RunnableInstruction

  def modify_relup(instructions = %Instructions{up_instructions: up_instructions}, _config = %{}) do
    node_name = :"node@host"
    %{instructions|
      up_instructions:   [call_this([node_name]) | instructions.up_instructions],
      down_instructions: [call_this([node_name]) | instructions.down_instructions]
    }
  end

  # executed during hot code upgrade from relup file
  def run(_options = [node_name]) do
    :net_adm.ping(node_name)
  end

  # actually implemented already in this module
  def call_this(arguments) do
    # creates a relup instruction to call `run/1` of this module
    {:apply, {__MODULE__, :run, arguments}}
  end

end

# using the instruction
defmodule Acme.Relup.Modification do
  use Edeliver.Relup.Modification

  def modify_relup(instructions = %Instructions{}, config = %{}) do
    instructions |> Edeliver.Relup.DefaultModification.modify_relup(config) # use default modifications
                 |> Acme.Relup.PingNodeInstruction.modify_relup(config) # apply also custom instructions
  end
end

Summary

Functions

Logs a debug message using the Logger on the running node which is upgraded

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the Edeliver.Relup.RunnableInstruction.dependencies/0 callback are loaded before this instruction is executed during the upgrade

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the Edeliver.Relup.RunnableInstruction.dependencies/0 callback are unloaded after this instruction is executed during the downgrade

Logs an error using the Logger on the running node which is upgraded

Formats and prints the message on the node

Logs an info message using the Logger on the running node which is upgraded

Logs the message of the given type on the node

Logs a warning using the Logger on the running node which is upgraded

Macros

Assumes that the pattern matches or throws an error with the given error message

Callbacks

Returns the arguments which will be passed the Edeliver.Relup.RunnableInstruction.run/1 function during the upgrade

Returns a list of module names which implement the behaviour Edeliver.Relup.RunnableInstruction

Returns a function which inserts the relup instruction

The function to run during hot code upgrade on nodes

Functions

debug(message)

Specs

debug(message :: String.t) :: no_return

Logs a debug message using the Logger on the running node which is upgraded.

In addition the same debug message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies)

Specs

ensure_dependencies_loaded_before_instruction_for_upgrade(instructions :: Edeliver.Relup.Instructions.t, runnable_instruction :: {:apply, {module :: atom, :run, arguments :: [term]}}, dependencies :: [instruction_module :: atom]) :: Edeliver.Relup.Instructions.t

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the Edeliver.Relup.RunnableInstruction.dependencies/0 callback are loaded before this instruction is executed during the upgrade.

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions, call_this_instruction, dependencies)

Specs

ensure_dependencies_unloaded_after_instruction_for_downgrade(instructions :: Edeliver.Relup.Instructions.t, runnable_instruction :: {:apply, {module :: atom, :run, arguments :: [term]}}, dependencies :: [instruction_module :: atom]) :: Edeliver.Relup.Instructions.t

Ensures that all Edeliver.Relup.RunnableInstruction modules used / referenced by this instruction and returned by the Edeliver.Relup.RunnableInstruction.dependencies/0 callback are unloaded after this instruction is executed during the downgrade.

error(message)

Specs

error(message :: String.t) :: no_return

Logs an error using the Logger on the running node which is upgraded.

In addition the same error message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

format_in_upgrade_script(format, arguments)

Specs

format_in_upgrade_script(format :: charlist, arguments :: [term]) :: no_return

Formats and prints the message on the node

running the upgrade script which was started by the $APP/bin/$APP upgrade $RELEASE command.

info(message)

Specs

info(message :: String.t) :: no_return

Logs an info message using the Logger on the running node which is upgraded.

In addition the same info message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

log_in_upgrade_script(type, message)

Specs

log_in_upgrade_script(type :: :error | :warning | :info | :debug, message :: String.t) :: no_return

Logs the message of the given type on the node

which executes the upgrade and displays it as output of the $APP/bin/$APP upgrade $RELEASE command. The message is prefixed with a string derived from the message type.

warn(message)

Specs

warn(message :: String.t) :: no_return

Logs a warning using the Logger on the running node which is upgraded.

In addition the same warning message is logged on the node which executes the upgrade and is displayed as output of the $APP/bin/$APP upgarde $RELEASE command.

Macros

assume(assertion, error_message)

Assumes that the pattern matches or throws an error with the given error message.

The error message is logged as error to the logfile using the Logger and displayed as error output by the $APP/bin/$APP upgrade $RELEASE task using the $APP/ebin/install_upgrade.escript script. If the pattern matches the variables from the matching are assigned.

Callbacks

arguments(instructions, config)

Specs

arguments(instructions :: %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, config :: Edeliver.Relup.Config.t) :: [term]

Returns the arguments which will be passed the Edeliver.Relup.RunnableInstruction.run/1 function during the upgrade.

Default is an empty list.

dependencies()

Specs

dependencies :: [instruction_module :: atom]

Returns a list of module names which implement the behaviour Edeliver.Relup.RunnableInstruction

and are used / referenced by this runnable instruction. These modules must be loaded before this instruction is executed for upgrades and unloaded after this instruction for downgrades. Default is an empty list.

insert_where()

Specs

insert_where :: (%Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term}, Edeliver.Relup.Instruction.instruction -> %Edeliver.Relup.Instructions{changed_modules: term, down_instructions: term, down_version: term, up_instructions: term, up_version: term})

Returns a function which inserts the relup instruction

that calls the Edeliver.Relup.RunnableInstruction.run/1 fuction of this module. Default is inserting it at the end of the instructions

run(options)

Specs

run(options :: [term]) :: :ok

The function to run during hot code upgrade on nodes.

If it throws an error before the point_of_no_return the upgrade is aborted. If it throws an error and was executed after that point, the release is restarted