Previous Next JavaScript must be enabled to correctly display this content

## Using Master Affinity Zones

Master Affinity zones let you specify which Primary Zone handles write requests for your client applications.

Oracle NoSQL Databases use zones. Zones duplicate the entire data store, spreading the data store and load across multiple physical locations. Having zones helps to avoid catastrophic data loss and operational disruptions. A zone consists of a number of Storage Nodes (SNs) and Replication Nodes (RNs). See Architecture in the Concepts Guide.

Two kinds of zones exist:

- Primary zones — can host both master nodes and replication nodes, though they are not required to do so. Data read and write requests go to Primary zones configured to handle such requests.

- Secondary zones — have no master node. They handle only read requests from client applications.

Each shard has a single Master Node, which is capable of writing data to all RNs. Regardless of zone type, all zones require high quality network connectivity to maintain optimal performance for writing data to the RNs, and accessing data from RNs for application data requests.

You choose which Primary zones have Master Affinity, which provides a way for you to send write requests to a specific Primary zone. Setting the `-master-affinity` property confirms its designation as such, while keeping the default `–no-master-affinity` property designates that a zone is not a Master Affinity zone. Using the `–master-affinity` property organizes Master nodes from different shards into the Master Affinity zone, providing several advantages:

- Master Affinity zones service high demand write requests across shards.

- When a Master Node fails, a replacement from the Master Affinity zone is available to take over from the failed node, with virtually no lag in service.

- RNs in the Master Affinity zone perform a standard election process to determine the Master Node that assumes the role of the failed Master Node.

Using Master Affinity zones successfully requires knowledge of the zones that are in closest proximity to your client applications with the highest demands. The client application is then predictably serviced by both the Master Node and RNs in the Master Affinity zone.

### Benefits of Master Affinity Zones

Master affinity is a zone property. A zone either has the Master Affinity property (`-master-affinity`), or does not (`-no-master-affinity`). Most likely, you will choose a specific Primary Zone to become a Master Affinity zone because that zone is ideally suited to service demanding client write requests. The candidate zone is in close proximity to the application demands, and has high quality communication capabilities to service them.

You can set the Master Affinity property only on Primary Zones. Once you do, only nodes in Master Affinity zones can become masters during a failover. Having a Master Affinity zone with one or more Master nodes supports both low latency write activities and high availability.

Typically, when a Master Node fails, the Replication Nodes (RNs) enter a selection process to elect a new Master node. The election involves an algorithmic approach using, among other factors, a criteria to elect the RN with the most recent data. Once a zone is a Master Affinity zone, and a Master Node fails, a similar process occurs. When a new Master node exists, write requests are automatically directed to the new Master, and absolute consistency requests are serviced by the new Master in the Master Affinity zone.

All storage nodes (SNs) can determine if they are part of a Master Affinity zone. If they are not part of a Master Affinity zone, they help determine which SNs are candidates to host RNs that will transfer to the Master Affinity zone as potential Master Nodes during election. By choosing and assigning RNs to a Master Affinity zone, if the current Master node fails, the next applicable node will assume its responsibilities.

### Adding a Master Affinity Zone

Describes the Master Affinity zone parameter, and the effects of setting it.

Using Master Affinity zones is optional. By default, after upgrading to the current release, all zones are set to `-no-master-affinity`. To use Master Affinity, you change the zone property manually. The Master Affinity zone property affects only the Replication Node masters, and has no effect on the database Admin masters. This section describes how to use Master Affinity zones, and what effects they can have on your operations.

Your first choice is to determine which zones should have Master Affinity. The chosen zones must be in close physical proximity to the applications they serve. In this way, a Master Affinity zone provides the lowest latency write performance.

As an example, the following topology is for two (2) shards (`rg1` and `rg2`) with a replication factor of three (3), described as a 2 * 3 data store, where `rg2–rn1` and `rg1–rn2` are the master nodes in `zn1` and `zn2`, respectively:

    Storage Node [sn1] on localhost:5100 		Zone: [name=1 id=zn1
    type=PRIMARY allowArbiters=false 			Status: RUNNING
    	Admin [admin1] 			Status: 			RUNNING,MASTER
    	Rep Node [rg1-rn1] 		Status: 			RUNNING,REPLICA
    	Rep Node [rg2-rn1] 		Status: 			RUNNING,MASTER
    Storage Node [sn2] on localhost:5200 		Zone: [name=2 id=zn2
    type=PRIMARY allowArbiters=false  			Status: RUNNING
    	Admin [admin2] 			Status: 			RUNNING,REPLICA
    	Rep Node [rg1-rn2] 		Status: 			RUNNING,MASTER
    	Rep Node [rg2-rn2] 		Status: 			RUNNING,REPLICA
    Storage Node [sn3] on localhost:5300 		Zone: [name=3 id=zn3
    type=PRIMARY allowArbiters=false  			Status: RUNNING
    	Admin [admin3] 			Status: 			RUNNING,REPLICA
    	Rep Node [rg1-rn3] 		Status: 			RUNNING,REPLICA
    	Rep Node [rg2-rn3] 		Status: 			RUNNING,REPLICA

Here are the zones before using Master Affinity. Primary Zones 1 and 2 each have a master node in their respective shards (`rg1` and `rg2`):

Figure 1-3 Zone Distribution Before Master Affinity

Description of "Figure 1-3 Zone Distribution Before Master Affinity"

After choosing the Primary Zone best suited for having Master Affinity, set the `–master-affinity` property as follows:

- When deploying a zone for the first time, use the `plan deploy-zone` command.

- After deploying a zone, use the `topology change-zone-master-affinity` command.

For example, here is the `plan deploy-zone` command being used as part of configuring the store `mystore` to change the `master-affinity` zone property. In this example, you set the `master-affinity` property for Zone 2.

    configure -name mystore
    plan deploy-zone -name 1 -rf 1 -no-master-affinity -wait
    plan deploy-zone -name 2 -rf 1 -master-affinity -wait
    plan deploy-zone -name 3 -rf 1 -wait

Note:

When Master Affinity is in effect for Zone 2, both master nodes for the two shards are placed in Zone 2.

Figure 1-4 Zone Distribution After Master Affinity

Description of "Figure 1-4 Zone Distribution After Master Affinity"

### Losing a Master Affinity Zone Node

Describes what occurs when a Master Node fails in a Master Affinity Zone.

After your initial setup, you determine which Primary zone will be a Master Affinity zone. Using Master Affinity zones optimizes write requests to Master Nodes in that zone. The Storage Nodes (SNs) can detect if they are part of a Master Affinity zone. If an SN is not part of a zone itself, it detects which SNs are part of a Master Affinity zone.

If a Master Affinity zone master node fails, the RNs detect if an applicable node exists within the zone. For example, the Master Affinity zone may have another master node. If another master node is not available, RNs elect the best candidate, or have applicable RNs from other zones migrate into the Master Affinity zone for Master Node consideration. Such zone realignment occurs automatically to support the Master Affinity zone.

Finally, the RNs vote to determine which node should become the next Master node. For voting and deciding on a new master node, only the highest performance RNs can become master nodes in the Master Affinity zone. Once the next Master node is available, Oracle NoSQL directs all write requests and absolute consistency requirements to that Master.