For more details on Availability groups and how they work, see Gateway Availability groups.
The Availability group API consists of a module (availability_group.api)
with constants, functions, and structures that you can use in custom workflows that need
to interact with Availability groups. A workflow will need to work with Availability
groups if its continued operation would be affected during an Availability group
failover event — that is, when the Primary Gateway node fails and
the Secondary node takes over Gateway requests.
In general, to respond smoothly to failover events within an Availability group, a custom workflow should:
- Monitor the current role of the node that it runs on.
- Provide custom code to be called by the Availability group when a failover (or other) event occurs. This code should perform additional operations required to handle the failover event.
The Availability group API provides the following:
-
Constants for values used by Availability groups
-
Functions you can use in custom workflows to get information about the state of the Availability group and the current node’s role in it.
-
Structures (classes) used by the module.
Performing different operations based on the node state
Sometimes a workflow needs to do different things based on whether the node that's
running it is a Primary (active) node or a Secondary (passive or standby) node. You
can gather information about the local node with the get_node_state() function, performing the
necessary operations depending on the results.
get_node_state() function doesn't just
retrieve information about the role of the local node. It also tells you whether
the node is currently connected to the DNS server and details about the last
heartbeat from the Primary node.
Subscribing to Availability group failover events
The Availability group's subscribe() function lets you register a
callback handler for Availability group-related events. When that event occurs (like
a failover between the Primary and Secondary nodes), the callback function that you
specify is called. That function can then perform any special processing or
operations needed to let the workflow continue operations smoothly. It means your
workflow doesn't need to continuously monitor the Availability group for its
status.
For example, to specify a function to run when a Gateway node
changes its role between Primary and Secondary, you would subscribe to the
NODE_ROLE_CHANGED event.
subscribe().