mongofw

mongofw is a small Python library that gathers the tasks I kept repeating with MongoDB into a single class. It is built on pymongo and offers inserting, querying, updating, deleting, backing up and restoring through simple methods. It can optionally cache query results in Valkey.

Purpose

pymongo is a powerful driver, but in every project I had to rewrite the same code for connecting, converting the _id field to an ObjectId, catching errors, counting total records for pagination and turning results into JSON. I wrote mongofw to remove that repetition.

My other goal was to make queries easier to write. MongoDB's own query language is flexible, but because it is written as nested dictionaries it can be hard to read. In this library I wanted to give conditions in a shorter, more readable form and translate them into a MongoDB query behind the scenes.

How it works

At the heart of the library is the MongoDBFramework class. When it is created, it receives the connection details, the collection to use and an optional Valkey client. The collection can be changed later with the set_collection method.

Queries are run with the get method. Conditions are given as a dictionary, and short operators can be used for each field. For example, sw looks for text that starts with a value, ew for text that ends with it and sew for text that contains it; these become case-insensitive regular expressions. Comparison operators such as gt, gte, lt, lte, in and nin are translated to their MongoDB equivalents. The or key combines several conditions with a logical "or". Field names that start with a dot are appended to a given base field, so long paths in nested documents do not have to be repeated.

When sort, skip and limit values are passed to get, the total record count is returned along with the results, which makes pagination easy. When a group_by parameter is given, the query becomes an aggregation pipeline, MongoDB's mechanism for processing data in stages, and returns record counts grouped by that field.

If a Valkey client is set and caching is requested, the result is written to the cache for a set time under a key built from the collection name and the query parameters. When the same query comes again, the result is read from the cache without touching the database.

Key features

• Insert, bulk insert, update, bulk update, delete and bulk delete are done through consistent methods.
• The update_between and delete_between methods update or delete records whose field falls between two values.
• _id values given as text are converted to ObjectId automatically.
• Every method is wrapped in a decorator, so MongoDB errors are caught and a consistent response with a success flag and a message is returned.
• An encoder and decoder convert ObjectId and date values to JSON and back.
• The get_sql method produces the SQL equivalent of the same conditions, which helps when debugging or explaining a MongoDB query to someone who knows SQL.
• The backup and restore methods call MongoDB's mongodump and mongorestore tools to back up and restore the database.
• Query results can optionally be cached in Valkey with an expiry time.

Technical stack

The library is written in Python and works with Python 3.9 and later. Its only direct dependency is pymongo. For caching, a Valkey or Redis client is passed in from outside and the library uses its get and set methods. Backup and restore require MongoDB's command-line tools to be installed on the system. The package is built with setuptools and released under the MIT licence.

Use cases

• Quickly setting up a data access layer in small and medium-sized Python projects that use MongoDB.
• Search and listing screens that need text search, range filters and pagination.
• Reducing database load by caching frequently repeated read queries in Valkey.
• Running simple backup and restore jobs from inside Python scripts.

Status

I released version 1.0.1 of the library in 2025. It is a small tool shaped by the needs of my own projects, not a broad framework.