View Source Edeliver.Relup.RunnableInstruction behaviour (edeliver v1.9.2)
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
endLink to this section Summary
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
Assumes that the pattern matches or throws an error with the given error message.
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.
Link to this section Callbacks
@callback 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.
@callback 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.
@callback 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 function of this module.
Default is inserting it at the end of the instructions
@callback 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
Link to this section Functions
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.
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 upgrade $RELEASE command.
ensure_dependencies_loaded_before_instruction_for_upgrade(instructions, call_this_instruction, dependencies)
View Source@spec 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)
View Source@spec 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.
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 upgrade $RELEASE command.
Formats and prints the message on the node
running the upgrade script which was started by the
$APP/bin/$APP upgrade $RELEASE command.
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 upgrade $RELEASE command.
@spec 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.
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 upgrade $RELEASE command.