MySQLMasterPos.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\Rdbms;
 
use InvalidArgumentException;
use UnexpectedValueException;
 
class MySQLMasterPos implements DBMasterPos {
    private $style;
    private $binLog;
    private $logPos;
    private $gtids = [];
    private $activeDomain;
    private $activeServerId;
    private $activeServerUUID;
    private $asOfTime = 0.0;
 
    private const BINARY_LOG = 'binary-log';
    private const GTID_MARIA = 'gtid-maria';
    private const GTID_MYSQL = 'gtid-mysql';
 
    public const CORD_INDEX = 0;
    public const CORD_EVENT = 1;
 
    public function __construct( $position, $asOfTime ) {
        $this->init( $position, $asOfTime );
    }
 
    protected function init( $position, $asOfTime ) {
        $m = [];
        if ( preg_match( '!^(.+)\.(\d+)/(\d+)$!', $position, $m ) ) {
            $this->binLog = $m[1]; // ideally something like host name
            $this->logPos = [ self::CORD_INDEX => (int)$m[2], self::CORD_EVENT => (int)$m[3] ];
            $this->style = self::BINARY_LOG;
        } else {
            $gtids = array_filter( array_map( 'trim', explode( ',', $position ) ) );
            foreach ( $gtids as $gtid ) {
                $components = self::parseGTID( $gtid );
                if ( !$components ) {
                    throw new InvalidArgumentException( "Invalid GTID '$gtid'." );
                }
 
                list( $domain, $pos ) = $components;
                if ( isset( $this->gtids[$domain] ) ) {
                    // For MySQL, handle the case where some past issue caused a gap in the
                    // executed GTID set, e.g. [last_purged+1,N-1] and [N+1,N+2+K]. Ignore the
                    // gap by using the GTID with the highest ending sequence number.
                    list( , $otherPos ) = self::parseGTID( $this->gtids[$domain] );
                    if ( $pos > $otherPos ) {
                        $this->gtids[$domain] = $gtid;
                    }
                } else {
                    $this->gtids[$domain] = $gtid;
                }
 
                if ( is_int( $domain ) ) {
                    $this->style = self::GTID_MARIA; // gtid_domain_id
                } else {
                    $this->style = self::GTID_MYSQL; // server_uuid
                }
            }
            if ( !$this->gtids ) {
                throw new InvalidArgumentException( "GTID set cannot be empty." );
            }
        }
 
        $this->asOfTime = $asOfTime;
    }
 
    public function asOfTime() {
        return $this->asOfTime;
    }
 
