ExternalStoreDB.php

Go to the documentation of this file.

<?php
namespace MediaWiki\ExternalStore;
 
use HistoryBlobUtils;
use InvalidArgumentException;
use RuntimeException;
use Wikimedia\Rdbms\DatabaseDomain;
use Wikimedia\Rdbms\DBUnexpectedError;
use Wikimedia\Rdbms\ILoadBalancer;
use Wikimedia\Rdbms\LBFactory;
use Wikimedia\Rdbms\Query;
use Wikimedia\Rdbms\ServerInfo;
use Wikimedia\ScopedCallback;
 
class ExternalStoreDB extends ExternalStoreMedium {
    private $lbFactory;
 
    public function __construct( array $params ) {
        parent::__construct( $params );
        if ( !isset( $params['lbFactory'] ) || !( $params['lbFactory'] instanceof LBFactory ) ) {
            throw new InvalidArgumentException( "LBFactory required in 'lbFactory' field." );
        }
        $this->lbFactory = $params['lbFactory'];
    }
 
    public function fetchFromURL( $url ) {
        [ $cluster, $id, $itemID ] = $this->parseURL( $url );
        $ret = $this->fetchBlob( $cluster, $id, $itemID );
 
        if ( $itemID !== false && $ret !== false ) {
            return $ret->getItem( $itemID );
        }
 
        return $ret;
    }
 
    public function batchFetchFromURLs( array $urls ) {
        $batched = $inverseUrlMap = [];
        foreach ( $urls as $url ) {
            [ $cluster, $id, $itemID ] = $this->parseURL( $url );
            $batched[$cluster][$id][] = $itemID;
            // false $itemID gets cast to int, but should be ok
            // since we do === from the $itemID in $batched
            $inverseUrlMap[$cluster][$id][$itemID] = $url;
        }
        $ret = [];
        foreach ( $batched as $cluster => $batchByCluster ) {
            $res = $this->batchFetchBlobs( $cluster, $batchByCluster );
            foreach ( $res as $id => $blob ) {
                foreach ( $batchByCluster[$id] as $itemID ) {
                    $url = $inverseUrlMap[$cluster][$id][$itemID];
                    if ( $itemID === false ) {
                        $ret[$url] = $blob;
                    } else {
                        $ret[$url] = $blob->getItem( $itemID );
                    }
                }
            }
        }
 
        return $ret;
    }
 
    public function store( $location, $data ) {
        $blobsTable = $this->getTable( $location );
 
        $dbw = $this->getPrimary( $location );
        $dbw->newInsertQueryBuilder()
            ->insertInto( $blobsTable )
            ->row( [ 'blob_text' => $data ] )
            ->caller( __METHOD__ )->execute();
 
        $id = $dbw->insertId();
        if ( !$id ) {
            throw new ExternalStoreException( __METHOD__ . ': no insert ID' );
        }
 
        return "DB://$location/$id";
    }
 
    public function isReadOnly( $location ) {
        if ( parent::isReadOnly( $location ) ) {
            return true;
        }
 
        return ( $this->getLoadBalancer( $location )->getReadOnlyReason() !== false );
    }
 
    private function getLoadBalancer( $cluster ) {
        return $this->lbFactory->getExternalLB( $cluster );
    }
 
    public function getReplica( $cluster ) {
        $lb = $this->getLoadBalancer( $cluster );
 
        return $lb->getConnection(
            DB_REPLICA,
            [],
            $this->getDomainId( $lb->getServerInfo( ServerInfo::WRITER_INDEX ) ),
            $lb::CONN_TRX_AUTOCOMMIT
        );
    }
 
    public function getPrimary( $cluster ) {
        $lb = $this->getLoadBalancer( $cluster );
 
        return $lb->getMaintenanceConnectionRef(
            DB_PRIMARY,
            [],
            $this->getDomainId( $lb->getServerInfo( ServerInfo::WRITER_INDEX ) ),
            $lb::CONN_TRX_AUTOCOMMIT
        );
    }
 
    private function getDomainId( array $server ) {
        if ( $this->isDbDomainExplicit ) {
            return $this->dbDomain; // explicit foreign domain
        }
 
        if ( isset( $server['dbname'] ) ) {
            // T200471: for b/c, treat any "dbname" field as forcing which database to use.
            // MediaWiki/LoadBalancer previously did not enforce any concept of a local DB
            // domain, but rather assumed that the LB server configuration matched $wgDBname.
            // This check is useful when the external storage DB for this cluster does not use
            // the same name as the corresponding "main" DB(s) for wikis.
            $domain = new DatabaseDomain(
                $server['dbname'],
                $server['schema'] ?? null,
                $server['tablePrefix'] ?? ''
            );
 
            return $domain->getId();
        }
 
        return false; // local LB domain
    }
 
    public function getTable( string $cluster ) {
        $lb = $this->getLoadBalancer( $cluster );
        $info = $lb->getServerInfo( ServerInfo::WRITER_INDEX );
 
        return $info['blobs table'] ?? 'blobs';
    }
 
