Wait for a replica to apply a GTID. This function blocks until the replica has executed transactions up to the specified Global Transaction ID.
This function takes a string containing a comma-separated list of global transaction id's (similar to the value of, for example, gtid_binlog_pos). It waits until the value of has the same or higher seq_no within all replication domains specified in the gtid-list; in other words, it waits until the replica has reached the specified GTID position.
An optional second argument gives a timeout in seconds. If the timeout expires before the specified GTID position is reached, then the function returns -1. Passing NULL or a negative number for the timeout means no timeout, and the function will wait indefinitely.
If the wait completes without a timeout, 0 is returned. Passing NULL for the gtid-list makes the function return NULL immediately, without waiting.
The gtid-list may be the empty string, in which case MASTER_GTID_WAIT() returns immediately. If the gtid-list contains fewer domains than , then only those domains are waited upon. If gtid-list contains a domain that is not present in @@gtid_slave_pos, then MASTER_GTID_WAIT() will wait until an event containing such domain_id arrives on the replica (or until timed out or killed).
MASTER_GTID_WAIT() can be useful to ensure that a replica has caught up to a master. Simply take the value of on the master, and use it in a MASTER_GTID_WAIT() call on the replica; when the call completes, the replica will have caught up with that master position.
MASTER_GTID_WAIT() can also be used in client applications together with the session variable. This is useful in a read-scaleout setup, where the application writes to a single master but divides the reads out to a number of replica to distribute the load. In such a setup, there
is a risk that an application could first do an update on the master, and then a bit later do a read on a replica, and if the replica is not fast enough, the data read from the slave might not include the update just made, possibly confusing the application and/or the end-user. One way to avoid this is to request the value of on the master just after the update. Then before doing the read on the replica, do a MASTER_GTID_WAIT() on the value obtained from the master; this will ensure that the read is not performed until the replica has replicated sufficiently far for the update to have become visible.
Note that MASTER_GTID_WAIT() can be used even if the replica is configured not to use GTID for connections (). This is because from MariaDB 10, GTIDs are always logged on the master server, and always recorded on the replica servers.
MASTER_GTID_WAIT() is global; it waits for any master connection to reach the specified GTID position. works only against a specific connection. This also means that while MASTER_POS_WAIT() aborts if its master connection is terminated with or due to an error, MASTER_GTID_WAIT() continues to wait while replicas are stopped.
MASTER_GTID_WAIT() can take its timeout as a floating-point value, so a timeout in fractional seconds is supported, eg. MASTER_GTID_WAIT("0-1-100", 0.5). (The minimum wait is one microsecond, 0.000001 seconds).
Since MASTER_GTID_WAIT() looks only at the seq_no part of the GTIDs, not the server_id, care is needed if a replica becomes diverged from another server so that two different GTIDs with the same seq_no (in the same domain) arrive at the same server. This situation is in any case best avoided; setting is recommended, as this will prevent any such out-of-order sequence numbers from ever being replicated on a replica.
This page is licensed: CC BY-SA / Gnu FDL
MASTER_GTID_WAIT(gtid-list[, timeout)MASTER_GTID_WAIT() allows one to specify a timeout of zero in order to do a non-blocking check to see if the replicas have progressed to a specific GTID position (MASTER_POS_WAIT() takes a zero timeout as meaning an infinite wait). To do an infinite MASTER_GTID_WAIT(), specify a negative timeout, or omit the timeout argument.
MASTER_GTID_WAIT() does not return the number of events executed since the wait started, nor does it return NULL if a replica thread is stopped. It always returns either 0 for successful wait completed, or -1 for timeout reached (or NULL if the specified gtid-pos is NULL).