    public function hasReached( DBMasterPos $pos ) {
        if ( !( $pos instanceof self ) ) {
            throw new InvalidArgumentException( "Position not an instance of " . __CLASS__ );
        }
 
        // Prefer GTID comparisons, which work with multi-tier replication
        $thisPosByDomain = $this->getActiveGtidCoordinates();
        $thatPosByDomain = $pos->getActiveGtidCoordinates();
        if ( $thisPosByDomain && $thatPosByDomain ) {
            $comparisons = [];
            // Check that this has positions reaching those in $pos for all domains in common
            foreach ( $thatPosByDomain as $domain => $thatPos ) {
                if ( isset( $thisPosByDomain[$domain] ) ) {
                    $comparisons[] = ( $thatPos <= $thisPosByDomain[$domain] );
                }
            }
            // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB
            // quirks, prior master switch-overs may result in inactive garbage GTIDs that cannot
            // be cleaned up. Assume that the domains in both this and $pos cover the relevant
            // active channels.
            return ( $comparisons && !in_array( false, $comparisons, true ) );
        }
 
        // Fallback to the binlog file comparisons
        $thisBinPos = $this->getBinlogCoordinates();
        $thatBinPos = $pos->getBinlogCoordinates();
        if ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] ) {
            return ( $thisBinPos['pos'] >= $thatBinPos['pos'] );
        }
 
        // Comparing totally different binlogs does not make sense
        return false;
    }
 
    public function channelsMatch( DBMasterPos $pos ) {
        if ( !( $pos instanceof self ) ) {
            throw new InvalidArgumentException( "Position not an instance of " . __CLASS__ );
        }
 
        // Prefer GTID comparisons, which work with multi-tier replication
        $thisPosDomains = array_keys( $this->getActiveGtidCoordinates() );
        $thatPosDomains = array_keys( $pos->getActiveGtidCoordinates() );
        if ( $thisPosDomains && $thatPosDomains ) {
            // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB
            // quirks, prior master switch-overs may result in inactive garbage GTIDs that cannot
            // easily be cleaned up. Assume that the domains in both this and $pos cover the
            // relevant active channels.
            return array_intersect( $thatPosDomains, $thisPosDomains ) ? true : false;
        }
 
        // Fallback to the binlog file comparisons
        $thisBinPos = $this->getBinlogCoordinates();
        $thatBinPos = $pos->getBinlogCoordinates();
 
        return ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] );
    }
 
    public function getLogName() {
        return $this->gtids ? null : $this->binLog;
    }
 
    public function getLogPosition() {
        return $this->gtids ? null : $this->logPos;
    }
 
    public function getLogFile() {
        // @phan-suppress-next-line PhanTypeArraySuspiciousNullable
        return $this->gtids ? null : "{$this->binLog}.{$this->logPos[self::CORD_INDEX]}";
    }
 
    public function getGTIDs() {
        return $this->gtids;
    }
 
    public function setActiveDomain( $id ) {
        $this->activeDomain = (int)$id;
 
        return $this;
    }
 
    public function setActiveOriginServerId( $id ) {
        $this->activeServerId = (int)$id;
 
        return $this;
    }
 
    public function setActiveOriginServerUUID( $id ) {
        $this->activeServerUUID = $id;
 
        return $this;
    }
 
    public static function getRelevantActiveGTIDs( MySQLMasterPos $pos, MySQLMasterPos $refPos ) {
        return array_values( array_intersect_key(
            $pos->gtids,
            $pos->getActiveGtidCoordinates(),
            $refPos->gtids
        ) );
    }
 
    protected function getActiveGtidCoordinates() {
        $gtidInfos = [];
 
        foreach ( $this->gtids as $domain => $gtid ) {
            list( $domain, $pos, $server ) = self::parseGTID( $gtid );
 
            $ignore = false;
            // Filter out GTIDs from non-active replication domains
            if ( $this->style === self::GTID_MARIA && $this->activeDomain !== null ) {
                $ignore = $ignore || ( $domain !== $this->activeDomain );
            }
            // Likewise for GTIDs from non-active replication origin servers
            if ( $this->style === self::GTID_MARIA && $this->activeServerId !== null ) {
                $ignore = $ignore || ( $server !== $this->activeServerId );
            } elseif ( $this->style === self::GTID_MYSQL && $this->activeServerUUID !== null ) {
                $ignore = $ignore || ( $server !== $this->activeServerUUID );
            }
 
            if ( !$ignore ) {
                $gtidInfos[$domain] = $pos;
            }
        }
 
        return $gtidInfos;
    }
 
    protected static function parseGTID( $id ) {
        $m = [];
        if ( preg_match( '!^(\d+)-(\d+)-(\d+)$!', $id, $m ) ) {
            // MariaDB style: <domain>-<server id>-<sequence number>
            return [ (int)$m[1], (int)$m[3], (int)$m[2] ];
        } elseif ( preg_match( '!^(\w{8}-\w{4}-\w{4}-\w{4}-\w{12}):(?:\d+-|)(\d+)$!', $id, $m ) ) {
            // MySQL style: <server UUID>:<sequence number>-<sequence number>
            // Normally, the first number should reflect the point (gtid_purged) where older
            // binary logs where purged to save space. When doing comparisons, it may as well
            // be 1 in that case. Assume that this is generally the situation.
            return [ $m[1], (int)$m[2], $m[1] ];
        }
 
        return null;
    }
 
    protected function getBinlogCoordinates() {
        return ( $this->binLog !== null && $this->logPos !== null )
            ? [ 'binlog' => $this->binLog, 'pos' => $this->logPos ]
            : false;
    }
 
    public function serialize() {
        return serialize( [
            'position' => $this->__toString(),
            'activeDomain' => $this->activeDomain,
            'activeServerId' => $this->activeServerId,
            'activeServerUUID' => $this->activeServerUUID,
            'asOfTime' => $this->asOfTime
        ] );
    }
 
    public function unserialize( $serialized ) {
        $data = unserialize( $serialized );
        if ( !is_array( $data ) ) {
            throw new UnexpectedValueException( __METHOD__ . ": cannot unserialize position" );
        }
 
        $this->init( $data['position'], $data['asOfTime'] );
        if ( isset( $data['activeDomain'] ) ) {
            $this->setActiveDomain( $data['activeDomain'] );
        }
        if ( isset( $data['activeServerId'] ) ) {
            $this->setActiveOriginServerId( $data['activeServerId'] );
        }
        if ( isset( $data['activeServerUUID'] ) ) {
            $this->setActiveOriginServerUUID( $data['activeServerUUID'] );
        }
    }
 
    public function __toString() {
        return $this->gtids
            ? implode( ',', $this->gtids )
            // @phan-suppress-next-line PhanTypeArraySuspiciousNullable
            : $this->getLogFile() . "/{$this->logPos[self::CORD_EVENT]}";
    }
}