    public function initializeTable( $cluster ) {
        global $IP;
 
        static $supportedTypes = [ 'mysql', 'sqlite' ];
 
        $dbw = $this->getPrimary( $cluster );
        if ( !in_array( $dbw->getType(), $supportedTypes, true ) ) {
            throw new DBUnexpectedError( $dbw, "RDBMS type '{$dbw->getType()}' not supported." );
        }
 
        $sqlFilePath = "$IP/maintenance/storage/blobs.sql";
        $sql = file_get_contents( $sqlFilePath );
        if ( $sql === false ) {
            throw new RuntimeException( "Failed to read '$sqlFilePath'." );
        }
 
        $blobsTable = $this->getTable( $cluster );
        $encTable = $dbw->tableName( $blobsTable );
        $sqlWithReplacedVars = str_replace(
            [ '/*$wgDBprefix*/blobs', '/*_*/blobs' ],
            [ $encTable, $encTable ],
            $sql
        );
 
        $dbw->query(
            new Query(
                $sqlWithReplacedVars,
                $dbw::QUERY_CHANGE_SCHEMA,
                'CREATE',
                $blobsTable,
                $sqlWithReplacedVars
            ),
            __METHOD__
        );
    }
 
    private function fetchBlob( $cluster, $id, $itemID ) {
        static $externalBlobCache = [];
 
        $cacheID = ( $itemID === false ) ? "$cluster/$id" : "$cluster/$id/";
        $cacheID = "$cacheID@{$this->dbDomain}";
 
        if ( isset( $externalBlobCache[$cacheID] ) ) {
            $this->logger->debug( __METHOD__ . ": cache hit on $cacheID" );
 
            return $externalBlobCache[$cacheID];
        }
 
        $this->logger->debug( __METHOD__ . ": cache miss on $cacheID" );
 
        $blobsTable = $this->getTable( $cluster );
 
        $dbr = $this->getReplica( $cluster );
        $ret = $dbr->newSelectQueryBuilder()
            ->select( 'blob_text' )
            ->from( $blobsTable )
            ->where( [ 'blob_id' => $id ] )
            ->caller( __METHOD__ )->fetchField();
 
        if ( $ret === false ) {
            // Try the primary DB
            $this->logger->warning( __METHOD__ . ": primary DB fallback on $cacheID" );
            $trxProfiler = $this->lbFactory->getTransactionProfiler();
            $scope = $trxProfiler->silenceForScope( $trxProfiler::EXPECTATION_REPLICAS_ONLY );
            $dbw = $this->getPrimary( $cluster );
            $ret = $dbw->newSelectQueryBuilder()
                ->select( 'blob_text' )
                ->from( $blobsTable )
                ->where( [ 'blob_id' => $id ] )
                ->caller( __METHOD__ )->fetchField();
            ScopedCallback::consume( $scope );
            if ( $ret === false ) {
                $this->logger->warning( __METHOD__ . ": primary DB failed to find $cacheID" );
            }
        }
        if ( $itemID !== false && $ret !== false ) {
            // Unserialise object; caller extracts item
            $ret = HistoryBlobUtils::unserialize( $ret );
        }
 
        $externalBlobCache = [ $cacheID => $ret ];
 
        return $ret;
    }
 
    private function batchFetchBlobs( $cluster, array $ids ) {
        $blobsTable = $this->getTable( $cluster );
 
        $dbr = $this->getReplica( $cluster );
        $res = $dbr->newSelectQueryBuilder()
            ->select( [ 'blob_id', 'blob_text' ] )
            ->from( $blobsTable )
            ->where( [ 'blob_id' => array_keys( $ids ) ] )
            ->caller( __METHOD__ )
            ->fetchResultSet();
 
        $ret = [];
        $this->mergeBatchResult( $ret, $ids, $res );
        if ( $ids ) {
            // Try the primary
            $this->logger->info(
                __METHOD__ . ": primary fallback on '$cluster' for: " .
                implode( ',', array_keys( $ids ) )
            );
            $trxProfiler = $this->lbFactory->getTransactionProfiler();
            $scope = $trxProfiler->silenceForScope( $trxProfiler::EXPECTATION_REPLICAS_ONLY );
            $dbw = $this->getPrimary( $cluster );
            $res = $dbw->newSelectQueryBuilder()
                ->select( [ 'blob_id', 'blob_text' ] )
                ->from( $blobsTable )
                ->where( [ 'blob_id' => array_keys( $ids ) ] )
                ->caller( __METHOD__ )
                ->fetchResultSet();
            ScopedCallback::consume( $scope );
            $this->mergeBatchResult( $ret, $ids, $res );
        }
        if ( $ids ) {
            $this->logger->error(
                __METHOD__ . ": primary on '$cluster' failed locating items: " .
                implode( ',', array_keys( $ids ) )
            );
        }
 
        return $ret;
    }
 
    private function mergeBatchResult( array &$ret, array &$ids, $res ) {
        foreach ( $res as $row ) {
            $id = $row->blob_id;
            $itemIDs = $ids[$id];
            unset( $ids[$id] ); // to track if everything is found
            if ( count( $itemIDs ) === 1 && reset( $itemIDs ) === false ) {
                // single result stored per blob
                $ret[$id] = $row->blob_text;
            } else {
                // multi result stored per blob
                $ret[$id] = HistoryBlobUtils::unserialize( $row->blob_text );
            }
        }
    }
 
    protected function parseURL( $url ) {
        $path = explode( '/', $url );
 
        return [
            $path[2], // cluster
            $path[3], // id
            $path[4] ?? false // itemID
        ];
    }
 
    public function getClusterForUrl( $url ) {
        $parts = explode( '/', $url );
        return $parts[2] ?? null;
    }
 
    public function getDomainIdForCluster( $cluster ) {
        $lb = $this->getLoadBalancer( $cluster );
        return $this->getDomainId( $lb->getServerInfo( ServerInfo::WRITER_INDEX ) );
    }
}
 
class_alias( ExternalStoreDB::class, 'ExternalStoreDB' );