Clustering: Using REFRESH CLUSTER best practices
You use the REFRESH CLUSTER command to discard all locally held information about a cluster and rebuild that information from the full repositories in the cluster. We should not need to use this command, except in exceptional circumstances. If we do need to use it, there are special considerations about how we use it. This information is a guide based on testing and feedback from customers.
Only run REFRESH CLUSTER if you really need to do so
The IBM MQ cluster technology ensures that any change to the cluster configuration, such as a change to a clustered queue, automatically becomes known to any member of the cluster that needs to know the information. There is no need for further administrative steps to be taken to achieve this propagation of information.
If such information does not reach the queue managers in the cluster where it is required, for example a clustered queue is not known by another queue manager in the cluster when an application attempts to open it for the first time, it implies a problem in the cluster infrastructure. For example, it is possible that a channel cannot be started between a queue manager and a full repository queue manager. Therefore, any situation where inconsistencies are observed must be investigated. If possible, resolve the situation without using the REFRESH CLUSTER command.
In rare circumstances that are documented elsewhere in this product documentation, or when requested by IBM support, we can use the REFRESH CLUSTER command to discard all locally held information about a cluster and rebuild that information from the full repositories in the cluster.
Refreshing in a large cluster can affect performance and availability of the cluster
Use of the REFRESH CLUSTER command can be disruptive to the cluster while it is in progress, for example by creating a sudden increase in work for the full repositories as they process the repropagation of queue manager cluster resources. If we are refreshing in a large cluster (that is, many hundreds of queue managers) we should avoid use of the command in day-to-day work if possible and use alternative methods to correct specific inconsistencies. For example, if a cluster queue is not being correctly propagated across the cluster, an initial investigation technique of updating the clustered queue definition, such as altering its description, repropagates the queue configuration across the cluster. This process can help to identify the problem and potentially resolve a temporary inconsistency.
If alternative methods cannot be used, and you have to run REFRESH CLUSTER in a large cluster, we should do so at off-peak times or during a maintenance window to avoid impact on user workloads. We should also avoid refreshing a large cluster in a single batch, and instead stagger the activity as explained in Avoid performance and availability issues when cluster objects send automatic updates.
Avoid performance and availability issues when cluster objects send automatic updates
After a new cluster object is defined on a queue manager, an update for this object is generated every 27 days from the time of definition, and sent to every full repository in the cluster and onwards to any other interested queue managers. When we issue the REFRESH CLUSTER command to a queue manager, you reset the clock for this automatic update on all objects defined locally in the specified cluster.
If you refresh a large cluster (that is, many hundreds of queue managers) in a single batch, or in other circumstances such as recreating a system from configuration backup, after 27 days all of those queue managers will re-advertise all of their object definitions to the full repositories at the same time. This could again cause the system to run significantly slower, or even become unavailable, until all the updates have completed. Therefore, when you have to refresh or re-create multiple queue managers in a large cluster, we should stagger the activity over several hours, or several days, so that subsequent automatic updates do not regularly impact system performance.
The system cluster history queue
When a REFRESH CLUSTER is performed, the queue manager takes a snapshot of the cluster state before the refresh and stores it on the SYSTEM.CLUSTER.HISTORY.QUEUE (SCHQ) if it is defined on the queue manager. This snapshot is for IBM service purposes only, in case of later problems with the system.
The SCHQ is defined by default on distributed queue managers on startup. For z/OS migration, the SCHQ must be manually defined.
Messages on the SCHQ expire after three months.
Parent topic: Clustering: Best practices
Related concepts
Related information