Install MongoDB on macOS with Homebrew and CRUD operations

▶

Let's learn how to install MongoDB if we are on macOS; for this, we will start with the assumption that you have Homebrew installed, which is simply a package manager for macOS and Linux.

Installing MongoDB on macOS might seem complicated the first time, but using Homebrew makes the process much simpler and cleaner. In this guide, I will explain step-by-step how to install MongoDB on macOS with Homebrew, how to start it correctly, and how to begin working with the database by performing basic CRUD operations.

In my case, this workflow is the one I always use whenever I set up a new development environment on Mac, and it avoids most of the typical errors that usually appear when starting MongoDB for the first time.

Once we have our package manager, it couldn't be easier; the first thing we need to do is add the MongoDB repository to our package manager.

Prerequisites

Before installing MongoDB, it is important to ensure that the system has everything necessary.

Compatible macOS

MongoDB works correctly on modern versions of macOS (Catalina onwards). If you are using a very old version, it is recommended to update the system or install a compatible version of MongoDB.

Homebrew Installation

macOS does not include Homebrew by default, and it is one of the most important tools for development on Mac. Homebrew is a package manager that allows you to install software from the terminal easily.

To install it, follow the official instructions from their website:

https://brew.sh/#install

Necessary software to install MongoDB

Install Command line tools for Xcode

Most likely, when you go to execute the Brew command to install the package, it will ask you to install the Command Line Tools for Xcode; accept, download, and install these tools.

It is very likely that, when executing any brew command, macOS will ask you to install the Command Line Tools for Xcode.

Accept the message and let them install, as they are necessary to compile and run many dependencies.

Install Homebrew

What is a Homebrew tap?

A tap is simply an additional repository that Homebrew uses to find packages. MongoDB maintains its official tap, which is important to avoid unsupported installations.

Command to add the tap

Now, let's install Homebrew; macOS does not include the Homebrew preparation package by default; therefore, you have to install it as indicated on the official page. https://brew.sh/#install

Homebrew installs the things you need for your macOS from a terminal easily.

$ brew tap mongodb/brew

This step is key; many errors come from trying to install MongoDB without using the official tap.

Choosing the MongoDB version

MongoDB publishes several versions. In this case, we are going to install a specific stable version, which is the one that has given me the best results on macOS:

Install the MongoDB Homebrew Tap

Issue the following from the terminal to tap the official MongoDB Homebrew tap: https://github.com/mongodb/homebrew-brew

This is a custom Homebrew Tap (package) for official MongoDB software.

$ brew tap mongodb/brew

Or a specific version:

$ brew install mongodb-community@5.0

Installing a specific version avoids incompatibilities with libraries or the operating system, something that has already saved me from more than one headache.

Installation check

Once the process is finished, MongoDB will already be installed on your computer, but it will not yet be running.

Starting the MongoDB process

Now that we have MongoDB on our computer, the next thing we are going to do is start the process, because if we run in our terminal:

brew services start mongodb-community

This command is fundamental. If you don't start the service and run mongo directly, you will get a connection error.

Because if you don't start it and type mongo in the terminal, you will see an error like the following:

MongoDB shell version v8.0.2
connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
Error: couldn't connect to server 127.0.0.1:27017, connection attempt failed: SocketException: Error connecting to 127.0.0.1:27017 :: caused by :: Connection refused :
connect@src/mongo/shell/mongo.js:372:17

This happens because MongoDB is not listening on port 27017.

Once started correctly, the command:

$ mongo

Will allow you to access the shell without problems, or see its installed version:

$ mongod --version

Stopping or restarting MongoDB

Some useful commands I usually use:

$ brew services stop mongodb-community
$ brew services restart mongodb-community

⚠️ Common errors and how to solve them

Connection error on localhost

It is almost always because the service is not started. Verify with:

$ brew services list

Incompatible version problems

If you changed your macOS version or updated MongoDB, it may be necessary to reinstall the correct version or clean up old services.

First steps with MongoDB (Basic CRUD)

Let's learn how we can perform CRUD operations using MongoDB; remember that CRUD operations are those that allow us to Create, Read, Update, and Delete respectively.

Create operations

Create or insertion operations add new documents to a collection. If the collection does not currently exist, the insertion operations will create the collection.
MongoDB provides the following methods to insert documents into a collection:

db.collection.insertOne() 
db.collection.insertMany()

Example operations:

var user2 = {
   name: 'Andres',
   last_name: 'Cruz',
   age: 29,
   email: 'andres@gmail.com'
}
var user3 = {
   name: 'Pablo',
   last_name: 'Lama',
   age: 30,
   email: 'pablo@gmail.com'
}
var user4 = {
   name: 'Luis',
   last_name: 'Yello',
   age: 99,
   email: 'pepe@gmail.com'
}
db.users.insertOne(user2)
db.users.insertMany(
   [user3, user4, user2]
)

Which allow inserting a single record or more than one respectively.

Read operations

Read operations retrieve documents from a collection; that is, they query a collection of documents. MongoDB provides the following operation to read documents from a collection:

db.collection.find()
Operaciones de ejemplo:
db.users.find(
   { age: 25 },
   { name: true, email: true, _id: false }
).pretty()
db.users.find(
   { age: 25 },
   { email: false, _id: false }
).pretty()

Update operations

Update operations modify existing documents in a collection. MongoDB provides the following methods to update documents in a collection:

db.collection.updateOne()
db.collection.updateMany()
db.collection.replaceOne()

Example operations:

db.users.updateMany(
   {
       name: {
           $exists: true
       }
   },
   {
       $set: {
           name2: "Luisito"
       }
   }
)
db.users.updateOne(
   {
       name: {
           $exists: true
       }
   },
   {
       $unset: {
           name2: "Luisito"
       }
   }
)

Delete operations

Delete operations remove documents from a collection. MongoDB provides the following methods to delete documents from a collection:

db.collection.deleteOne()
db.collection.deleteMany()

Example operations:

db.users.deleteOne({"_id": new mongo.ObjectID(id) })
db.users.deleteMany({"_id": new mongo.ObjectID(id) })

Additional tips and best practices

• Always use the official MongoDB tap
• Install specific versions to avoid incompatibilities
• Don't forget to start the service before using the shell
• For production environments, enable authentication and backups