Compatibility Changes with Legacy mongo Shell

Deprecated Methods

The following shell methods are deprecated in mongosh. Instead, use the methods listed in the Alternative Resources column.

Read Preference Behavior

Write Preference Behavior

Retryable writes are enabled by default in mongosh. Retryable writes were disabled by default in the legacy mongo shell. To disable retryable writes, use --retryWrites=false.

ObjectId Methods and Attributes

These ObjectId() methods work differently in mongosh than in the legacy mongo shell.

Numeric Values

The legacy mongo shell stored numerical values as doubles by default. In mongosh numbers are stored as 32 bit integers, Int32, or else as Double if the value cannot be stored as an Int32.

MongoDB Shell continues to support the numeric types that are supported in mongo shell. However, the preferred types have been updated to better align with the MongoDB drivers. See mongosh Data Types for more information.

The preferred types for numeric variables are different in MongoDB Shell than the types suggested in the legacy mongo shell. The types in mongosh better align with the types used by the MongoDB Drivers.

Undefined Values

The undefined BSON type is deprecated. If you try to insert a document with the undefined JS type in mongosh, your deployment replaces the undefined value in your document with the BSON null value. There is no supported way of inserting undefined values into your database using mongosh.

For example, consider running the following code to insert a document in mongosh:

db.people.insertOne( { name : "Sally", age : undefined } )

When you run this code in mongosh, the shell inserts the following document:

{ name : "Sally", age : null }

mongosh represents any BSON undefined values stored using other tools, such as the Go Driver or the legacy mongo shell, as null.

Object Quoting Behavior

mongosh does not quote object keys in its output, and places single quotes on values. To reproduce the output of the legacy mongo shell, which wraps both the keys and string values in double quotes, use mongosh --eval with EJSON.stringify().

For example, the following command returns the items in the sales collection on the test database with double quotes and indentation:

mongosh --eval "EJSON.stringify(db.sales.findOne().toArray(), null, 2)"

The output looks like the following:

{
     "_id": {
          "$oid": "64da90c1175f5091debcab26"
     },
     "custId": 345,
     "purchaseDate": {
          "$date": "2023-07-04T00:00:00Z"
     },
     "quantity": 4,
     "cost": {
          "$numberDecimal": "100.60"
     }
}

Limitations on Database Calls

The results of database queries cannot be passed inside the following contexts:

• Class constructor functions

• Non-async generator functions

• Callbacks to .sort() on an array

• JavaScript setters in classes

To access to the results of database calls, use async functions, async generator functions, or .map().

// This code will fail
class FindResults {
   constructor() {
      this.value = db.students.find();
   }
}
// This code will fail
function listEntries() { return db.students.find(); }
class FindResults {
   constructor() {
      this.value = listEntries();
   }
}

class FindResults {
   constructor() {
      this.value = ( async() => {
         return db.students.find();
      } )();
   }
}

class FindResults {
   constructor() { }
   init() { this.value = db.students.find(); }
 }

// This code will fail
function* FindResults() {
   yield db.students.findOne();
}
// This code will fail
function listEntries() { return db.students.findOne(); }
function* findResults() {
   yield listEntries();
}

function listEntries() { return db.students.findOne(); }
async function* findResults() {
   yield listEntries();
}

// This code will fail
db.getCollectionNames().sort( ( collectionOne, collectionTwo ) => {
  return db[ collectionOne ].estimatedDocumentCount() - db[ collectionOne ].estimatedDocumentCount() )
} );

db.getCollectionNames().map( collectionName => {
   return { collectionName, size: db[ collectionName ].estimatedDocumentCount() };
} ).sort( ( collectionOne, collectionTwo ) => {
   return collectionOne.size - collectionTwo.size;
} ).map( collection => collection.collectionName);

// This code will fail
class TestClass {
  value = 1;
  get property() {
    return this.value;
  }
  // does not work:
  set property(value) {
    this.value = db.test.findOne({ value });
  }
}

Command Exceptions

For commands whose output includes { ok: 0 }, mongosh returns a consistent exception and omits the server raw output. The legacy mongo shell returns output that varies for each command.

For details, see Run Commands.

Shell Configuration

The legacy mongo shell uses a configuration file named .mongorc.js.

If mongosh finds .mongorc.js on startup but doesn't find .mongoshrc.js, mongosh doesn't load the legacy .mongorc.js file and states you should rename .mongorc.js to .mongoshrc.js.

For details, see .mongoshrc Configuration File.

Data Types

MongoDB stores data using BSON, which supports additional data types that aren't available in JSON. The mongosh shell has better data type support for drivers than the legacy mongo shell.

For details, see Data Types.

Methods

The legacy mongo shell cannot access a script's file name or directory in the load() method.

For details, see load().

Retryable Writes

By default, retryable writes are:

• enabled in mongosh

• disabled in the legacy mongo shell

To disable retryable writes, use --retryWrites=false.

For details, see --retryWrites.

Legacy Output

The mongosh shell returns output that differs from the legacy mongo shell. If you have scripts that require the output to be formatted in a similar way to the legacy mongo shell, try reformatting the mongosh output with EJSON.stringify().

For details, see Legacy tojsononeline().

Code Snippets

Working with code snippets is different for the legacy mongo shell.

For details, see Get Help for a Snippet.