MongoDB with Python: Connect, Insert and Retrieve Data

Introduction

Python is one of the most popular programming languages used for web development, automation, data science, machine learning and backend development.

MongoDB is a flexible NoSQL database that stores information in JSON-like documents. By connecting Python with MongoDB, developers can build applications that store, retrieve, update and manage data efficiently.

To connect Python applications with MongoDB, we use PyMongo, the official Python driver for MongoDB.

In this tutorial, you will learn how to connect Python with MongoDB, create databases and collections, insert documents, retrieve records and perform basic CRUD operations using practical examples.

1. What Is PyMongo?

PyMongo is the official Python library used to communicate with MongoDB databases.

It allows Python applications to perform database operations without directly writing MongoDB commands in the MongoDB Shell.

Using PyMongo, we can:

• Connect Python applications to MongoDB.

• Create and access databases.

• Work with collections and documents.

• Insert single or multiple documents.

• Retrieve documents using queries.

• Update existing records.

• Delete documents from collections.

Example:

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")

Here, MongoClient creates a client that allows our Python application to communicate with MongoDB.

2. Requirements Before Starting

Before connecting Python with MongoDB, make sure you have installed:

1. Python 3.

2. MongoDB Community Server or a MongoDB Atlas account.

3. Visual Studio Code or another Python code editor.

4. pip package installer.

5. PyMongo Python driver.

You should also understand basic Python syntax and MongoDB database, collection and document concepts.

3. Install PyMongo

First, open the terminal in Visual Studio Code.

Run the following command:

python -m pip install pymongo

If you also want to store database connection details in a .env file, install python-dotenv:

python -m pip install python-dotenv

To verify that PyMongo is installed, run:

python -m pip show pymongo

If the package information appears, PyMongo is installed successfully.

Important: Do not install a separate package named bson. PyMongo already includes its compatible BSON implementation.

4. Create a Python Project

Create a new folder named:

mongodb_python_project

Open this folder in Visual Studio Code.

Create the following files:

mongodb_python_project/
│
├── .env
├── .gitignore
└── main.py

We will use main.py for our MongoDB operations.

5. Configure the MongoDB Connection

There are two common ways to connect Python with MongoDB:

• Local MongoDB Server

• MongoDB Atlas Cloud Database

Option A: Connect to Local MongoDB

If MongoDB Community Server is installed and running on your computer, use this connection string:

mongodb://127.0.0.1:27017/

The default MongoDB port is 27017.

Option B: Connect to MongoDB Atlas

If you are using MongoDB Atlas, copy the connection string from your Atlas cluster.

It looks similar to:

mongodb+srv://<username>:<password>@cluster-name.mongodb.net/

Replace the username, password and cluster details with your actual Atlas credentials.

Before connecting, make sure your database user is created and your current IP address is allowed in Atlas Network Access.

Store the Connection String in .env

Open the .env file and add:

MONGODB_URI=mongodb://127.0.0.1:27017/

For Atlas, replace the local URI with your Atlas connection string.

Now open .gitignore and add:

.env
.venv/
__pycache__/

This helps prevent sensitive connection details and local environment files from being committed to Git.

6. Connect Python to MongoDB

Open main.py and write the following code:

from pymongo import MongoClient
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Get MongoDB connection string
MONGODB_URI = os.getenv(
    "MONGODB_URI",
    "mongodb://127.0.0.1:27017/"
)

# Create MongoDB client
client = MongoClient(MONGODB_URI)

try:
    # Check MongoDB connection
    client.admin.command("ping")

    print("MongoDB connected successfully!")

except Exception as error:
    print("MongoDB connection failed:", error)

finally:
    client.close()

Code Explanation

• MongoClient creates a connection client for MongoDB.

• load_dotenv() loads variables from the .env file.

• os.getenv() reads the MongoDB connection string.

• client.admin.command("ping") checks whether MongoDB responds successfully.

• client.close() closes the client after this connection test.

Save the file and run:

python main.py

Expected output:

MongoDB connected successfully!

Note: This is only a connection test. In the complete CRUD program below, we will keep the client open while performing database operations and close it after the work is finished.

7. Create a Database and Collection

In MongoDB, a database contains collections, and collections contain documents.

Let's use the following database and collection:

• Database Name: collegeDB

• Collection Name: students

Add this code to your Python program:

database = client["collegeDB"]

students = database["students"]

Here:

• client["collegeDB"] accesses the database named collegeDB.

• database["students"] accesses the students collection.

MongoDB creates a database and collection when data is first stored in them. Merely selecting a database or collection does not necessarily create it physically.

8. Insert One Document Using insert_one()

The insert_one() method is used to insert a single document into a MongoDB collection.

Example:

student = {
    "name": "Rahul",
    "age": 22,
    "course": "Python",
    "city": "Raipur"
}

result = students.insert_one(student)

