djongo: a Django to MongoDB connector capped at Django 3.1 and pymongo 3.11

The unusual mechanism: compiling SQL into a MongoDB query document

djongo is described as a SQL to MongoDB query compiler. It takes a SQL query string and translates it into a MongoDB query document, which is what allows Django's ORM to keep working unchanged.

Read that again, because it explains everything about the project, including its limits. Most Django plus MongoDB options take one of two routes: a third party ORM with a Django-like syntax, in which case you rewrite model definitions and imports, or a thin driver in which case you write queries yourself. djongo instead intercepts at the SQL layer and compiles down, so models, querysets and the admin interface continue to emit SQL that becomes MongoDB.

The stated payoff is that all Django features, models and so on work as is, and that the contrib modules django.contrib.admin, django.contrib.auth and django.contrib.sessions are fully supported, along with others. For a team with a working admin interface over a large existing model layer, that is the whole argument, and it is a real one.

The cost of the approach is visible in the dependency ceilings. Whatever else changes, the compiler has to track the SQL Django emits, which is why the version bounds matter more here than in an ordinary package.

Install and wire it into settings.py

The package installs from PyPI:

pip install djongo

Then the DATABASES setting points Django at the connector rather than at a SQL engine, with a host under a CLIENT key:

DATABASES = {
    'default': {
        'ENGINE': 'djongo',
        'NAME': 'your-db-name',
        'CLIENT': {
           'host': 'your-db-host',
        }
    }
}

The third step is the one people miss. You run manage.py makemigrations <app_name> followed by manage.py migrate, and the README marks this as only for the first time, to create collections in MongoDB. In other words the migration is doing collection setup rather than building relational tables, so running it repeatedly on a live dataset is not the intent.

Requirements are stated as Python 3.6 or higher and MongoDB 3.4 or higher, with one exception. If your models use nested queries or sub querysets, such as filtering one model by a values queryset from another, MongoDB 3.6 or higher is required. That example is short:

inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
entries = Entry.objects.filter(blog__name__in=inner_qs)

If that pattern appears anywhere in your codebase, 3.6 is your floor, not 3.4.

The dependency ceilings are the real specification

pyproject.toml is short and every line matters:

dependencies = [
    'sqlparse==0.2.4',
    'pymongo>=3.7.0,<=3.11.4',
    'django>=2.1,<=3.1.12',
    'pytz>=2018.5'
]

sqlparse is pinned to exactly one version, which is consistent with the parsing approach: the SQL text handling depends on that release's behaviour. pymongo is capped at 3.11.4 and Django at 3.1.12, and both are upper bounds rather than minimums.

An upper bound on a database driver and on your web framework is a different kind of constraint from a minimum. It means the package will refuse to install alongside a newer Django, or will resolve to an older pymongo that a newer MongoDB server may not fully match. For an application, this is the difference between a connector and a fork you maintain yourself.

The metadata also carries requires-python as >=3.6 and a Development Status of 3 - Alpha, while the classifier list includes a Programming Language entry for Python 3.6 only. The stated floor and the tested floor are not the same number, which is worth noticing on a project of this age.

Version numbers come from the package itself rather than a tag, since pyproject.toml sets version as dynamic and reads djongo.__version__.

Features beyond the ORM, and what documentation exists

The feature list names four things beyond query translation. You can use the Django Admin GUI to access MongoDB, which follows from the contrib support. Embedded Model allows a document to hold a nested model. Embedded Array does the same for a list. Embedded Form Fields exposes those embedded documents through Django forms rather than only through the ORM.

Those last three are the ones that make the connector useful for schema design that MongoDB actually encourages, and they are also the ones most likely to need the full documentation rather than the README. The README points to the documentation site at djongomapper.com for the complete set.

For anyone wanting to understand the internals, the project publishes a design document specifically about how the Django MongoDB connector is implemented. That is unusual and worth reading before committing, because it tells you whether the compiler approach is a maintained design or a set of accumulated patches.

Community channels are split by purpose: a Google group for release announcements and discussion, GitHub issues for things not working as expected, and Stack Overflow for usage questions. That split is a small signal about the volume of each.

Maintenance: recent pushes, no releases since 2018

Here the signals disagree, and an adopter needs to hold both.

The repository is not archived and the last push was on 2026-10-06, so files are being touched. The latest listed release is 1.2.23, named Stable regressed, published on 2018-03-19. A release title reading Stable regressed is its own commentary: the last tagged state was labelled as a regression, and nothing has superseded it in the release list.

Against that, the constraints have not moved. The package metadata still points to the older Django and pymongo lines. A project whose source receives attention but whose release artefacts are from 2018 is usually one where fixes land on master and are picked up by installing from a branch rather than from PyPI.

So the honest summary is: the code is being worked on, the published package is eight years old, and the dependency ceilings mean that even a current checkout runs against a 2020 era Django. Plan for the second and third facts, and treat the first as a bonus.

The alternative, and the difference in approach

The main alternatives are a Django-compatible ODM, a document field in a relational database, or MongoDB with an API layer instead of an ORM.

The difference in approach between djongo and a Django-style ODM is where the queries are written. djongo leaves your queryset code untouched and compiles SQL downward, so a codebase written for Django runs unchanged, at the cost of depending on how faithfully the compiler reproduces Django's SQL semantics. A third party ODM changes your imports and model declarations, which is a large but visible diff, and in exchange the query language is the vendor's own rather than a translation layer's interpretation of SQL.

The relational middle path is the one worth naming explicitly. A relational database's document-shaped fields can provide another route while staying with the relational ORM. If the reason you want MongoDB is nested documents rather than scale or sharding, that route removes the entire class of problems djongo's ceilings create.

The deciding question is therefore not which library is better but why MongoDB is in the picture. If it is sharding or document flexibility at scale, djongo may be the least disruptive route. If it is a general preference for document storage on a small dataset, the relational route will age considerably better.

Licence, which is AGPL with a mismatched classifier

The project is AGPL-3.0, with the LICENSE file at the repository root and the licence declared in pyproject.toml as AGPL. The README badge also reads AGPL v3. That is a strong copyleft licence, and it carries obligations when you modify the program and let others interact with it, particularly over a network. This is a licence note rather than legal advice, and for an internal service the practical questions are about distribution and about whether your deployment model triggers the network use clause.

One inconsistency is worth flagging because it is exactly the kind of thing that matters in a licence review. The classifiers list includes 'License:: OSI Approved:: BSD License' alongside the AGPL declarations. If your process reads classifiers to populate a licence report, this package will be recorded as BSD.

The project also depends on sqlparse, pymongo and Django, so their respective terms need separate review.

Before adopting, resolve that classifier question against the LICENSE file directly, confirm your deployment model against the AGPL network clause, and read the design document to judge whether the SQL compilation approach is a design you want to depend on.

Editorial conclusion

Use djongo if you have an existing Django project whose models and admin interface must stay unchanged while the storage moves to MongoDB, because the SQL to query document compiler is the only approach described here that keeps the ORM intact, and the Django contrib modules including admin, auth and sessions are listed as fully supported. Do not start a new project on it. The dependency ceiling of django>=2.1,<=3.1.12 and pymongo>=3.7.0,<=3.11.4 means you are choosing a Django release line that ended years ago, and both of those upper bounds are hard, not advisory. Verify first which Django version your project is on, whether you can accept staying on 3.1, and whether MongoDB 3.6 is available if your queries use sub querysets, since nested queries require it and 3.4 is the stated baseline.

Frequently asked questions

Official sources

1. doableware/djongo on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases