includes/libs/rdbms/database/position/MySQLMasterPos.php

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 use InvalidArgumentException;
   6 use UnexpectedValueException;
   7
   8 /**
   9  * DBMasterPos class for MySQL/MariaDB
  10  *
  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).
  15  *
  16  * @see https://mariadb.com/kb/en/library/gtid/
  17  * @see https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html
  18  */
  19 class MySQLMasterPos implements DBMasterPos {
  20         /** @var string One of (BINARY_LOG, GTID_MYSQL, GTID_MARIA) */
  21         private $style;
  22         /** @var string|null Base name of all Binary Log files */
  23         private $binLog;
  24         /** @var int[]|null Binary Log position tuple (index number, event number) */
  25         private $logPos;
  26         /** @var string[] Map of (server_uuid/gtid_domain_id => GTID) */
  27         private $gtids = [];
  28         /** @var int|null Active GTID domain ID */
  29         private $activeDomain;
  30         /** @var int|null ID of the server were DB writes originate */
  31         private $activeServerId;
  32         /** @var string|null UUID of the server were DB writes originate */
  33         private $activeServerUUID;
  34         /** @var float UNIX timestamp */
  35         private $asOfTime = 0.0;
  36
  37         const BINARY_LOG = 'binary-log';
  38         const GTID_MARIA = 'gtid-maria';
  39         const GTID_MYSQL = 'gtid-mysql';
  40
  41         /** @var int Key name of the binary log index number of a position tuple */
  42         const CORD_INDEX = 0;
  43         /** @var int Key name of the binary log event number of a position tuple */
  44         const CORD_EVENT = 1;
  45
  46         /**
  47          * @param string $position One of (comma separated GTID list, <binlog file>/<integer>)
  48          * @param float $asOfTime UNIX timestamp
  49          */
  50         public function __construct( $position, $asOfTime ) {
  51                 $this->init( $position, $asOfTime );
  52         }
  53
  54         /**
  55          * @param string $position
  56          * @param float $asOfTime
  57          */
  58         protected function init( $position, $asOfTime ) {
  59                 $m = [];
  60                 if ( preg_match( '!^(.+)\.(\d+)/(\d+)$!', $position, $m ) ) {
  61                         $this->binLog = $m[1]; // ideally something like host name
  62                         $this->logPos = [ self::CORD_INDEX => (int)$m[2], self::CORD_EVENT => (int)$m[3] ];
  63                         $this->style = self::BINARY_LOG;
  64                 } else {
  65                         $gtids = array_filter( array_map( 'trim', explode( ',', $position ) ) );
  66                         foreach ( $gtids as $gtid ) {
  67                                 $components = self::parseGTID( $gtid );
  68                                 if ( !$components ) {
  69                                         throw new InvalidArgumentException( "Invalid GTID '$gtid'." );
  70                                 }
  71
  72                                 list( $domain, $pos ) = $components;
  73                                 if ( isset( $this->gtids[$domain] ) ) {
  74                                         // For MySQL, handle the case where some past issue caused a gap in the
  75                                         // executed GTID set, e.g. [last_purged+1,N-1] and [N+1,N+2+K]. Ignore the
  76                                         // gap by using the GTID with the highest ending sequence number.
  77                                         list( , $otherPos ) = self::parseGTID( $this->gtids[$domain] );
  78                                         if ( $pos > $otherPos ) {
  79                                                 $this->gtids[$domain] = $gtid;
  80                                         }
  81                                 } else {
  82                                         $this->gtids[$domain] = $gtid;
  83                                 }
  84
  85                                 if ( is_int( $domain ) ) {
  86                                         $this->style = self::GTID_MARIA; // gtid_domain_id
  87                                 } else {
  88                                         $this->style = self::GTID_MYSQL; // server_uuid
  89                                 }
  90                         }
  91                         if ( !$this->gtids ) {
  92                                 throw new InvalidArgumentException( "GTID set cannot be empty." );
  93                         }
  94                 }
  95
  96                 $this->asOfTime = $asOfTime;
  97         }
  98
  99         public function asOfTime() {
 100                 return $this->asOfTime;
 101         }
 102
 103         public function hasReached( DBMasterPos $pos ) {
 104                 if ( !( $pos instanceof self ) ) {
 105                         throw new InvalidArgumentException( "Position not an instance of " . __CLASS__ );
 106                 }
 107
 108                 // Prefer GTID comparisons, which work with multi-tier replication
 109                 $thisPosByDomain = $this->getActiveGtidCoordinates();
 110                 $thatPosByDomain = $pos->getActiveGtidCoordinates();
 111                 if ( $thisPosByDomain && $thatPosByDomain ) {
 112                         $comparisons = [];
 113                         // Check that this has positions reaching those in $pos for all domains in common
 114                         foreach ( $thatPosByDomain as $domain => $thatPos ) {
 115                                 if ( isset( $thisPosByDomain[$domain] ) ) {
 116                                         $comparisons[] = ( $thatPos <= $thisPosByDomain[$domain] );
 117                                 }
 118                         }
 119                         // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB
 120                         // quirks, prior master switch-overs may result in inactive garbage GTIDs that cannot
 121                         // be cleaned up. Assume that the domains in both this and $pos cover the relevant
 122                         // active channels.
 123                         return ( $comparisons && !in_array( false, $comparisons, true ) );
 124                 }
 125
 126                 // Fallback to the binlog file comparisons
 127                 $thisBinPos = $this->getBinlogCoordinates();
 128                 $thatBinPos = $pos->getBinlogCoordinates();
 129                 if ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] ) {
 130                         return ( $thisBinPos['pos'] >= $thatBinPos['pos'] );
 131                 }
 132
 133                 // Comparing totally different binlogs does not make sense
 134                 return false;
 135         }
 136
 137         public function channelsMatch( DBMasterPos $pos ) {
 138                 if ( !( $pos instanceof self ) ) {
 139                         throw new InvalidArgumentException( "Position not an instance of " . __CLASS__ );
 140                 }
 141
 142                 // Prefer GTID comparisons, which work with multi-tier replication
 143                 $thisPosDomains = array_keys( $this->getActiveGtidCoordinates() );
 144                 $thatPosDomains = array_keys( $pos->getActiveGtidCoordinates() );
 145                 if ( $thisPosDomains && $thatPosDomains ) {
 146                         // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB
 147                         // quirks, prior master switch-overs may result in inactive garbage GTIDs that cannot
 148                         // easily be cleaned up. Assume that the domains in both this and $pos cover the
 149                         // relevant active channels.
 150                         return array_intersect( $thatPosDomains, $thisPosDomains ) ? true : false;
 151                 }
 152
 153                 // Fallback to the binlog file comparisons
 154                 $thisBinPos = $this->getBinlogCoordinates();
 155                 $thatBinPos = $pos->getBinlogCoordinates();
 156
 157                 return ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] );
 158         }
 159
 160         /**
 161          * @return string|null Base name of binary log files
 162          * @since 1.31
 163          */
 164         public function getLogName() {
 165                 return $this->gtids ? null : $this->binLog;
 166         }
 167
 168         /**
 169          * @return int[]|null Tuple of (binary log file number, event number)
 170          * @since 1.31
 171          */
 172         public function getLogPosition() {
 173                 return $this->gtids ? null : $this->logPos;
 174         }
 175
 176         /**
 177          * @return string|null Name of the binary log file for this position
 178          * @since 1.31
 179          */
 180         public function getLogFile() {
 181                 return $this->gtids ? null : "{$this->binLog}.{$this->logPos[self::CORD_INDEX]}";
 182         }
 183
 184         /**
 185          * @return string[] Map of (server_uuid/gtid_domain_id => GTID)
 186          * @since 1.31
 187          */
 188         public function getGTIDs() {
 189                 return $this->gtids;
 190         }
 191
 192         /**
 193          * Set the GTID domain known to be used in new commits on a replication stream of interest
 194          *
 195          * This makes getRelevantActiveGTIDs() filter out GTIDs from other domains
 196          *
 197          * @see MySQLMasterPos::getRelevantActiveGTIDs()
 198          * @see https://mariadb.com/kb/en/library/gtid/#gtid_domain_id
 199          *
 200          * @param int|null $id @@gtid_domain_id of the active replication stream
 201          * @return MySQLMasterPos This instance (since 1.34)
 202          * @since 1.31
 203          */
 204         public function setActiveDomain( $id ) {
 205                 $this->activeDomain = (int)$id;
 206
 207                 return $this;
 208         }
 209
 210         /**
 211          * Set the server ID known to be used in new commits on a replication stream of interest
 212          *
 213          * This makes getRelevantActiveGTIDs() filter out GTIDs from other origin servers
 214          *
 215          * @see MySQLMasterPos::getRelevantActiveGTIDs()
 216          *
 217          * @param int|null $id @@server_id of the server were writes originate
 218          * @return MySQLMasterPos This instance (since 1.34)
 219          * @since 1.31
 220          */
 221         public function setActiveOriginServerId( $id ) {
 222                 $this->activeServerId = (int)$id;
 223
 224                 return $this;
 225         }
 226
 227         /**
 228          * Set the server UUID known to be used in new commits on a replication stream of interest
 229          *
 230          * This makes getRelevantActiveGTIDs() filter out GTIDs from other origin servers
 231          *
 232          * @see MySQLMasterPos::getRelevantActiveGTIDs()
 233          *
 234          * @param string|null $id @@server_uuid of the server were writes originate
 235          * @return MySQLMasterPos This instance (since 1.34)
 236          * @since 1.31
 237          */
 238         public function setActiveOriginServerUUID( $id ) {
 239                 $this->activeServerUUID = $id;
 240
 241                 return $this;
 242         }
 243
 244         /**
 245          * @param MySQLMasterPos $pos
 246          * @param MySQLMasterPos $refPos
 247          * @return string[] List of active GTIDs from $pos that have domains in $refPos
 248          * @since 1.34
 249          */
 250         public static function getRelevantActiveGTIDs( MySQLMasterPos $pos, MySQLMasterPos $refPos ) {
 251                 return array_values( array_intersect_key(
 252                         $pos->gtids,
 253                         $pos->getActiveGtidCoordinates(),
 254                         $refPos->gtids
 255                 ) );
 256         }
 257
 258         /**
 259          * @see https://mariadb.com/kb/en/mariadb/gtid
 260          * @see https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html
 261          * @return array Map of (server_uuid/gtid_domain_id => integer position); possibly empty
 262          */
 263         protected function getActiveGtidCoordinates() {
 264                 $gtidInfos = [];
 265
 266                 foreach ( $this->gtids as $domain => $gtid ) {
 267                         list( $domain, $pos, $server ) = self::parseGTID( $gtid );
 268
 269                         $ignore = false;
 270                         // Filter out GTIDs from non-active replication domains
 271                         if ( $this->style === self::GTID_MARIA && $this->activeDomain !== null ) {
 272                                 $ignore |= ( $domain !== $this->activeDomain );
 273                         }
 274                         // Likewise for GTIDs from non-active replication origin servers
 275                         if ( $this->style === self::GTID_MARIA && $this->activeServerId !== null ) {
 276                                 $ignore |= ( $server !== $this->activeServerId );
 277                         } elseif ( $this->style === self::GTID_MYSQL && $this->activeServerUUID !== null ) {
 278                                 $ignore |= ( $server !== $this->activeServerUUID );
 279                         }
 280
 281                         if ( !$ignore ) {
 282                                 $gtidInfos[$domain] = $pos;
 283                         }
 284                 }
 285
 286                 return $gtidInfos;
 287         }
 288
 289         /**
 290          * @param string $id GTID
 291          * @return array|null [domain ID or server UUID, sequence number, server ID/UUID] or null
 292          */
 293         protected static function parseGTID( $id ) {
 294                 $m = [];
 295                 if ( preg_match( '!^(\d+)-(\d+)-(\d+)$!', $id, $m ) ) {
 296                         // MariaDB style: <domain>-<server id>-<sequence number>
 297                         return [ (int)$m[1], (int)$m[3], (int)$m[2] ];
 298                 } elseif ( preg_match( '!^(\w{8}-\w{4}-\w{4}-\w{4}-\w{12}):(?:\d+-|)(\d+)$!', $id, $m ) ) {
 299                         // MySQL style: <server UUID>:<sequence number>-<sequence number>
 300                         // Normally, the first number should reflect the point (gtid_purged) where older
 301                         // binary logs where purged to save space. When doing comparisons, it may as well
 302                         // be 1 in that case. Assume that this is generally the situation.
 303                         return [ $m[1], (int)$m[2], $m[1] ];
 304                 }
 305
 306                 return null;
 307         }
 308
 309         /**
 310          * @see https://dev.mysql.com/doc/refman/5.7/en/show-master-status.html
 311          * @see https://dev.mysql.com/doc/refman/5.7/en/show-slave-status.html
 312          * @return array|bool Map of (binlog:<string>, pos:(<integer>, <integer>)) or false
 313          */
 314         protected function getBinlogCoordinates() {
 315                 return ( $this->binLog !== null && $this->logPos !== null )
 316                         ? [ 'binlog' => $this->binLog, 'pos' => $this->logPos ]
 317                         : false;
 318         }
 319
 320         public function serialize() {
 321                 return serialize( [
 322                         'position' => $this->__toString(),
 323                         'activeDomain' => $this->activeDomain,
 324                         'activeServerId' => $this->activeServerId,
 325                         'activeServerUUID' => $this->activeServerUUID,
 326                         'asOfTime' => $this->asOfTime
 327                 ] );
 328         }
 329
 330         public function unserialize( $serialized ) {
 331                 $data = unserialize( $serialized );
 332                 if ( !is_array( $data ) ) {
 333                         throw new UnexpectedValueException( __METHOD__ . ": cannot unserialize position" );
 334                 }
 335
 336                 $this->init( $data['position'], $data['asOfTime'] );
 337                 if ( isset( $data['activeDomain'] ) ) {
 338                         $this->setActiveDomain( $data['activeDomain'] );
 339                 }
 340                 if ( isset( $data['activeServerId'] ) ) {
 341                         $this->setActiveOriginServerId( $data['activeServerId'] );
 342                 }
 343                 if ( isset( $data['activeServerUUID'] ) ) {
 344                         $this->setActiveOriginServerUUID( $data['activeServerUUID'] );
 345                 }
 346         }
 347
 348         /**
 349          * @return string GTID set or <binary log file>/<position> (e.g db1034-bin.000976/843431247)
 350          */
 351         public function __toString() {
 352                 return $this->gtids
 353                         ? implode( ',', $this->gtids )
 354                         : $this->getLogFile() . "/{$this->logPos[self::CORD_EVENT]}";
 355         }
 356 }