cdcb79cde65d79ad357f619524fa8b5974ed8dde
3 namespace Wikimedia\Rdbms
;
5 use InvalidArgumentException
;
6 use UnexpectedValueException
;
9 * DBMasterPos class for MySQL/MariaDB
11 * Note that master positions and sync logic here make some assumptions:
12 * - Binlog-based usage assumes single-source replication and non-hierarchical replication.
13 * - GTID-based usage allows getting/syncing with multi-source replication. It is assumed
14 * that GTID sets are complete (e.g. include all domains on the server).
16 class MySQLMasterPos
implements DBMasterPos
{
17 /** @var string|null Binlog file base name */
19 /** @var int[]|null Binglog file position tuple */
21 /** @var string[] GTID list */
23 /** @var float UNIX timestamp */
24 public $asOfTime = 0.0;
27 * @param string $position One of (comma separated GTID list, <binlog file>/<integer>)
28 * @param float $asOfTime UNIX timestamp
30 public function __construct( $position, $asOfTime ) {
31 $this->init( $position, $asOfTime );
35 * @param string $position
36 * @param float $asOfTime
38 protected function init( $position, $asOfTime ) {
40 if ( preg_match( '!^(.+)\.(\d+)/(\d+)$!', $position, $m ) ) {
41 $this->binlog
= $m[1]; // ideally something like host name
42 $this->pos
= [ (int)$m[2], (int)$m[3] ];
44 $gtids = array_filter( array_map( 'trim', explode( ',', $position ) ) );
45 foreach ( $gtids as $gtid ) {
46 if ( !self
::parseGTID( $gtid ) ) {
47 throw new InvalidArgumentException( "Invalid GTID '$gtid'." );
49 $this->gtids
[] = $gtid;
51 if ( !$this->gtids
) {
52 throw new InvalidArgumentException( "Got empty GTID set." );
56 $this->asOfTime
= $asOfTime;
59 public function asOfTime() {
60 return $this->asOfTime
;
63 public function hasReached( DBMasterPos
$pos ) {
64 if ( !( $pos instanceof self
) ) {
65 throw new InvalidArgumentException( "Position not an instance of " . __CLASS__
);
68 // Prefer GTID comparisons, which work with multi-tier replication
69 $thisPosByDomain = $this->getGtidCoordinates();
70 $thatPosByDomain = $pos->getGtidCoordinates();
71 if ( $thisPosByDomain && $thatPosByDomain ) {
73 // Check that this has positions reaching those in $pos for all domains in common
74 foreach ( $thatPosByDomain as $domain => $thatPos ) {
75 if ( isset( $thisPosByDomain[$domain] ) ) {
76 $comparisons[] = ( $thatPos <= $thisPosByDomain[$domain] );
79 // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB
80 // quirks, prior master switch-overs may result in inactive garbage GTIDs that cannot
81 // be cleaned up. Assume that the domains in both this and $pos cover the relevant
83 return ( $comparisons && !in_array( false, $comparisons, true ) );
86 // Fallback to the binlog file comparisons
87 $thisBinPos = $this->getBinlogCoordinates();
88 $thatBinPos = $pos->getBinlogCoordinates();
89 if ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] ) {
90 return ( $thisBinPos['pos'] >= $thatBinPos['pos'] );
93 // Comparing totally different binlogs does not make sense
97 public function channelsMatch( DBMasterPos
$pos ) {
98 if ( !( $pos instanceof self
) ) {
99 throw new InvalidArgumentException( "Position not an instance of " . __CLASS__
);
102 // Prefer GTID comparisons, which work with multi-tier replication
103 $thisPosDomains = array_keys( $this->getGtidCoordinates() );
104 $thatPosDomains = array_keys( $pos->getGtidCoordinates() );
105 if ( $thisPosDomains && $thatPosDomains ) {
106 // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB
107 // quirks, prior master switch-overs may result in inactive garbage GTIDs that cannot
108 // easily be cleaned up. Assume that the domains in both this and $pos cover the
109 // relevant active channels.
110 return array_intersect( $thatPosDomains, $thisPosDomains ) ?
true : false;
113 // Fallback to the binlog file comparisons
114 $thisBinPos = $this->getBinlogCoordinates();
115 $thatBinPos = $pos->getBinlogCoordinates();
117 return ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] );
121 * @return string|null
123 public function getLogFile() {
124 return $this->gtids ?
null : "{$this->binlog}.{$this->pos[0]}";
130 public function getGTIDs() {
135 * @return string GTID set or <binlog file>/<position> (e.g db1034-bin.000976/843431247)
137 public function __toString() {
139 ?
implode( ',', $this->gtids
)
140 : $this->getLogFile() . "/{$this->pos[1]}";
144 * @param MySQLMasterPos $pos
145 * @param MySQLMasterPos $refPos
146 * @return string[] List of GTIDs from $pos that have domains in $refPos
148 public static function getCommonDomainGTIDs( MySQLMasterPos
$pos, MySQLMasterPos
$refPos ) {
151 $relevantDomains = $refPos->getGtidCoordinates(); // (domain => unused)
152 foreach ( $pos->gtids
as $gtid ) {
153 list( $domain ) = self
::parseGTID( $gtid );
154 if ( isset( $relevantDomains[$domain] ) ) {
155 $gtidsCommon[] = $gtid;
163 * @see https://mariadb.com/kb/en/mariadb/gtid
164 * @see https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html
165 * @return array Map of (domain => integer position); possibly empty
167 protected function getGtidCoordinates() {
169 foreach ( $this->gtids
as $gtid ) {
170 list( $domain, $pos ) = self
::parseGTID( $gtid );
171 $gtidInfos[$domain] = $pos;
178 * @param string $gtid
179 * @return array|null [domain, integer position] or null
181 protected static function parseGTID( $gtid ) {
183 if ( preg_match( '!^(\d+)-\d+-(\d+)$!', $gtid, $m ) ) {
184 // MariaDB style: <domain>-<server id>-<sequence number>
185 return [ (int)$m[1], (int)$m[2] ];
186 } elseif ( preg_match( '!^(\w{8}-\w{4}-\w{4}-\w{4}-\w{12}):(\d+)$!', $gtid, $m ) ) {
187 // MySQL style: <UUID domain>:<sequence number>
188 return [ $m[1], (int)$m[2] ];
195 * @see https://dev.mysql.com/doc/refman/5.7/en/show-master-status.html
196 * @see https://dev.mysql.com/doc/refman/5.7/en/show-slave-status.html
197 * @return array|bool (binlog, (integer file number, integer position)) or false
199 protected function getBinlogCoordinates() {
200 return ( $this->binlog
!== null && $this->pos
!== null )
201 ?
[ 'binlog' => $this->binlog
, 'pos' => $this->pos
]
205 public function serialize() {
206 return serialize( [ 'position' => $this->__toString(), 'asOfTime' => $this->asOfTime
] );
209 public function unserialize( $serialized ) {
210 $data = unserialize( $serialized );
211 if ( !is_array( $data ) ) {
212 throw new UnexpectedValueException( __METHOD__
. ": cannot unserialize position" );
215 $this->init( $data['position'], $data['asOfTime'] );