[DOCS-11641] Document that upgradeCheckAllDBS() and upgradeCheck() must have an explicit option specified that enforces documents validation Created: 23/Apr/18  Updated: 30/Oct/23

Status: Closed
Project: Documentation
Component/s: Server
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Bug Priority: Major - P3
Reporter: Dmitry Ryabtsev Assignee: Unassigned
Resolution: Won't Do Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 1 year, 14 weeks, 2 days ago
Epic Link: DOCSP-1769

 Description   

The problem is that the db.upgradeCheckAllDBs() and db.upgradeCheck() helpers will only validate the data if true option is specified - you can tell that from the source code:

 
> db.upgradeCheckAllDBs
function (checkDocs) {  // <== here's the option that enforces document check
"use strict";
 
        var self = this;
        if (self.getName() !== "admin") {
            throw Error("db.upgradeCheckAllDBs() can only be run from the admin database");
        }
 
        var dbs = self.getMongo().getDBs();
        var goodSoFar = true;
 
        // run db level checks on each db
        dbs.databases.forEach(function(dbObj) {
            if (!dbUpgradeCheck(self.getSiblingDB(dbObj.name), checkDocs)) { 
                goodSoFar = false;
            }
        });
 
        if (goodSoFar) {
            print("Everything is ready for the upgrade!");
            return true;
        }
        print("To fix the problems above please consult " +
              "http://dochub.mongodb.org/core/upgrade_checker_help");
        return false;
    }

If you run it as suggested in the documentation, then the helper will not be able to detect if, for instance there are index keys that are violating the index key limit of 1024 bytes e.g.:

db.getSiblingDB("admin").upgradeCheckAllDBs()

In order to get that behaviour it should be executed as:

db.getSiblingDB("admin").upgradeCheckAllDBs(true)

Likewise for upgradeCheck(), it should be executed as:

db.upgradeCheck( { collection: '<collection_name>' }, true );

While the mentioned helpers were removed from v3.6, they are still has to be used by users who are migrating into Atlas. We should update the docs for v3.2 and 3.4 to reflect that the true option needs to be specified separately in order to enforce the document validation.



 Comments   
Comment by Education Bot [ 31/Oct/22 ]

Hello! This ticket has been closed due to inactivity. If you believe this ticket is still important, please reopen it and leave a comment to explain why. Thank you!

Comment by Dmitry Ryabtsev [ 23/Apr/18 ]

Turned out there is a defect in upgradeCheck() - it does not check the docs even if the true option is used (see SERVER-34609). Thus there is no point in updating the docs for upgradeCheck() unless that defect is fixed.

However, the documentation for db.upgradeCheckAllDBs() must be fixed.

EDIT: For db.upgradeCheck() there are two modes of operation:

  1. db.upgradeCheck(undefined, true); - this will enforce the check on all of the collections in the db; works as expected
  2. db.upgradeCheck({ collection: "<name>"}, true) - this one is broken as reported in SERVER-34609
Generated at Thu Feb 08 08:03:18 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.