print("Inserted ID:", result.inserted_id)

Explanation

• student is a Python dictionary containing student details.

• insert_one() inserts this dictionary as one MongoDB document.

• inserted_id returns the unique _id assigned to the inserted document.

MongoDB automatically generates an _id value when one is not supplied.

Example Document in MongoDB:

{
    _id: ObjectId("..."),
    name: "Rahul",
    age: 22,
    course: "Python",
    city: "Raipur"
}

The actual ObjectId will be generated by MongoDB and will be different for each inserted document.

9. Insert Multiple Documents Using insert_many()

If you want to insert multiple records at once, use the insert_many() method.

Example:

students_data = [
    {
        "name": "Amit",
        "age": 21,
        "course": "Python",
        "city": "Raipur"
    },
    {
        "name": "Priya",
        "age": 23,
        "course": "Java",
        "city": "Bilaspur"
    },
    {
        "name": "Rohit",
        "age": 22,
        "course": "MongoDB",
        "city": "Durg"
    }
]

result = students.insert_many(students_data)

print("Inserted IDs:", result.inserted_ids)

Explanation

• students_data is a list of Python dictionaries.

• Each dictionary represents one document.

• insert_many() inserts all the supplied documents.

• inserted_ids returns the IDs of the inserted documents.

This method is useful when you need to insert multiple records efficiently.

10. Retrieve All Documents Using find()

The find() method retrieves multiple documents from a MongoDB collection.

Example:

records = students.find()

for record in records:
    print(record)

Explanation

• find() retrieves documents from the collection.

• The returned cursor can be iterated using a for loop.

• Each record represents one MongoDB document.

Example output:

{
    '_id': ObjectId('...'),
    'name': 'Rahul',
    'age': 22,
    'course': 'Python',
    'city': 'Raipur'
}

The output will depend on the documents stored in your collection.

11. Retrieve One Document Using find_one()

If you want to retrieve only one matching document, use find_one().

Example:

student = students.find_one({"name": "Rahul"})

print(student)

Explanation

• find_one() searches for the first document matching the filter.

• {"name": "Rahul"} is the query condition.

• If a matching document is found, it returns that document.

• If no matching document exists, it returns None.

12. Retrieve Documents Using Query Conditions

You can also retrieve documents using conditions.

Example: Find students whose age is greater than 21.

records = students.find({"age": {"$gt": 21}})

for record in records:
    print(record)

Here, $gt means greater than.

Some useful MongoDB comparison operators include:

Operator	Meaning
$gt	Greater than
$gte	Greater than or equal to
$lt	Less than
$lte	Less than or equal to
$eq	Equal to
$ne	Not equal to

Example: Find students who are older than or equal to 22.

records = students.find({"age": {"$gte": 22}})

for record in records:
    print(record)

13. Update a Document Using update_one()

The update_one() method modifies the first document that matches the given condition.

Example:

result = students.update_one(
    {"name": "Rahul"},
    {"$set": {"course": "Full Stack Python"}}
)

print("Modified Count:", result.modified_count)

Explanation

• The first argument identifies the document to update.

• $set changes the specified field.

• modified_count tells you how many documents were modified.

If the matching value is already the same, the modified count may be zero.

14. Delete a Document Using delete_one()

The delete_one() method removes the first document matching the given condition.

Example:

result = students.delete_one({"name": "Rahul"})

print("Deleted Count:", result.deleted_count)

Explanation

• delete_one() searches for a matching document.

• It deletes the first matching document.

• deleted_count returns the number of documents deleted.

Be careful when deleting records. Always use an appropriate filter so you do not remove unintended data.

15. Complete Python MongoDB CRUD Program

Now let's combine the connection, insert, retrieve, update and delete operations into one practical Python program.

Open main.py and use the following complete code:

from pymongo import MongoClient
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# MongoDB connection
MONGODB_URI = os.getenv(
    "MONGODB_URI",
    "mongodb://127.0.0.1:27017/"
)

client = MongoClient(MONGODB_URI)

try:
    # Check connection
    client.admin.command("ping")
    print("MongoDB connected successfully!")

    # Select database and collection
    database = client["collegeDB"]
    students = database["students"]

    # Insert one document
    student = {
        "name": "Rahul",
        "age": 22,
        "course": "Python",
        "city": "Raipur"
    }

    insert_result = students.insert_one(student)
    print("Inserted ID:", insert_result.inserted_id)

    # Retrieve all documents
    print("\\nAll Student Records:")

    for record in students.find():
        print(record)

    # Retrieve one document
    print("\\nFind One Student:")

    result = students.find_one({"name": "Rahul"})
    print(result)

    # Update one document
    update_result = students.update_one(
        {"_id": insert_result.inserted_id},
        {"$set": {"course": "Full Stack Python"}}
    )

    print("\\nModified Count:", update_result.modified_count)

    # Delete the inserted document
    delete_result = students.delete_one(
        {"_id": insert_result.inserted_id}
    )

    print("Deleted Count:", delete_result.deleted_count)

