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

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