RevisionStore.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Revision;

use ActorMigration;
use CommentStore;
use CommentStoreComment;
use Content;
use ContentHandler;
use DBAccessObjectUtils;
use Hooks;
use IDBAccessObject;
use InvalidArgumentException;
use IP;
use LogicException;
use MediaWiki\Linker\LinkTarget;
use MediaWiki\Storage\BlobAccessException;
use MediaWiki\Storage\BlobStore;
use MediaWiki\Storage\NameTableAccessException;
use MediaWiki\Storage\NameTableStore;
use MediaWiki\Storage\SqlBlobStore;
use MediaWiki\User\UserIdentity;
use MediaWiki\User\UserIdentityValue;
use Message;
use MWException;
use MWUnknownContentModelException;
use Psr\Log\LoggerAwareInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use RecentChange;
use Revision;
use RuntimeException;
use stdClass;
use Title;
use User;
use WANObjectCache;
use Wikimedia\Assert\Assert;
use Wikimedia\Rdbms\Database;
use Wikimedia\Rdbms\DBConnRef;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\ILoadBalancer;

class RevisionStore
    implements IDBAccessObject, RevisionFactory, RevisionLookup, LoggerAwareInterface {

    const ROW_CACHE_KEY = 'revision-row-1.29';

    private $blobStore;

    private $wikiId;

    private $contentHandlerUseDB = true;

    private $loadBalancer;

    private $cache;

    private $commentStore;

    private $actorMigration;

    private $logger;

    private $contentModelStore;

    private $slotRoleStore;

    private $mcrMigrationStage;

    private $slotRoleRegistry;

    public function __construct(
        ILoadBalancer $loadBalancer,
        SqlBlobStore $blobStore,
        WANObjectCache $cache,
        CommentStore $commentStore,
        NameTableStore $contentModelStore,
        NameTableStore $slotRoleStore,
        SlotRoleRegistry $slotRoleRegistry,
        $mcrMigrationStage,
        ActorMigration $actorMigration,
        $wikiId = false
    ) {
        Assert::parameterType( 'string|boolean', $wikiId, '$wikiId' );
        Assert::parameterType( 'integer', $mcrMigrationStage, '$mcrMigrationStage' );
        Assert::parameter(
            ( $mcrMigrationStage & SCHEMA_COMPAT_READ_BOTH ) !== SCHEMA_COMPAT_READ_BOTH,
            '$mcrMigrationStage',
            'Reading from the old and the new schema at the same time is not supported.'
        );
        Assert::parameter(
            ( $mcrMigrationStage & SCHEMA_COMPAT_READ_BOTH ) !== 0,
            '$mcrMigrationStage',
            'Reading needs to be enabled for the old or the new schema.'
        );
        Assert::parameter(
            ( $mcrMigrationStage & SCHEMA_COMPAT_WRITE_BOTH ) !== 0,
            '$mcrMigrationStage',
            'Writing needs to be enabled for the old or the new schema.'
        );
        Assert::parameter(
            ( $mcrMigrationStage & SCHEMA_COMPAT_READ_OLD ) === 0
            || ( $mcrMigrationStage & SCHEMA_COMPAT_WRITE_OLD ) !== 0,
            '$mcrMigrationStage',
            'Cannot read the old schema when not also writing it.'
        );
        Assert::parameter(
            ( $mcrMigrationStage & SCHEMA_COMPAT_READ_NEW ) === 0
            || ( $mcrMigrationStage & SCHEMA_COMPAT_WRITE_NEW ) !== 0,
            '$mcrMigrationStage',
            'Cannot read the new schema when not also writing it.'
        );

        $this->loadBalancer = $loadBalancer;
        $this->blobStore = $blobStore;
        $this->cache = $cache;
        $this->commentStore = $commentStore;
        $this->contentModelStore = $contentModelStore;
        $this->slotRoleStore = $slotRoleStore;
        $this->slotRoleRegistry = $slotRoleRegistry;
        $this->mcrMigrationStage = $mcrMigrationStage;
        $this->actorMigration = $actorMigration;
        $this->wikiId = $wikiId;
        $this->logger = new NullLogger();
    }

    private function hasMcrSchemaFlags( $flags ) {
        return ( $this->mcrMigrationStage & $flags ) === $flags;
    }

    private function assertCrossWikiContentLoadingIsSafe() {
        if ( $this->wikiId !== false && $this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_OLD ) ) {
            throw new RevisionAccessException(
                "Cross-wiki content loading is not supported by the pre-MCR schema"
            );
        }
    }

    public function setLogger( LoggerInterface $logger ) {
        $this->logger = $logger;
    }

    public function isReadOnly() {
        return $this->blobStore->isReadOnly();
    }

    public function getContentHandlerUseDB() {
        return $this->contentHandlerUseDB;
    }

    public function setContentHandlerUseDB( $contentHandlerUseDB ) {
        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW )
            || $this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_NEW )
        ) {
            if ( !$contentHandlerUseDB ) {
                throw new MWException(
                    'Content model must be stored in the database for multi content revision migration.'
                );
            }
        }
        $this->contentHandlerUseDB = $contentHandlerUseDB;
    }

    private function getDBLoadBalancer() {
        return $this->loadBalancer;
    }

    private function getDBConnection( $mode, $groups = [] ) {
        $lb = $this->getDBLoadBalancer();
        return $lb->getConnection( $mode, $groups, $this->wikiId );
    }

    private function getDBConnectionRefForQueryFlags( $queryFlags ) {
        list( $mode, ) = DBAccessObjectUtils::getDBOptions( $queryFlags );
        return $this->getDBConnectionRef( $mode );
    }

    private function releaseDBConnection( IDatabase $connection ) {
        $lb = $this->getDBLoadBalancer();
        $lb->reuseConnection( $connection );
    }

    private function getDBConnectionRef( $mode ) {
        $lb = $this->getDBLoadBalancer();
        return $lb->getConnectionRef( $mode, [], $this->wikiId );
    }

    public function getTitle( $pageId, $revId, $queryFlags = self::READ_NORMAL ) {
        if ( !$pageId && !$revId ) {
            throw new InvalidArgumentException( '$pageId and $revId cannot both be 0 or null' );
        }

        // This method recalls itself with READ_LATEST if READ_NORMAL doesn't get us a Title
        // So ignore READ_LATEST_IMMUTABLE flags and handle the fallback logic in this method
        if ( DBAccessObjectUtils::hasFlags( $queryFlags, self::READ_LATEST_IMMUTABLE ) ) {
            $queryFlags = self::READ_NORMAL;
        }

        $canUseTitleNewFromId = ( $pageId !== null && $pageId > 0 && $this->wikiId === false );
        list( $dbMode, $dbOptions ) = DBAccessObjectUtils::getDBOptions( $queryFlags );
        $titleFlags = ( $dbMode == DB_MASTER ? Title::GAID_FOR_UPDATE : 0 );

        // Loading by ID is best, but Title::newFromID does not support that for foreign IDs.
        if ( $canUseTitleNewFromId ) {
            // TODO: better foreign title handling (introduce TitleFactory)
            $title = Title::newFromID( $pageId, $titleFlags );
            if ( $title ) {
                return $title;
            }
        }

        // rev_id is defined as NOT NULL, but this revision may not yet have been inserted.
        $canUseRevId = ( $revId !== null && $revId > 0 );

        if ( $canUseRevId ) {
            $dbr = $this->getDBConnectionRef( $dbMode );
            // @todo: Title::getSelectFields(), or Title::getQueryInfo(), or something like that
            $row = $dbr->selectRow(
                [ 'revision', 'page' ],
                [
                    'page_namespace',
                    'page_title',
                    'page_id',
                    'page_latest',
                    'page_is_redirect',
                    'page_len',
                ],
                [ 'rev_id' => $revId ],
                __METHOD__,
                $dbOptions,
                [ 'page' => [ 'JOIN', 'page_id=rev_page' ] ]
            );
            if ( $row ) {
                // TODO: better foreign title handling (introduce TitleFactory)
                return Title::newFromRow( $row );
            }
        }

        // If we still don't have a title, fallback to master if that wasn't already happening.
        if ( $dbMode !== DB_MASTER ) {
            $title = $this->getTitle( $pageId, $revId, self::READ_LATEST );
            if ( $title ) {
                $this->logger->info(
                    __METHOD__ . ' fell back to READ_LATEST and got a Title.',
                    [ 'trace' => wfBacktrace() ]
                );
                return $title;
            }
        }

        throw new RevisionAccessException(
            "Could not determine title for page ID $pageId and revision ID $revId"
        );
    }

    private function failOnNull( $value, $name ) {
        if ( $value === null ) {
            throw new IncompleteRevisionException(
                "$name must not be " . var_export( $value, true ) . "!"
            );
        }

        return $value;
    }

    private function failOnEmpty( $value, $name ) {
        if ( $value === null || $value === 0 || $value === '' ) {
            throw new IncompleteRevisionException(
                "$name must not be " . var_export( $value, true ) . "!"
            );
        }

        return $value;
    }

    public function insertRevisionOn( RevisionRecord $rev, IDatabase $dbw ) {
        // TODO: pass in a DBTransactionContext instead of a database connection.
        $this->checkDatabaseWikiId( $dbw );

        $slotRoles = $rev->getSlotRoles();

        // Make sure the main slot is always provided throughout migration
        if ( !in_array( SlotRecord::MAIN, $slotRoles ) ) {
            throw new InvalidArgumentException(
                'main slot must be provided'
            );
        }

        // If we are not writing into the new schema, we can't support extra slots.
        if ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW )
            && $slotRoles !== [ SlotRecord::MAIN ]
        ) {
            throw new InvalidArgumentException(
                'Only the main slot is supported when not writing to the MCR enabled schema!'
            );
        }

        // As long as we are not reading from the new schema, we don't want to write extra slots.
        if ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_NEW )
            && $slotRoles !== [ SlotRecord::MAIN ]
        ) {
            throw new InvalidArgumentException(
                'Only the main slot is supported when not reading from the MCR enabled schema!'
            );
        }

        // Checks
        $this->failOnNull( $rev->getSize(), 'size field' );
        $this->failOnEmpty( $rev->getSha1(), 'sha1 field' );
        $this->failOnEmpty( $rev->getTimestamp(), 'timestamp field' );
        $comment = $this->failOnNull( $rev->getComment( RevisionRecord::RAW ), 'comment' );
        $user = $this->failOnNull( $rev->getUser( RevisionRecord::RAW ), 'user' );
        $this->failOnNull( $user->getId(), 'user field' );
        $this->failOnEmpty( $user->getName(), 'user_text field' );

        if ( !$rev->isReadyForInsertion() ) {
            // This is here for future-proofing. At the time this check being added, it
            // was redundant to the individual checks above.
            throw new IncompleteRevisionException( 'Revision is incomplete' );
        }

        // TODO: we shouldn't need an actual Title here.
        $title = Title::newFromLinkTarget( $rev->getPageAsLinkTarget() );
        $pageId = $this->failOnEmpty( $rev->getPageId(), 'rev_page field' ); // check this early

        $parentId = $rev->getParentId() === null
            ? $this->getPreviousRevisionId( $dbw, $rev )
            : $rev->getParentId();

        $rev = $dbw->doAtomicSection(
            __METHOD__,
            function ( IDatabase $dbw, $fname ) use (
                $rev,
                $user,
                $comment,
                $title,
                $pageId,
                $parentId
            ) {
                return $this->insertRevisionInternal(
                    $rev,
                    $dbw,
                    $user,
                    $comment,
                    $title,
                    $pageId,
                    $parentId
                );
            }
        );

        // sanity checks
        Assert::postcondition( $rev->getId() > 0, 'revision must have an ID' );
        Assert::postcondition( $rev->getPageId() > 0, 'revision must have a page ID' );
        Assert::postcondition(
            $rev->getComment( RevisionRecord::RAW ) !== null,
            'revision must have a comment'
        );
        Assert::postcondition(
            $rev->getUser( RevisionRecord::RAW ) !== null,
            'revision must have a user'
        );

        // Trigger exception if the main slot is missing.
        // Technically, this could go away after MCR migration: while
        // calling code may require a main slot to exist, RevisionStore
        // really should not know or care about that requirement.
        $rev->getSlot( SlotRecord::MAIN, RevisionRecord::RAW );

        foreach ( $slotRoles as $role ) {
            $slot = $rev->getSlot( $role, RevisionRecord::RAW );
            Assert::postcondition(
                $slot->getContent() !== null,
                $role . ' slot must have content'
            );
            Assert::postcondition(
                $slot->hasRevision(),
                $role . ' slot must have a revision associated'
            );
        }

        Hooks::run( 'RevisionRecordInserted', [ $rev ] );

        // TODO: deprecate in 1.32!
        $legacyRevision = new Revision( $rev );
        Hooks::run( 'RevisionInsertComplete', [ &$legacyRevision, null, null ] );

        return $rev;
    }

    private function insertRevisionInternal(
        RevisionRecord $rev,
        IDatabase $dbw,
        User $user,
        CommentStoreComment $comment,
        Title $title,
        $pageId,
        $parentId
    ) {
        $slotRoles = $rev->getSlotRoles();

        $revisionRow = $this->insertRevisionRowOn(
            $dbw,
            $rev,
            $title,
            $parentId
        );

        $revisionId = $revisionRow['rev_id'];

        $blobHints = [
            BlobStore::PAGE_HINT => $pageId,
            BlobStore::REVISION_HINT => $revisionId,
            BlobStore::PARENT_HINT => $parentId,
        ];

        $newSlots = [];
        foreach ( $slotRoles as $role ) {
            $slot = $rev->getSlot( $role, RevisionRecord::RAW );

            // If the SlotRecord already has a revision ID set, this means it already exists
            // in the database, and should already belong to the current revision.
            // However, a slot may already have a revision, but no content ID, if the slot
            // is emulated based on the archive table, because we are in SCHEMA_COMPAT_READ_OLD
            // mode, and the respective archive row was not yet migrated to the new schema.
            // In that case, a new slot row (and content row) must be inserted even during
            // undeletion.
            if ( $slot->hasRevision() && $slot->hasContentId() ) {
                // TODO: properly abort transaction if the assertion fails!
                Assert::parameter(
                    $slot->getRevision() === $revisionId,
                    'slot role ' . $slot->getRole(),
                    'Existing slot should belong to revision '
                    . $revisionId . ', but belongs to revision ' . $slot->getRevision() . '!'
                );

                // Slot exists, nothing to do, move along.
                // This happens when restoring archived revisions.

                $newSlots[$role] = $slot;

                // Write the main slot's text ID to the revision table for backwards compatibility
                if ( $slot->getRole() === SlotRecord::MAIN
                    && $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_OLD )
                ) {
                    $blobAddress = $slot->getAddress();
                    $this->updateRevisionTextId( $dbw, $revisionId, $blobAddress );
                }
            } else {
                $newSlots[$role] = $this->insertSlotOn( $dbw, $revisionId, $slot, $title, $blobHints );
            }
        }

        $this->insertIpChangesRow( $dbw, $user, $rev, $revisionId );

        $rev = new RevisionStoreRecord(
            $title,
            $user,
            $comment,
            (object)$revisionRow,
            new RevisionSlots( $newSlots ),
            $this->wikiId
        );

        return $rev;
    }

    private function updateRevisionTextId( IDatabase $dbw, $revisionId, &$blobAddress ) {
        $textId = $this->blobStore->getTextIdFromAddress( $blobAddress );
        if ( !$textId ) {
            throw new LogicException(
                'Blob address not supported in 1.29 database schema: ' . $blobAddress
            );
        }

        // getTextIdFromAddress() is free to insert something into the text table, so $textId
        // may be a new value, not anything already contained in $blobAddress.
        $blobAddress = SqlBlobStore::makeAddressFromTextId( $textId );

        $dbw->update(
            'revision',
            [ 'rev_text_id' => $textId ],
            [ 'rev_id' => $revisionId ],
            __METHOD__
        );

        return $textId;
    }

    private function insertSlotOn(
        IDatabase $dbw,
        $revisionId,
        SlotRecord $protoSlot,
        Title $title,
        array $blobHints = []
    ) {
        if ( $protoSlot->hasAddress() ) {
            $blobAddress = $protoSlot->getAddress();
        } else {
            $blobAddress = $this->storeContentBlob( $protoSlot, $title, $blobHints );
        }

        $contentId = null;

        // Write the main slot's text ID to the revision table for backwards compatibility
        if ( $protoSlot->getRole() === SlotRecord::MAIN
            && $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_OLD )
        ) {
            // If SCHEMA_COMPAT_WRITE_NEW is also set, the fake content ID is overwritten
            // with the real content ID below.
            $textId = $this->updateRevisionTextId( $dbw, $revisionId, $blobAddress );
            $contentId = $this->emulateContentId( $textId );
        }

        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW ) ) {
            if ( $protoSlot->hasContentId() ) {
                $contentId = $protoSlot->getContentId();
            } else {
                $contentId = $this->insertContentRowOn( $protoSlot, $dbw, $blobAddress );
            }

            $this->insertSlotRowOn( $protoSlot, $dbw, $revisionId, $contentId );
        }

        $savedSlot = SlotRecord::newSaved(
            $revisionId,
            $contentId,
            $blobAddress,
            $protoSlot
        );

        return $savedSlot;
    }

    private function insertIpChangesRow(
        IDatabase $dbw,
        User $user,
        RevisionRecord $rev,
        $revisionId
    ) {
        if ( $user->getId() === 0 && IP::isValid( $user->getName() ) ) {
            $ipcRow = [
                'ipc_rev_id'        => $revisionId,
                'ipc_rev_timestamp' => $dbw->timestamp( $rev->getTimestamp() ),
                'ipc_hex'           => IP::toHex( $user->getName() ),
            ];
            $dbw->insert( 'ip_changes', $ipcRow, __METHOD__ );
        }
    }

    private function insertRevisionRowOn(
        IDatabase $dbw,
        RevisionRecord $rev,
        Title $title,
        $parentId
    ) {
        $revisionRow = $this->getBaseRevisionRow( $dbw, $rev, $title, $parentId );

        list( $commentFields, $commentCallback ) =
            $this->commentStore->insertWithTempTable(
                $dbw,
                'rev_comment',
                $rev->getComment( RevisionRecord::RAW )
            );
        $revisionRow += $commentFields;

        list( $actorFields, $actorCallback ) =
            $this->actorMigration->getInsertValuesWithTempTable(
                $dbw,
                'rev_user',
                $rev->getUser( RevisionRecord::RAW )
            );
        $revisionRow += $actorFields;

        $dbw->insert( 'revision', $revisionRow, __METHOD__ );

        if ( !isset( $revisionRow['rev_id'] ) ) {
            // only if auto-increment was used
            $revisionRow['rev_id'] = intval( $dbw->insertId() );

            if ( $dbw->getType() === 'mysql' ) {
                // (T202032) MySQL until 8.0 and MariaDB until some version after 10.1.34 don't save the
                // auto-increment value to disk, so on server restart it might reuse IDs from deleted
                // revisions. We can fix that with an insert with an explicit rev_id value, if necessary.

                $maxRevId = intval( $dbw->selectField( 'archive', 'MAX(ar_rev_id)', '', __METHOD__ ) );
                $table = 'archive';
                if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW ) ) {
                    $maxRevId2 = intval( $dbw->selectField( 'slots', 'MAX(slot_revision_id)', '', __METHOD__ ) );
                    if ( $maxRevId2 >= $maxRevId ) {
                        $maxRevId = $maxRevId2;
                        $table = 'slots';
                    }
                }

                if ( $maxRevId >= $revisionRow['rev_id'] ) {
                    $this->logger->debug(
                        '__METHOD__: Inserted revision {revid} but {table} has revisions up to {maxrevid}.'
                            . ' Trying to fix it.',
                        [
                            'revid' => $revisionRow['rev_id'],
                            'table' => $table,
                            'maxrevid' => $maxRevId,
                        ]
                    );

                    if ( !$dbw->lock( 'fix-for-T202032', __METHOD__ ) ) {
                        throw new MWException( 'Failed to get database lock for T202032' );
                    }
                    $fname = __METHOD__;
                    $dbw->onTransactionResolution( function ( $trigger, $dbw ) use ( $fname ) {
                        $dbw->unlock( 'fix-for-T202032', $fname );
                    } );

                    $dbw->delete( 'revision', [ 'rev_id' => $revisionRow['rev_id'] ], __METHOD__ );

                    // The locking here is mostly to make MySQL bypass the REPEATABLE-READ transaction
                    // isolation (weird MySQL "feature"). It does seem to block concurrent auto-incrementing
                    // inserts too, though, at least on MariaDB 10.1.29.
                    //
                    // Don't try to lock `revision` in this way, it'll deadlock if there are concurrent
                    // transactions in this code path thanks to the row lock from the original ->insert() above.
                    //
                    // And we have to use raw SQL to bypass the "aggregation used with a locking SELECT" warning
                    // that's for non-MySQL DBs.
                    $row1 = $dbw->query(
                        $dbw->selectSQLText( 'archive', [ 'v' => "MAX(ar_rev_id)" ], '', __METHOD__ ) . ' FOR UPDATE'
                    )->fetchObject();
                    if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW ) ) {
                        $row2 = $dbw->query(
                            $dbw->selectSQLText( 'slots', [ 'v' => "MAX(slot_revision_id)" ], '', __METHOD__ )
                                . ' FOR UPDATE'
                        )->fetchObject();
                    } else {
                        $row2 = null;
                    }
                    $maxRevId = max(
                        $maxRevId,
                        $row1 ? intval( $row1->v ) : 0,
                        $row2 ? intval( $row2->v ) : 0
                    );

                    // If we don't have SCHEMA_COMPAT_WRITE_NEW, all except the first of any concurrent
                    // transactions will throw a duplicate key error here. It doesn't seem worth trying
                    // to avoid that.
                    $revisionRow['rev_id'] = $maxRevId + 1;
                    $dbw->insert( 'revision', $revisionRow, __METHOD__ );
                }
            }
        }

        $commentCallback( $revisionRow['rev_id'] );
        $actorCallback( $revisionRow['rev_id'], $revisionRow );

        return $revisionRow;
    }

    private function getBaseRevisionRow(
        IDatabase $dbw,
        RevisionRecord $rev,
        Title $title,
        $parentId
    ) {
        // Record the edit in revisions
        $revisionRow = [
            'rev_page'       => $rev->getPageId(),
            'rev_parent_id'  => $parentId,
            'rev_minor_edit' => $rev->isMinor() ? 1 : 0,
            'rev_timestamp'  => $dbw->timestamp( $rev->getTimestamp() ),
            'rev_deleted'    => $rev->getVisibility(),
            'rev_len'        => $rev->getSize(),
            'rev_sha1'       => $rev->getSha1(),
        ];

        if ( $rev->getId() !== null ) {
            // Needed to restore revisions with their original ID
            $revisionRow['rev_id'] = $rev->getId();
        }

        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_OLD ) ) {
            // In non MCR mode this IF section will relate to the main slot
            $mainSlot = $rev->getSlot( SlotRecord::MAIN );
            $model = $mainSlot->getModel();
            $format = $mainSlot->getFormat();

            // MCR migration note: rev_content_model and rev_content_format will go away
            if ( $this->contentHandlerUseDB ) {
                $this->assertCrossWikiContentLoadingIsSafe();

                $defaultModel = ContentHandler::getDefaultModelFor( $title );
                $defaultFormat = ContentHandler::getForModelID( $defaultModel )->getDefaultFormat();

                $revisionRow['rev_content_model'] = ( $model === $defaultModel ) ? null : $model;
                $revisionRow['rev_content_format'] = ( $format === $defaultFormat ) ? null : $format;
            }
        }

        return $revisionRow;
    }

    private function storeContentBlob(
        SlotRecord $slot,
        Title $title,
        array $blobHints = []
    ) {
        $content = $slot->getContent();
        $format = $content->getDefaultFormat();
        $model = $content->getModel();

        $this->checkContent( $content, $title, $slot->getRole() );

        return $this->blobStore->storeBlob(
            $content->serialize( $format ),
            // These hints "leak" some information from the higher abstraction layer to
            // low level storage to allow for optimization.
            array_merge(
                $blobHints,
                [
                    BlobStore::DESIGNATION_HINT => 'page-content',
                    BlobStore::ROLE_HINT => $slot->getRole(),
                    BlobStore::SHA1_HINT => $slot->getSha1(),
                    BlobStore::MODEL_HINT => $model,
                    BlobStore::FORMAT_HINT => $format,
                ]
            )
        );
    }

    private function insertSlotRowOn( SlotRecord $slot, IDatabase $dbw, $revisionId, $contentId ) {
        $slotRow = [
            'slot_revision_id' => $revisionId,
            'slot_role_id' => $this->slotRoleStore->acquireId( $slot->getRole() ),
            'slot_content_id' => $contentId,
            // If the slot has a specific origin use that ID, otherwise use the ID of the revision
            // that we just inserted.
            'slot_origin' => $slot->hasOrigin() ? $slot->getOrigin() : $revisionId,
        ];
        $dbw->insert( 'slots', $slotRow, __METHOD__ );
    }

    private function insertContentRowOn( SlotRecord $slot, IDatabase $dbw, $blobAddress ) {
        $contentRow = [
            'content_size' => $slot->getSize(),
            'content_sha1' => $slot->getSha1(),
            'content_model' => $this->contentModelStore->acquireId( $slot->getModel() ),
            'content_address' => $blobAddress,
        ];
        $dbw->insert( 'content', $contentRow, __METHOD__ );
        return intval( $dbw->insertId() );
    }

    private function checkContent( Content $content, Title $title, $role ) {
        // Note: may return null for revisions that have not yet been inserted

        $model = $content->getModel();
        $format = $content->getDefaultFormat();
        $handler = $content->getContentHandler();

        $name = "$title";

        if ( !$handler->isSupportedFormat( $format ) ) {
            throw new MWException( "Can't use format $format with content model $model on $name" );
        }

        if ( !$this->contentHandlerUseDB ) {
            // if $wgContentHandlerUseDB is not set,
            // all revisions must use the default content model and format.

            $this->assertCrossWikiContentLoadingIsSafe();

            $roleHandler = $this->slotRoleRegistry->getRoleHandler( $role );
            $defaultModel = $roleHandler->getDefaultModel( $title );
            $defaultHandler = ContentHandler::getForModelID( $defaultModel );
            $defaultFormat = $defaultHandler->getDefaultFormat();

            if ( $model != $defaultModel ) {
                throw new MWException( "Can't save non-default content model with "
                    . "\$wgContentHandlerUseDB disabled: model is $model, "
                    . "default for $name is $defaultModel"
                );
            }

            if ( $format != $defaultFormat ) {
                throw new MWException( "Can't use non-default content format with "
                    . "\$wgContentHandlerUseDB disabled: format is $format, "
                    . "default for $name is $defaultFormat"
                );
            }
        }

        if ( !$content->isValid() ) {
            throw new MWException(
                "New content for $name is not valid! Content model is $model"
            );
        }
    }

    public function newNullRevision(
        IDatabase $dbw,
        Title $title,
        CommentStoreComment $comment,
        $minor,
        User $user
    ) {
        $this->checkDatabaseWikiId( $dbw );

        $pageId = $title->getArticleID();

        // T51581: Lock the page table row to ensure no other process
        // is adding a revision to the page at the same time.
        // Avoid locking extra tables, compare T191892.
        $pageLatest = $dbw->selectField(
            'page',
            'page_latest',
            [ 'page_id' => $pageId ],
            __METHOD__,
            [ 'FOR UPDATE' ]
        );

        if ( !$pageLatest ) {
            return null;
        }

        // Fetch the actual revision row from master, without locking all extra tables.
        $oldRevision = $this->loadRevisionFromConds(
            $dbw,
            [ 'rev_id' => intval( $pageLatest ) ],
            self::READ_LATEST,
            $title
        );

        if ( !$oldRevision ) {
            $msg = "Failed to load latest revision ID $pageLatest of page ID $pageId.";
            $this->logger->error(
                $msg,
                [ 'exception' => new RuntimeException( $msg ) ]
            );
            return null;
        }

        // Construct the new revision
        $timestamp = wfTimestampNow(); // TODO: use a callback, so we can override it for testing.
        $newRevision = MutableRevisionRecord::newFromParentRevision( $oldRevision );

        $newRevision->setComment( $comment );
        $newRevision->setUser( $user );
        $newRevision->setTimestamp( $timestamp );
        $newRevision->setMinorEdit( $minor );

        return $newRevision;
    }

    public function getRcIdIfUnpatrolled( RevisionRecord $rev ) {
        $rc = $this->getRecentChange( $rev );
        if ( $rc && $rc->getAttribute( 'rc_patrolled' ) == RecentChange::PRC_UNPATROLLED ) {
            return $rc->getAttribute( 'rc_id' );
        } else {
            return 0;
        }
    }

    public function getRecentChange( RevisionRecord $rev, $flags = 0 ) {
        list( $dbType, ) = DBAccessObjectUtils::getDBOptions( $flags );
        $db = $this->getDBConnection( $dbType );

        $userIdentity = $rev->getUser( RevisionRecord::RAW );

        if ( !$userIdentity ) {
            // If the revision has no user identity, chances are it never went
            // into the database, and doesn't have an RC entry.
            return null;
        }

        // TODO: Select by rc_this_oldid alone - but as of Nov 2017, there is no index on that!
        $actorWhere = $this->actorMigration->getWhere( $db, 'rc_user', $rev->getUser(), false );
        $rc = RecentChange::newFromConds(
            [
                $actorWhere['conds'],
                'rc_timestamp' => $db->timestamp( $rev->getTimestamp() ),
                'rc_this_oldid' => $rev->getId()
            ],
            __METHOD__,
            $dbType
        );

        $this->releaseDBConnection( $db );

        // XXX: cache this locally? Glue it to the RevisionRecord?
        return $rc;
    }

    private static function mapArchiveFields( $archiveRow ) {
        $fieldMap = [
            // keep with ar prefix:
            'ar_id'        => 'ar_id',

            // not the same suffix:
            'ar_page_id'        => 'rev_page',
            'ar_rev_id'         => 'rev_id',

            // same suffix:
            'ar_text_id'        => 'rev_text_id',
            'ar_timestamp'      => 'rev_timestamp',
            'ar_user_text'      => 'rev_user_text',
            'ar_user'           => 'rev_user',
            'ar_actor'          => 'rev_actor',
            'ar_minor_edit'     => 'rev_minor_edit',
            'ar_deleted'        => 'rev_deleted',
            'ar_len'            => 'rev_len',
            'ar_parent_id'      => 'rev_parent_id',
            'ar_sha1'           => 'rev_sha1',
            'ar_comment'        => 'rev_comment',
            'ar_comment_cid'    => 'rev_comment_cid',
            'ar_comment_id'     => 'rev_comment_id',
            'ar_comment_text'   => 'rev_comment_text',
            'ar_comment_data'   => 'rev_comment_data',
            'ar_comment_old'    => 'rev_comment_old',
            'ar_content_format' => 'rev_content_format',
            'ar_content_model'  => 'rev_content_model',
        ];

        $revRow = new stdClass();
        foreach ( $fieldMap as $arKey => $revKey ) {
            if ( property_exists( $archiveRow, $arKey ) ) {
                $revRow->$revKey = $archiveRow->$arKey;
            }
        }

        return $revRow;
    }

    private function emulateMainSlot_1_29( $row, $queryFlags, Title $title ) {
        $mainSlotRow = new stdClass();
        $mainSlotRow->role_name = SlotRecord::MAIN;
        $mainSlotRow->model_name = null;
        $mainSlotRow->slot_revision_id = null;
        $mainSlotRow->slot_content_id = null;
        $mainSlotRow->content_address = null;

        $content = null;
        $blobData = null;
        $blobFlags = null;

        if ( is_object( $row ) ) {
            if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_NEW ) ) {
                // Don't emulate from a row when using the new schema.
                // Emulating from an array is still OK.
                throw new LogicException( 'Can\'t emulate the main slot when using MCR schema.' );
            }

            // archive row
            if ( !isset( $row->rev_id ) && ( isset( $row->ar_user ) || isset( $row->ar_actor ) ) ) {
                $row = $this->mapArchiveFields( $row );
            }

            if ( isset( $row->rev_text_id ) && $row->rev_text_id > 0 ) {
                $mainSlotRow->content_address = SqlBlobStore::makeAddressFromTextId(
                    $row->rev_text_id
                );
            }

            // This is used by null-revisions
            $mainSlotRow->slot_origin = isset( $row->slot_origin )
                ? intval( $row->slot_origin )
                : null;

            if ( isset( $row->old_text ) ) {
                // this happens when the text-table gets joined directly, in the pre-1.30 schema
                $blobData = isset( $row->old_text ) ? strval( $row->old_text ) : null;
                // Check against selects that might have not included old_flags
                if ( !property_exists( $row, 'old_flags' ) ) {
                    throw new InvalidArgumentException( 'old_flags was not set in $row' );
                }
                $blobFlags = $row->old_flags ?? '';
            }

            $mainSlotRow->slot_revision_id = intval( $row->rev_id );

            $mainSlotRow->content_size = isset( $row->rev_len ) ? intval( $row->rev_len ) : null;
            $mainSlotRow->content_sha1 = isset( $row->rev_sha1 ) ? strval( $row->rev_sha1 ) : null;
            $mainSlotRow->model_name = isset( $row->rev_content_model )
                ? strval( $row->rev_content_model )
                : null;
            // XXX: in the future, we'll probably always use the default format, and drop content_format
            $mainSlotRow->format_name = isset( $row->rev_content_format )
                ? strval( $row->rev_content_format )
                : null;

            if ( isset( $row->rev_text_id ) && intval( $row->rev_text_id ) > 0 ) {
                // Overwritten below for SCHEMA_COMPAT_WRITE_NEW
                $mainSlotRow->slot_content_id
                    = $this->emulateContentId( intval( $row->rev_text_id ) );
            }
        } elseif ( is_array( $row ) ) {
            $mainSlotRow->slot_revision_id = isset( $row['id'] ) ? intval( $row['id'] ) : null;

            $mainSlotRow->slot_origin = isset( $row['slot_origin'] )
                ? intval( $row['slot_origin'] )
                : null;
            $mainSlotRow->content_address = isset( $row['text_id'] )
                ? SqlBlobStore::makeAddressFromTextId( intval( $row['text_id'] ) )
                : null;
            $mainSlotRow->content_size = isset( $row['len'] ) ? intval( $row['len'] ) : null;
            $mainSlotRow->content_sha1 = isset( $row['sha1'] ) ? strval( $row['sha1'] ) : null;

            $mainSlotRow->model_name = isset( $row['content_model'] )
                ? strval( $row['content_model'] ) : null;  // XXX: must be a string!
            // XXX: in the future, we'll probably always use the default format, and drop content_format
            $mainSlotRow->format_name = isset( $row['content_format'] )
                ? strval( $row['content_format'] ) : null;
            $blobData = isset( $row['text'] ) ? rtrim( strval( $row['text'] ) ) : null;
            // XXX: If the flags field is not set then $blobFlags should be null so that no
            // decoding will happen. An empty string will result in default decodings.
            $blobFlags = isset( $row['flags'] ) ? trim( strval( $row['flags'] ) ) : null;

            // if we have a Content object, override mText and mContentModel
            if ( !empty( $row['content'] ) ) {
                if ( !( $row['content'] instanceof Content ) ) {
                    throw new MWException( 'content field must contain a Content object.' );
                }

                $content = $row['content'];
                $handler = $content->getContentHandler();

                $mainSlotRow->model_name = $content->getModel();

                // XXX: in the future, we'll probably always use the default format.
                if ( $mainSlotRow->format_name === null ) {
                    $mainSlotRow->format_name = $handler->getDefaultFormat();
                }
            }

            if ( isset( $row['text_id'] ) && intval( $row['text_id'] ) > 0 ) {
                // Overwritten below for SCHEMA_COMPAT_WRITE_NEW
                $mainSlotRow->slot_content_id
                    = $this->emulateContentId( intval( $row['text_id'] ) );
            }
        } else {
            throw new MWException( 'Revision constructor passed invalid row format.' );
        }

        // With the old schema, the content changes with every revision,
        // except for null-revisions.
        if ( !isset( $mainSlotRow->slot_origin ) ) {
            $mainSlotRow->slot_origin = $mainSlotRow->slot_revision_id;
        }

        if ( $mainSlotRow->model_name === null ) {
            $mainSlotRow->model_name = function ( SlotRecord $slot ) use ( $title ) {
                $this->assertCrossWikiContentLoadingIsSafe();

                return $this->slotRoleRegistry->getRoleHandler( $slot->getRole() )
                    ->getDefaultModel( $title );
            };
        }

        if ( !$content ) {
            // XXX: We should perhaps fail if $blobData is null and $mainSlotRow->content_address
            // is missing, but "empty revisions" with no content are used in some edge cases.

            $content = function ( SlotRecord $slot )
                use ( $blobData, $blobFlags, $queryFlags, $mainSlotRow )
            {
                return $this->loadSlotContent(
                    $slot,
                    $blobData,
                    $blobFlags,
                    $mainSlotRow->format_name,
                    $queryFlags
                );
            };
        }

        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW ) ) {
            // NOTE: this callback will be looped through RevisionSlot::newInherited(), allowing
            // the inherited slot to have the same content_id as the original slot. In that case,
            // $slot will be the inherited slot, while $mainSlotRow still refers to the original slot.
            $mainSlotRow->slot_content_id =
                function ( SlotRecord $slot ) use ( $queryFlags, $mainSlotRow ) {
                    $db = $this->getDBConnectionRefForQueryFlags( $queryFlags );
                    return $this->findSlotContentId( $db, $mainSlotRow->slot_revision_id, SlotRecord::MAIN );
                };
        }

        return new SlotRecord( $mainSlotRow, $content );
    }

    private function emulateContentId( $textId ) {
        // Return a negative number to ensure the ID is distinct from any real content IDs
        // that will be assigned in SCHEMA_COMPAT_WRITE_NEW mode and read in SCHEMA_COMPAT_READ_NEW
        // mode.
        return -$textId;
    }

    private function loadSlotContent(
        SlotRecord $slot,
        $blobData = null,
        $blobFlags = null,
        $blobFormat = null,
        $queryFlags = 0
    ) {
        if ( $blobData !== null ) {
            Assert::parameterType( 'string', $blobData, '$blobData' );
            Assert::parameterType( 'string|null', $blobFlags, '$blobFlags' );

            $cacheKey = $slot->hasAddress() ? $slot->getAddress() : null;

            if ( $blobFlags === null ) {
                // No blob flags, so use the blob verbatim.
                $data = $blobData;
            } else {
                $data = $this->blobStore->expandBlob( $blobData, $blobFlags, $cacheKey );
                if ( $data === false ) {
                    throw new RevisionAccessException(
                        "Failed to expand blob data using flags $blobFlags (key: $cacheKey)"
                    );
                }
            }

        } else {
            $address = $slot->getAddress();
            try {
                $data = $this->blobStore->getBlob( $address, $queryFlags );
            } catch ( BlobAccessException $e ) {
                throw new RevisionAccessException(
                    "Failed to load data blob from $address: " . $e->getMessage(), 0, $e
                );
            }
        }

        // Unserialize content
        $handler = ContentHandler::getForModelID( $slot->getModel() );

        $content = $handler->unserializeContent( $data, $blobFormat );
        return $content;
    }

    public function getRevisionById( $id, $flags = 0 ) {
        return $this->newRevisionFromConds( [ 'rev_id' => intval( $id ) ], $flags );
    }

    public function getRevisionByTitle( LinkTarget $linkTarget, $revId = 0, $flags = 0 ) {
        // TODO should not require Title in future (T206498)
        $title = Title::newFromLinkTarget( $linkTarget );
        $conds = [
            'page_namespace' => $title->getNamespace(),
            'page_title' => $title->getDBkey()
        ];
        if ( $revId ) {
            // Use the specified revision ID.
            // Note that we use newRevisionFromConds here because we want to retry
            // and fall back to master if the page is not found on a replica.
            // Since the caller supplied a revision ID, we are pretty sure the revision is
            // supposed to exist, so we should try hard to find it.
            $conds['rev_id'] = $revId;
            return $this->newRevisionFromConds( $conds, $flags, $title );
        } else {
            // Use a join to get the latest revision.
            // Note that we don't use newRevisionFromConds here because we don't want to retry
            // and fall back to master. The assumption is that we only want to force the fallback
            // if we are quite sure the revision exists because the caller supplied a revision ID.
            // If the page isn't found at all on a replica, it probably simply does not exist.
            $db = $this->getDBConnectionRefForQueryFlags( $flags );

            $conds[] = 'rev_id=page_latest';
            $rev = $this->loadRevisionFromConds( $db, $conds, $flags, $title );

            return $rev;
        }
    }

    public function getRevisionByPageId( $pageId, $revId = 0, $flags = 0 ) {
        $conds = [ 'page_id' => $pageId ];
        if ( $revId ) {
            // Use the specified revision ID.
            // Note that we use newRevisionFromConds here because we want to retry
            // and fall back to master if the page is not found on a replica.
            // Since the caller supplied a revision ID, we are pretty sure the revision is
            // supposed to exist, so we should try hard to find it.
            $conds['rev_id'] = $revId;
            return $this->newRevisionFromConds( $conds, $flags );
        } else {
            // Use a join to get the latest revision.
            // Note that we don't use newRevisionFromConds here because we don't want to retry
            // and fall back to master. The assumption is that we only want to force the fallback
            // if we are quite sure the revision exists because the caller supplied a revision ID.
            // If the page isn't found at all on a replica, it probably simply does not exist.
            $db = $this->getDBConnectionRefForQueryFlags( $flags );

            $conds[] = 'rev_id=page_latest';
            $rev = $this->loadRevisionFromConds( $db, $conds, $flags );

            return $rev;
        }
    }

    public function getRevisionByTimestamp( $title, $timestamp ) {
        $db = $this->getDBConnection( DB_REPLICA );
        return $this->newRevisionFromConds(
            [
                'rev_timestamp' => $db->timestamp( $timestamp ),
                'page_namespace' => $title->getNamespace(),
                'page_title' => $title->getDBkey()
            ],
            0,
            $title
        );
    }

    private function loadSlotRecords( $revId, $queryFlags ) {
        $revQuery = self::getSlotsQueryInfo( [ 'content' ] );

        list( $dbMode, $dbOptions ) = DBAccessObjectUtils::getDBOptions( $queryFlags );
        $db = $this->getDBConnectionRef( $dbMode );

        $res = $db->select(
            $revQuery['tables'],
            $revQuery['fields'],
            [
                'slot_revision_id' => $revId,
            ],
            __METHOD__,
            $dbOptions,
            $revQuery['joins']
        );

        $slots = [];

        foreach ( $res as $row ) {
            // resolve role names and model names from in-memory cache, instead of joining.
            $row->role_name = $this->slotRoleStore->getName( (int)$row->slot_role_id );
            $row->model_name = $this->contentModelStore->getName( (int)$row->content_model );

            $contentCallback = function ( SlotRecord $slot ) use ( $queryFlags ) {
                return $this->loadSlotContent( $slot, null, null, null, $queryFlags );
            };

            $slots[$row->role_name] = new SlotRecord( $row, $contentCallback );
        }

        if ( !isset( $slots[SlotRecord::MAIN] ) ) {
            throw new RevisionAccessException(
                'Main slot of revision ' . $revId . ' not found in database!'
            );
        }

        return $slots;
    }

    private function newRevisionSlots(
        $revId,
        $revisionRow,
        $queryFlags,
        Title $title
    ) {
        if ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_NEW ) ) {
            $mainSlot = $this->emulateMainSlot_1_29( $revisionRow, $queryFlags, $title );
            // @phan-suppress-next-line PhanTypeInvalidCallableArraySize false positive
            $slots = new RevisionSlots( [ SlotRecord::MAIN => $mainSlot ] );
        } else {
            // XXX: do we need the same kind of caching here
            // that getKnownCurrentRevision uses (if $revId == page_latest?)

            $slots = new RevisionSlots( function () use( $revId, $queryFlags ) {
                return $this->loadSlotRecords( $revId, $queryFlags );
            } );
        }

        return $slots;
    }

    public function newRevisionFromArchiveRow(
        $row,
        $queryFlags = 0,
        Title $title = null,
        array $overrides = []
    ) {
        Assert::parameterType( 'object', $row, '$row' );

        // check second argument, since Revision::newFromArchiveRow had $overrides in that spot.
        Assert::parameterType( 'integer', $queryFlags, '$queryFlags' );

        if ( !$title && isset( $overrides['title'] ) ) {
            if ( !( $overrides['title'] instanceof Title ) ) {
                throw new MWException( 'title field override must contain a Title object.' );
            }

            $title = $overrides['title'];
        }

        if ( !isset( $title ) ) {
            if ( isset( $row->ar_namespace ) && isset( $row->ar_title ) ) {
                $title = Title::makeTitle( $row->ar_namespace, $row->ar_title );
            } else {
                throw new InvalidArgumentException(
                    'A Title or ar_namespace and ar_title must be given'
                );
            }
        }

        foreach ( $overrides as $key => $value ) {
            $field = "ar_$key";
            $row->$field = $value;
        }

        try {
            $user = User::newFromAnyId(
                $row->ar_user ?? null,
                $row->ar_user_text ?? null,
                $row->ar_actor ?? null,
                $this->wikiId
            );
        } catch ( InvalidArgumentException $ex ) {
            wfWarn( __METHOD__ . ': ' . $title->getPrefixedDBkey() . ': ' . $ex->getMessage() );
            $user = new UserIdentityValue( 0, 'Unknown user', 0 );
        }

        $db = $this->getDBConnectionRefForQueryFlags( $queryFlags );
        // Legacy because $row may have come from self::selectFields()
        $comment = $this->commentStore->getCommentLegacy( $db, 'ar_comment', $row, true );

        $slots = $this->newRevisionSlots( $row->ar_rev_id, $row, $queryFlags, $title );

        return new RevisionArchiveRecord( $title, $user, $comment, $row, $slots, $this->wikiId );
    }

    public function newRevisionFromRow(
        $row,
        $queryFlags = 0,
        Title $title = null,
        $fromCache = false
    ) {
        Assert::parameterType( 'object', $row, '$row' );

        if ( !$title ) {
            $pageId = $row->rev_page ?? 0; // XXX: also check page_id?
            $revId = $row->rev_id ?? 0;

            $title = $this->getTitle( $pageId, $revId, $queryFlags );
        }

        if ( !isset( $row->page_latest ) ) {
            $row->page_latest = $title->getLatestRevID();
            if ( $row->page_latest === 0 && $title->exists() ) {
                wfWarn( 'Encountered title object in limbo: ID ' . $title->getArticleID() );
            }
        }

        try {
            $user = User::newFromAnyId(
                $row->rev_user ?? null,
                $row->rev_user_text ?? null,
                $row->rev_actor ?? null,
                $this->wikiId
            );
        } catch ( InvalidArgumentException $ex ) {
            wfWarn( __METHOD__ . ': ' . $title->getPrefixedDBkey() . ': ' . $ex->getMessage() );
            $user = new UserIdentityValue( 0, 'Unknown user', 0 );
        }

        $db = $this->getDBConnectionRefForQueryFlags( $queryFlags );
        // Legacy because $row may have come from self::selectFields()
        $comment = $this->commentStore->getCommentLegacy( $db, 'rev_comment', $row, true );

        $slots = $this->newRevisionSlots( $row->rev_id, $row, $queryFlags, $title );

        // If this is a cached row, instantiate a cache-aware revision class to avoid stale data.
        if ( $fromCache ) {
            $rev = new RevisionStoreCacheRecord(
                function ( $revId ) use ( $queryFlags ) {
                    $db = $this->getDBConnectionRefForQueryFlags( $queryFlags );
                    return $this->fetchRevisionRowFromConds(
                        $db,
                        [ 'rev_id' => intval( $revId ) ]
                    );
                },
                $title, $user, $comment, $row, $slots, $this->wikiId
            );
        } else {
            $rev = new RevisionStoreRecord(
                $title, $user, $comment, $row, $slots, $this->wikiId );
        }
        return $rev;
    }

    public function newMutableRevisionFromArray(
        array $fields,
        $queryFlags = 0,
        Title $title = null
    ) {
        if ( !$title && isset( $fields['title'] ) ) {
            if ( !( $fields['title'] instanceof Title ) ) {
                throw new MWException( 'title field must contain a Title object.' );
            }

            $title = $fields['title'];
        }

        if ( !$title ) {
            $pageId = $fields['page'] ?? 0;
            $revId = $fields['id'] ?? 0;

            $title = $this->getTitle( $pageId, $revId, $queryFlags );
        }

        if ( !isset( $fields['page'] ) ) {
            $fields['page'] = $title->getArticleID( $queryFlags );
        }

        // if we have a content object, use it to set the model and type
        if ( !empty( $fields['content'] ) && !( $fields['content'] instanceof Content )
            && !is_array( $fields['content'] )
        ) {
            throw new MWException(
                'content field must contain a Content object or an array of Content objects.'
            );
        }

        if ( !empty( $fields['text_id'] ) ) {
            if ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_OLD ) ) {
                throw new MWException( "The text_id field is only available in the pre-MCR schema" );
            }

            if ( !empty( $fields['content'] ) ) {
                throw new MWException(
                    "Text already stored in external store (id {$fields['text_id']}), " .
                    "can't specify content object"
                );
            }
        }

        if (
            isset( $fields['comment'] )
            && !( $fields['comment'] instanceof CommentStoreComment )
        ) {
            $commentData = $fields['comment_data'] ?? null;

            if ( $fields['comment'] instanceof Message ) {
                $fields['comment'] = CommentStoreComment::newUnsavedComment(
                    $fields['comment'],
                    $commentData
                );
            } else {
                $commentText = trim( strval( $fields['comment'] ) );
                $fields['comment'] = CommentStoreComment::newUnsavedComment(
                    $commentText,
                    $commentData
                );
            }
        }

        $revision = new MutableRevisionRecord( $title, $this->wikiId );
        $this->initializeMutableRevisionFromArray( $revision, $fields );

        if ( isset( $fields['content'] ) && is_array( $fields['content'] ) ) {
            // @phan-suppress-next-line PhanTypeNoPropertiesForeach
            foreach ( $fields['content'] as $role => $content ) {
                $revision->setContent( $role, $content );
            }
        } else {
            $mainSlot = $this->emulateMainSlot_1_29( $fields, $queryFlags, $title );
            $revision->setSlot( $mainSlot );
        }

        return $revision;
    }

    private function initializeMutableRevisionFromArray(
        MutableRevisionRecord $record,
        array $fields
    ) {
        $user = null;

        // If a user is passed in, use it if possible. We cannot use a user from a
        // remote wiki with unsuppressed ids, due to issues described in T222212.
        if ( isset( $fields['user'] ) &&
            ( $fields['user'] instanceof UserIdentity ) &&
            ( $this->wikiId === false ||
                ( !$fields['user']->getId() && !$fields['user']->getActorId() ) )
        ) {
            $user = $fields['user'];
        } else {
            try {
                $user = User::newFromAnyId(
                    $fields['user'] ?? null,
                    $fields['user_text'] ?? null,
                    $fields['actor'] ?? null,
                    $this->wikiId
                );
            } catch ( InvalidArgumentException $ex ) {
                $user = null;
            }
        }

        if ( $user ) {
            $record->setUser( $user );
        }

        $timestamp = isset( $fields['timestamp'] )
            ? strval( $fields['timestamp'] )
            : wfTimestampNow(); // TODO: use a callback, so we can override it for testing.

        $record->setTimestamp( $timestamp );

        if ( isset( $fields['page'] ) ) {
            $record->setPageId( intval( $fields['page'] ) );
        }

        if ( isset( $fields['id'] ) ) {
            $record->setId( intval( $fields['id'] ) );
        }
        if ( isset( $fields['parent_id'] ) ) {
            $record->setParentId( intval( $fields['parent_id'] ) );
        }

        if ( isset( $fields['sha1'] ) ) {
            $record->setSha1( $fields['sha1'] );
        }
        if ( isset( $fields['size'] ) ) {
            $record->setSize( intval( $fields['size'] ) );
        }

        if ( isset( $fields['minor_edit'] ) ) {
            $record->setMinorEdit( intval( $fields['minor_edit'] ) !== 0 );
        }
        if ( isset( $fields['deleted'] ) ) {
            $record->setVisibility( intval( $fields['deleted'] ) );
        }

        if ( isset( $fields['comment'] ) ) {
            Assert::parameterType(
                CommentStoreComment::class,
                $fields['comment'],
                '$row[\'comment\']'
            );
            $record->setComment( $fields['comment'] );
        }
    }

    public function loadRevisionFromId( IDatabase $db, $id ) {
        return $this->loadRevisionFromConds( $db, [ 'rev_id' => intval( $id ) ] );
    }

    public function loadRevisionFromPageId( IDatabase $db, $pageid, $id = 0 ) {
        $conds = [ 'rev_page' => intval( $pageid ), 'page_id' => intval( $pageid ) ];
        if ( $id ) {
            $conds['rev_id'] = intval( $id );
        } else {
            $conds[] = 'rev_id=page_latest';
        }
        return $this->loadRevisionFromConds( $db, $conds );
    }

    public function loadRevisionFromTitle( IDatabase $db, $title, $id = 0 ) {
        if ( $id ) {
            $matchId = intval( $id );
        } else {
            $matchId = 'page_latest';
        }

        return $this->loadRevisionFromConds(
            $db,
            [
                "rev_id=$matchId",
                'page_namespace' => $title->getNamespace(),
                'page_title' => $title->getDBkey()
            ],
            0,
            $title
        );
    }

    public function loadRevisionFromTimestamp( IDatabase $db, $title, $timestamp ) {
        return $this->loadRevisionFromConds( $db,
            [
                'rev_timestamp' => $db->timestamp( $timestamp ),
                'page_namespace' => $title->getNamespace(),
                'page_title' => $title->getDBkey()
            ],
            0,
            $title
        );
    }

    private function newRevisionFromConds( $conditions, $flags = 0, Title $title = null ) {
        $db = $this->getDBConnectionRefForQueryFlags( $flags );
        $rev = $this->loadRevisionFromConds( $db, $conditions, $flags, $title );

        $lb = $this->getDBLoadBalancer();

        // Make sure new pending/committed revision are visibile later on
        // within web requests to certain avoid bugs like T93866 and T94407.
        if ( !$rev
            && !( $flags & self::READ_LATEST )
            && $lb->getServerCount() > 1
            && $lb->hasOrMadeRecentMasterChanges()
        ) {
            $flags = self::READ_LATEST;
            $dbw = $this->getDBConnection( DB_MASTER );
            $rev = $this->loadRevisionFromConds( $dbw, $conditions, $flags, $title );
            $this->releaseDBConnection( $dbw );
        }

        return $rev;
    }

    private function loadRevisionFromConds(
        IDatabase $db,
        $conditions,
        $flags = 0,
        Title $title = null
    ) {
        $row = $this->fetchRevisionRowFromConds( $db, $conditions, $flags );
        if ( $row ) {
            $rev = $this->newRevisionFromRow( $row, $flags, $title );

            return $rev;
        }

        return null;
    }

    private function checkDatabaseWikiId( IDatabase $db ) {
        $storeWiki = $this->wikiId;
        $dbWiki = $db->getDomainID();

        if ( $dbWiki === $storeWiki ) {
            return;
        }

        $storeWiki = $storeWiki ?: $this->loadBalancer->getLocalDomainID();
        // @FIXME: when would getDomainID() be false here?
        $dbWiki = $dbWiki ?: wfWikiID();

        if ( $dbWiki === $storeWiki ) {
            return;
        }

        // HACK: counteract encoding imposed by DatabaseDomain
        $storeWiki = str_replace( '?h', '-', $storeWiki );
        $dbWiki = str_replace( '?h', '-', $dbWiki );

        if ( $dbWiki === $storeWiki ) {
            return;
        }

        throw new MWException( "RevisionStore for $storeWiki "
            . "cannot be used with a DB connection for $dbWiki" );
    }

    private function fetchRevisionRowFromConds( IDatabase $db, $conditions, $flags = 0 ) {
        $this->checkDatabaseWikiId( $db );

        $revQuery = $this->getQueryInfo( [ 'page', 'user' ] );
        $options = [];
        if ( ( $flags & self::READ_LOCKING ) == self::READ_LOCKING ) {
            $options[] = 'FOR UPDATE';
        }
        return $db->selectRow(
            $revQuery['tables'],
            $revQuery['fields'],
            $conditions,
            __METHOD__,
            $options,
            $revQuery['joins']
        );
    }

    private function findSlotContentId( IDatabase $db, $revId, $role ) {
        if ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_NEW ) ) {
            return null;
        }

        try {
            $roleId = $this->slotRoleStore->getId( $role );
            $conditions = [
                'slot_revision_id' => $revId,
                'slot_role_id' => $roleId,
            ];

            $contentId = $db->selectField( 'slots', 'slot_content_id', $conditions, __METHOD__ );

            return $contentId ?: null;
        } catch ( NameTableAccessException $ex ) {
            // If the role is missing from the slot_roles table,
            // the corresponding row in slots cannot exist.
            return null;
        }
    }

    public function getQueryInfo( $options = [] ) {
        $ret = [
            'tables' => [],
            'fields' => [],
            'joins'  => [],
        ];

        $ret['tables'][] = 'revision';
        $ret['fields'] = array_merge( $ret['fields'], [
            'rev_id',
            'rev_page',
            'rev_timestamp',
            'rev_minor_edit',
            'rev_deleted',
            'rev_len',
            'rev_parent_id',
            'rev_sha1',
        ] );

        $commentQuery = $this->commentStore->getJoin( 'rev_comment' );
        $ret['tables'] = array_merge( $ret['tables'], $commentQuery['tables'] );
        $ret['fields'] = array_merge( $ret['fields'], $commentQuery['fields'] );
        $ret['joins'] = array_merge( $ret['joins'], $commentQuery['joins'] );

        $actorQuery = $this->actorMigration->getJoin( 'rev_user' );
        $ret['tables'] = array_merge( $ret['tables'], $actorQuery['tables'] );
        $ret['fields'] = array_merge( $ret['fields'], $actorQuery['fields'] );
        $ret['joins'] = array_merge( $ret['joins'], $actorQuery['joins'] );

        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_OLD ) ) {
            $ret['fields'][] = 'rev_text_id';

            if ( $this->contentHandlerUseDB ) {
                $ret['fields'][] = 'rev_content_format';
                $ret['fields'][] = 'rev_content_model';
            }
        }

        if ( in_array( 'page', $options, true ) ) {
            $ret['tables'][] = 'page';
            $ret['fields'] = array_merge( $ret['fields'], [
                'page_namespace',
                'page_title',
                'page_id',
                'page_latest',
                'page_is_redirect',
                'page_len',
            ] );
            $ret['joins']['page'] = [ 'JOIN', [ 'page_id = rev_page' ] ];
        }

        if ( in_array( 'user', $options, true ) ) {
            $ret['tables'][] = 'user';
            $ret['fields'] = array_merge( $ret['fields'], [
                'user_name',
            ] );
            $u = $actorQuery['fields']['rev_user'];
            $ret['joins']['user'] = [ 'LEFT JOIN', [ "$u != 0", "user_id = $u" ] ];
        }

        if ( in_array( 'text', $options, true ) ) {
            if ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_WRITE_OLD ) ) {
                throw new InvalidArgumentException( 'text table can no longer be joined directly' );
            } elseif ( !$this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_OLD ) ) {
                // NOTE: even when this class is set to not read from the old schema, callers
                // should still be able to join against the text table, as long as we are still
                // writing the old schema for compatibility.
                // TODO: This should trigger a deprecation warning eventually (T200918), but not
                // before all known usages are removed (see T198341 and T201164).
                // wfDeprecated( __METHOD__ . ' with `text` option', '1.32' );
            }

            $ret['tables'][] = 'text';
            $ret['fields'] = array_merge( $ret['fields'], [
                'old_text',
                'old_flags'
            ] );
            $ret['joins']['text'] = [ 'JOIN', [ 'rev_text_id=old_id' ] ];
        }

        return $ret;
    }

    public function getSlotsQueryInfo( $options = [] ) {
        $ret = [
            'tables' => [],
            'fields' => [],
            'joins'  => [],
        ];

        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_OLD ) ) {
            $db = $this->getDBConnectionRef( DB_REPLICA );
            $ret['tables']['slots'] = 'revision';

            $ret['fields']['slot_revision_id'] = 'slots.rev_id';
            $ret['fields']['slot_content_id'] = 'NULL';
            $ret['fields']['slot_origin'] = 'slots.rev_id';
            $ret['fields']['role_name'] = $db->addQuotes( SlotRecord::MAIN );

            if ( in_array( 'content', $options, true ) ) {
                $ret['fields']['content_size'] = 'slots.rev_len';
                $ret['fields']['content_sha1'] = 'slots.rev_sha1';
                $ret['fields']['content_address']
                    = $db->buildConcat( [ $db->addQuotes( 'tt:' ), 'slots.rev_text_id' ] );

                if ( $this->contentHandlerUseDB ) {
                    $ret['fields']['model_name'] = 'slots.rev_content_model';
                } else {
                    $ret['fields']['model_name'] = 'NULL';
                }
            }
        } else {
            $ret['tables'][] = 'slots';
            $ret['fields'] = array_merge( $ret['fields'], [
                'slot_revision_id',
                'slot_content_id',
                'slot_origin',
                'slot_role_id',
            ] );

            if ( in_array( 'role', $options, true ) ) {
                // Use left join to attach role name, so we still find the revision row even
                // if the role name is missing. This triggers a more obvious failure mode.
                $ret['tables'][] = 'slot_roles';
                $ret['joins']['slot_roles'] = [ 'LEFT JOIN', [ 'slot_role_id = role_id' ] ];
                $ret['fields'][] = 'role_name';
            }

            if ( in_array( 'content', $options, true ) ) {
                $ret['tables'][] = 'content';
                $ret['fields'] = array_merge( $ret['fields'], [
                    'content_size',
                    'content_sha1',
                    'content_address',
                    'content_model',
                ] );
                $ret['joins']['content'] = [ 'JOIN', [ 'slot_content_id = content_id' ] ];

                if ( in_array( 'model', $options, true ) ) {
                    // Use left join to attach model name, so we still find the revision row even
                    // if the model name is missing. This triggers a more obvious failure mode.
                    $ret['tables'][] = 'content_models';
                    $ret['joins']['content_models'] = [ 'LEFT JOIN', [ 'content_model = model_id' ] ];
                    $ret['fields'][] = 'model_name';
                }

            }
        }

        return $ret;
    }

    public function getArchiveQueryInfo() {
        $commentQuery = $this->commentStore->getJoin( 'ar_comment' );
        $actorQuery = $this->actorMigration->getJoin( 'ar_user' );
        $ret = [
            'tables' => [ 'archive' ] + $commentQuery['tables'] + $actorQuery['tables'],
            'fields' => [
                    'ar_id',
                    'ar_page_id',
                    'ar_namespace',
                    'ar_title',
                    'ar_rev_id',
                    'ar_timestamp',
                    'ar_minor_edit',
                    'ar_deleted',
                    'ar_len',
                    'ar_parent_id',
                    'ar_sha1',
                ] + $commentQuery['fields'] + $actorQuery['fields'],
            'joins' => $commentQuery['joins'] + $actorQuery['joins'],
        ];

        if ( $this->hasMcrSchemaFlags( SCHEMA_COMPAT_READ_OLD ) ) {
            $ret['fields'][] = 'ar_text_id';

            if ( $this->contentHandlerUseDB ) {
                $ret['fields'][] = 'ar_content_format';
                $ret['fields'][] = 'ar_content_model';
            }
        }

        return $ret;
    }

    public function getRevisionSizes( array $revIds ) {
        return $this->listRevisionSizes( $this->getDBConnection( DB_REPLICA ), $revIds );
    }

    public function listRevisionSizes( IDatabase $db, array $revIds ) {
        $this->checkDatabaseWikiId( $db );

        $revLens = [];
        if ( !$revIds ) {
            return $revLens; // empty
        }

        $res = $db->select(
            'revision',
            [ 'rev_id', 'rev_len' ],
            [ 'rev_id' => $revIds ],
            __METHOD__
        );

        foreach ( $res as $row ) {
            $revLens[$row->rev_id] = intval( $row->rev_len );
        }

        return $revLens;
    }

    private function getRelativeRevision( RevisionRecord $rev, $flags, $dir ) {
        $op = $dir === 'next' ? '>' : '<';
        $sort = $dir === 'next' ? 'ASC' : 'DESC';

        if ( !$rev->getId() || !$rev->getPageId() ) {
            // revision is unsaved or otherwise incomplete
            return null;
        }

        if ( $rev instanceof RevisionArchiveRecord ) {
            // revision is deleted, so it's not part of the page history
            return null;
        }

        list( $dbType, ) = DBAccessObjectUtils::getDBOptions( $flags );
        $db = $this->getDBConnection( $dbType, [ 'contributions' ] );

        $ts = $this->getTimestampFromId( $rev->getId(), $flags );
        if ( $ts === false ) {
            // XXX Should this be moved into getTimestampFromId?
            $ts = $db->selectField( 'archive', 'ar_timestamp',
                [ 'ar_rev_id' => $rev->getId() ], __METHOD__ );
            if ( $ts === false ) {
                // XXX Is this reachable? How can we have a page id but no timestamp?
                return null;
            }
        }
        $ts = $db->addQuotes( $db->timestamp( $ts ) );

        $revId = $db->selectField( 'revision', 'rev_id',
            [
                'rev_page' => $rev->getPageId(),
                "rev_timestamp $op $ts OR (rev_timestamp = $ts AND rev_id $op {$rev->getId()})"
            ],
            __METHOD__,
            [
                'ORDER BY' => "rev_timestamp $sort, rev_id $sort",
                'IGNORE INDEX' => 'rev_timestamp', // Probably needed for T159319
            ]
        );

        if ( $revId === false ) {
            return null;
        }

        return $this->getRevisionById( intval( $revId ) );
    }

    public function getPreviousRevision( RevisionRecord $rev, $flags = 0 ) {
        if ( $flags instanceof Title ) {
            // Old calling convention, we don't use Title here anymore
            wfDeprecated( __METHOD__ . ' with Title', '1.34' );
            $flags = 0;
        }

        return $this->getRelativeRevision( $rev, $flags, 'prev' );
    }

    public function getNextRevision( RevisionRecord $rev, $flags = 0 ) {
        if ( $flags instanceof Title ) {
            // Old calling convention, we don't use Title here anymore
            wfDeprecated( __METHOD__ . ' with Title', '1.34' );
            $flags = 0;
        }

        return $this->getRelativeRevision( $rev, $flags, 'next' );
    }

    private function getPreviousRevisionId( IDatabase $db, RevisionRecord $rev ) {
        $this->checkDatabaseWikiId( $db );

        if ( $rev->getPageId() === null ) {
            return 0;
        }
        # Use page_latest if ID is not given
        if ( !$rev->getId() ) {
            $prevId = $db->selectField(
                'page', 'page_latest',
                [ 'page_id' => $rev->getPageId() ],
                __METHOD__
            );
        } else {
            $prevId = $db->selectField(
                'revision', 'rev_id',
                [ 'rev_page' => $rev->getPageId(), 'rev_id < ' . $rev->getId() ],
                __METHOD__,
                [ 'ORDER BY' => 'rev_id DESC' ]
            );
        }
        return intval( $prevId );
    }

    public function getTimestampFromId( $id, $flags = 0 ) {
        if ( $id instanceof Title ) {
            // Old deprecated calling convention supported for backwards compatibility
            $id = $flags;
            $flags = func_num_args() > 2 ? func_get_arg( 2 ) : 0;
        }
        $db = $this->getDBConnectionRefForQueryFlags( $flags );

        $timestamp =
            $db->selectField( 'revision', 'rev_timestamp', [ 'rev_id' => $id ], __METHOD__ );

        return ( $timestamp !== false ) ? wfTimestamp( TS_MW, $timestamp ) : false;
    }

    public function countRevisionsByPageId( IDatabase $db, $id ) {
        $this->checkDatabaseWikiId( $db );

        $row = $db->selectRow( 'revision',
            [ 'revCount' => 'COUNT(*)' ],
            [ 'rev_page' => $id ],
            __METHOD__
        );
        if ( $row ) {
            return intval( $row->revCount );
        }
        return 0;
    }

    public function countRevisionsByTitle( IDatabase $db, $title ) {
        $id = $title->getArticleID();
        if ( $id ) {
            return $this->countRevisionsByPageId( $db, $id );
        }
        return 0;
    }

    public function userWasLastToEdit( IDatabase $db, $pageId, $userId, $since ) {
        $this->checkDatabaseWikiId( $db );

        if ( !$userId ) {
            return false;
        }

        $revQuery = $this->getQueryInfo();
        $res = $db->select(
            $revQuery['tables'],
            [
                'rev_user' => $revQuery['fields']['rev_user'],
            ],
            [
                'rev_page' => $pageId,
                'rev_timestamp > ' . $db->addQuotes( $db->timestamp( $since ) )
            ],
            __METHOD__,
            [ 'ORDER BY' => 'rev_timestamp ASC', 'LIMIT' => 50 ],
            $revQuery['joins']
        );
        foreach ( $res as $row ) {
            if ( $row->rev_user != $userId ) {
                return false;
            }
        }
        return true;
    }

    public function getKnownCurrentRevision( Title $title, $revId ) {
        $db = $this->getDBConnectionRef( DB_REPLICA );

        $pageId = $title->getArticleID();

        if ( !$pageId ) {
            return false;
        }

        if ( !$revId ) {
            $revId = $title->getLatestRevID();
        }

        if ( !$revId ) {
            wfWarn(
                'No latest revision known for page ' . $title->getPrefixedDBkey()
                . ' even though it exists with page ID ' . $pageId
            );
            return false;
        }

        // Load the row from cache if possible.  If not possible, populate the cache.
        // As a minor optimization, remember if this was a cache hit or miss.
        // We can sometimes avoid a database query later if this is a cache miss.
        $fromCache = true;
        $row = $this->cache->getWithSetCallback(
            // Page/rev IDs passed in from DB to reflect history merges
            $this->getRevisionRowCacheKey( $db, $pageId, $revId ),
            WANObjectCache::TTL_WEEK,
            function ( $curValue, &$ttl, array &$setOpts ) use (
                $db, $pageId, $revId, &$fromCache
            ) {
                $setOpts += Database::getCacheSetOptions( $db );
                $row = $this->fetchRevisionRowFromConds( $db, [ 'rev_id' => intval( $revId ) ] );
                if ( $row ) {
                    $fromCache = false;
                }
                return $row; // don't cache negatives
            }
        );

        // Reflect revision deletion and user renames.
        if ( $row ) {
            return $this->newRevisionFromRow( $row, 0, $title, $fromCache );
        } else {
            return false;
        }
    }

    private function getRevisionRowCacheKey( IDatabase $db, $pageId, $revId ) {
        return $this->cache->makeGlobalKey(
            self::ROW_CACHE_KEY,
            $db->getDomainID(),
            $pageId,
            $revId
        );
    }

    // TODO: move relevant methods from Title here, e.g. getFirstRevision, isBigDeletion, etc.

}

class_alias( RevisionStore::class, 'MediaWiki\Storage\RevisionStore' );