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