except Exception as error:
    print("Error:", error)

finally:
    # Close MongoDB connection
    client.close()
    print("MongoDB connection closed.")

How This Program Works

1. Loads the MongoDB connection string from .env.

2. Creates a MongoDB client.

3. Checks the database connection using ping.

4. Selects the collegeDB database.

5. Selects the students collection.

6. Inserts a student document.

7. Retrieves all student records.

8. Retrieves one matching student.

9. Updates the inserted student's course.

10. Deletes the inserted student.

11. Closes the MongoDB client.

The program uses the inserted document's _id for the update and delete operations. This makes sure those two operations target the exact document created during the run.

16. Test the Data in MongoDB Compass

You can verify your Python operations using MongoDB Compass.

Follow these steps:

1. Open MongoDB Compass.

2. Connect to your local MongoDB server or Atlas cluster.

3. Find the collegeDB database.

4. Open the students collection.

5. View the stored documents.

If you run the complete CRUD program above, it inserts a record and then deletes that same record. Therefore, the test document will not remain in the collection after the program finishes.

To keep a document in the collection, temporarily remove or comment out the delete_one() section.

17. Common Errors and Their Solutions

Error 1: ModuleNotFoundError: No module named 'pymongo'

Reason: PyMongo is not installed in the Python environment currently running your script.

Solution:

python -m pip install pymongo

Error 2: ServerSelectionTimeoutError

Reason: Python cannot reach the MongoDB server.

Possible solutions:

• Make sure MongoDB Server is running.

• Check the connection string.

• Verify the MongoDB port.

• Check network connectivity if you are using Atlas.

Error 3: Authentication Failed

Reason: MongoDB Atlas username or password may be incorrect, or the database user may not have the required permissions.

Solution:

• Verify your Atlas database username.

• Check your password.

• Confirm that the database user has suitable permissions.

• Make sure the IP address is allowed in Atlas Network Access.

Error 4: Invalid Connection String

Reason: The MongoDB URI may contain incorrect syntax or missing connection details.

Solution: Copy the correct connection string from MongoDB Atlas or use the correct local connection string:

mongodb://127.0.0.1:27017/

18. Best Practices for Using PyMongo

Follow these practices when developing real Python applications:

1. Use the official PyMongo driver.

2. Keep database credentials in environment variables.

3. Never upload your .env file to a public Git repository.

4. Reuse a MongoClient instance in a long-running application instead of creating a new client for every database operation.

5. Close the client when your application is finished with it.

6. Use meaningful database and collection names.

7. Validate input before inserting documents.

8. Use appropriate query filters for update and delete operations.

9. Handle connection and database errors properly.

10. Avoid exposing database credentials in source code or logs.

19. Practical Exercises

Try these exercises to improve your MongoDB and Python skills.

Exercise 1: Connect Python to your local MongoDB server using PyMongo.

Exercise 2: Create a database named schoolDB and a collection named teachers.

Exercise 3: Insert five teacher records using insert_many().

Exercise 4: Retrieve all teacher records using find().

Exercise 5: Find a teacher by name using find_one().

Exercise 6: Find teachers whose experience is greater than five years.

Exercise 7: Update the subject of one teacher using update_one().

Exercise 8: Delete one teacher record using delete_one().

20. Frequently Asked Questions (FAQs)

Q1. What is PyMongo in Python?

PyMongo is the official Python driver used to connect Python applications with MongoDB databases.

Q2. How do I install PyMongo?

Run this command in your terminal:

python -m pip install pymongo

Q3. How can I connect Python to MongoDB?

Use MongoClient with a valid MongoDB connection string.

from pymongo import MongoClient

client = MongoClient("mongodb://127.0.0.1:27017/")
client.admin.command("ping")

Q4. Which method is used to insert data into MongoDB?

Use insert_one() to insert a single document and insert_many() to insert multiple documents.

Q5. Which method is used to retrieve data from MongoDB?

Use find_one() to retrieve one matching document and find() to retrieve multiple matching documents.

Q6. Can Python connect to MongoDB Atlas?

Yes. Python can connect to MongoDB Atlas using PyMongo and the Atlas connection string.

Q7. Does MongoDB automatically create an _id field?

Yes. If you do not provide an _id field, MongoDB automatically generates a unique ObjectId for the document.

Conclusion

Connecting Python with MongoDB is simple with the help of the PyMongo driver.

In this tutorial, we learned how to install PyMongo, connect Python to MongoDB, create databases and collections, insert documents, retrieve records, update data and delete documents.

These concepts are useful for building Python applications such as student management systems, inventory applications, web applications, automation tools and data-driven projects.

Practice each example with your own database to improve your understanding of MongoDB and Python integration.