diff --git a/docs/Gemfile b/docs/Gemfile
index 79ffbb8d5f99251c5cf1dd742c12febee39c9940..a30e766a6b3a8cf994d6a8c120bc513ab3fbbbad 100644
--- a/docs/Gemfile
+++ b/docs/Gemfile
@@ -1,9 +1,9 @@
source 'https://rubygems.org'
# run locally
-gem 'github-pages', group: :jekyll_plugins
-gem "jekyll-include-cache"
+# gem 'github-pages', group: :jekyll_plugins
+# gem "jekyll-include-cache"
# run server
-# gem "minimal-mistakes-jekyll" "4.15.2"
-# gem "jekyll", "~> 3.5"
+gem "minimal-mistakes-jekyll"
+gem "jekyll", "~> 3.5"
gem 'wdm'
diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml
index 84367e07a7583dd4b50efea0844e370cc025519a..0be88060a4c24933e1ea388c2922c71c38c216c5 100644
--- a/docs/_data/navigation.yml
+++ b/docs/_data/navigation.yml
@@ -1,7 +1,7 @@
# main links
main:
- title: "Get Started"
- url: /get-started/
+ url: /integrating-django-with-mongodb/
- title: "Sponsor"
url: https://www.patreon.com/nesdis/
- title: "Discuss"
@@ -10,10 +10,10 @@ main:
url: https://github.com/nesdis/djongo/
docs:
- - title: "Using Djongo"
+ - title: "Get Started"
url: /integrating-django-with-mongodb/
- - title: "Get started"
- url: /get-started/
+ - title: "Djongo Deep Dive"
+ url: /djongo-deep-dive/
- title: "Djongo Fields"
children:
- title: "Embedded Field"
@@ -47,9 +47,9 @@ docs:
- title: "Side stuff"
children:
- - title: "Other ways to integrate Django with MongoDBs"
- url: /different-ways-to-integrate-django-with-mongodb/
- - title: "Djongo design documentation"
+ - title: "Djongo vs Others"
+ url: /djongo-comparison/
+ - title: "Djongo Design"
url: /django-mongodb-connector-design-document/
# - title: "Roadmap"
# url: /roadmap/
diff --git a/docs/docs/different-ways-to-integrate-django-with-mongodb.md b/docs/docs/different-ways-to-integrate-django-with-mongodb.md
index 5d9485c13dbf38b5e0c257b4af1ee0b5966b089d..12e824b964579c5d4427df7948b55e08b594d908 100644
--- a/docs/docs/different-ways-to-integrate-django-with-mongodb.md
+++ b/docs/docs/different-ways-to-integrate-django-with-mongodb.md
@@ -1,9 +1,9 @@
---
-title: Different ways to integrate Django with MongoDB
-permalink: /different-ways-to-integrate-django-with-mongodb/
+title: Djongo vs Others
+permalink: /djongo-comparison/
---
-This page describes how to integrate MongoDB with Django with focus on Djongo. It describes the Django ORM internal implementation that is not covered by the [Django documentation](https://docs.djangoproject.com/en/dev/). If you have not yet checked out the [introduction to Djongo](https://nesdis.github.io/djongo/), be sure to do so!
+This page describes how to integrate MongoDB with Django with focus on Djongo. It describes the Django ORM internal implementation that is not covered by the [Django documentation](https://docs.djangoproject.com/en/dev/). If you have not yet checked out the [introduction to Djongo](https://nesdis.github.io/djongo/), be sure to do so first!
There are different ways to integrate MongoDB with Django, each with positives and negatives. Insights into the Django ORM design will help understand ways to integrate MongoDB and Django.
diff --git a/docs/docs/django-mongodb-connector-design-document.md b/docs/docs/django-mongodb-connector-design-document.md
index 8ae1e86821c416fe7372774f04cd705f2bb37d7a..db9585c8cbc5cc84c6069764aaa5756fb032c585 100644
--- a/docs/docs/django-mongodb-connector-design-document.md
+++ b/docs/docs/django-mongodb-connector-design-document.md
@@ -1,5 +1,5 @@
---
-title: Django MongoDB connector design document
+title: Django and MongoDB Connector Design
permalink: /django-mongodb-connector-design-document/
---
diff --git a/docs/docs/djongo-deep-dive.md b/docs/docs/djongo-deep-dive.md
new file mode 100644
index 0000000000000000000000000000000000000000..9eb184dd6392d03391fac407202d63070af8f76f
--- /dev/null
+++ b/docs/docs/djongo-deep-dive.md
@@ -0,0 +1,250 @@
+---
+title: Django and MongoDB connector
+permalink: "/djongo-deep-dive/"
+---
+
+
+## Database configuration
+
+The `settings.py` supports (but is not limited to) the following options:
+
+```python
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'djongo',
+ 'NAME': 'your-db-name',
+ 'ENFORCE_SCHEMA': False,
+ 'CLIENT': {
+ 'host': 'host-name or ip address',
+ 'port': port_number,
+ 'username': 'db-username',
+ 'password': 'password',
+ 'authSource': 'db-name',
+ 'authMechanism': 'SCRAM-SHA-1'
+ }
+ 'LOGGING': {
+ 'version': 1,
+ 'loggers': {
+ 'djongo': {
+ 'level': 'DEBUG',
+ 'propogate': False,
+ }
+ },
+ },
+ }
+ }
+```
+
+Attribute | Value | Description
+---------|------|-------------
+ENGINE | djongo | The MongoDB connection engine for interfacing with Django.
+ENFORCE_SCHEMA | True | Ensures that the model schema and database schema are exactly the same. Raises `Migration Error` in case of discrepancy.
+ENFORCE_SCHEMA | False | (Default) Implicitly creates collections. Returns missing fields as `None` instead of raising an exception.
+NAME | your-db-name | Specify your database name. This field cannot be left empty.
+LOGGING | dict | A [dictConfig](https://docs.python.org/3.6/library/logging.config.html) for the type of logging to run on djongo.
+CLIENT | dict | A set of key-value pairs that will be passed directly to [`MongoClient`]((http://api.mongodb.com/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient)) as kwargs while creating a new client connection.
+
+All options except `ENGINE` and `ENFORCE_SCHEMA` are the same those listed in the [pymongo documentation](http://api.mongodb.com/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient).
+
+### Enforce schema
+
+MongoDB is *schemaless*, which means no schema rules are enforced by the database. You can add and exclude fields per entry and MongoDB will not complain. This can make life easier, especially when there are frequent changes to the data model. Take for example the `Blog` Model (version 1).
+
+```python
+class Blog(models.Model):
+ name = models.CharField(max_length=100)
+ tagline = models.TextField()
+```
+
+You can save several entries into the DB and later modify it to version 2:
+
+```python
+class Blog(models.Model):
+ name = models.CharField(max_length=100)
+ tagline = models.TextField()
+ description = models.TextField()
+```
+
+The modified Model can be saved **without running any migrations**.
+
+This works fine if you know what you are doing. Consider a query that retrieves entries belonging to both the 'older' model (with just 2 fields) and the current model. What will the value of `description` now be? To handle such scenarios Djongo comes with the `ENFORCE_SCHEMA` option.
+
+When connecting to Djongo you can set `ENFORCE_SCHEMA: True`. In this case, a `MigrationError` will be raised when field values are missing from the retrieved documents. You can then check what went wrong.
+
+`ENFORCE_SCHEMA: False` works by silently setting the missing fields with the value `None`. If your app is programmed to expect this (which means it is not a bug) you can get away by not calling any migrations.
+
+## Use Django Admin to add documents
+
+The Django Admin interface can be used to work with MongoDB. Additionally, several MongoDB specific features are supported using [EmbeddedField](/djongo/using-django-with-mongodb-data-fields/), [ArrayField](/djongo/using-django-with-mongodb-array-field/) and other fields. Let’s say you want to create a blogging platform using Django with MongoDB as your backend. In your Blog `app/models.py` file define the `Blog` model:
+
+```python
+from djongo import models
+
+class Blog(models.Model):
+ name = models.CharField(max_length=100)
+ tagline = models.TextField()
+
+ class Meta:
+ abstract = True
+```
+
+Now ‘embed’ your `Blog` inside a `Entry` using the `EmbeddedField`:
+
+```python
+class Entry(models.Model):
+ blog = models.EmbeddedField(
+ model_container=Blog,
+ )
+
+ headline = models.CharField(max_length=255)
+```
+
+Register your `Entry` in `admin.py`:
+
+```python
+from django.contrib import admin
+from .models import Entry
+
+admin.site.register(Entry)
+```
+
+That’s it you are set! Fire up Django Admin on localhost:8000/admin/ and this is what you get:
+
+
+
+
+
+### Querying Embedded fields
+
+In the above example, to query all Entries with Blogs which have names that start with *Beatles*, use the following query:
+
+```python
+entries = Entry.objects.filter(blog__startswith={'name': 'Beatles'})
+```
+
+Refer to [Using Django with MongoDB data fields](/djongo/using-django-with-mongodb-data-fields/) for more details.
+
+## Djongo Manager
+
+Djongo Manager extends the functionality of the usual [Django Manager](https://docs.djangoproject.com/en/dev/topics/db/managers/). It gives direct access to the pymongo collection API. To use this manager define your manager as `DjongoManager` in the model.
+
+ ```python
+class Entry(models.Model):
+ blog = models.EmbeddedField(
+ model_container=Blog,
+ )
+ headline = models.CharField(max_length=255)
+ objects = models.DjongoManager()
+```
+
+Use it like the usual Django manager:
+
+```python
+post = Entry.objects.get(pk=p_key)
+```
+
+Will [get a model object](https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-a-single-object-with-get) having primary key `p_key`.
+
+### Using Pymongo commands
+
+MongoDB has powerful query syntax and `DjongoManager` lets you exploit it fully. For the above `Entry` model define a custom query function:
+
+```python
+class EntryView(DetailView):
+
+ def get_object(self, queryset=None):
+ index = [i for i in Entry.objects.mongo_aggregate([
+ {
+ '$match': {
+ 'headline': self.kwargs['path']
+ }
+ },
+ ])]
+
+ return index
+
+```
+
+You can directly *access any [pymongo](https://api.mongodb.com/python/current/) command* by prefixing `mongo_` to the command name. For example, to perform `aggregate` on the BlogPage collection (BlogPage is stored as a table in SQL or a collection in MongoDB) the function name becomes `mongo_aggregate`. To directly insert a document (instead of `.save()` a model) use `mongo_insert_one()`
+
+## GridFS
+
+To save files using [GridFS](https://docs.mongodb.com/manual/core/gridfs/) you must create a file storage instance of `GridFSStorage`:
+
+```python
+grid_fs_storage = GridFSStorage(collection='myfiles')
+```
+
+In your model define your field as `FileField` or `ImageField` as usual:
+
+```python
+avatar = models.ImageField(storage=grid_fs_storage, upload_to='')
+```
+
+Refer to [Using GridFSStorage](/djongo/using-django-with-mongodb-gridfs/) for more details.
+
+
+## Migrating an existing Django app to MongoDB
+
+When migrating an existing Django app to MongoDB, it is recommended to start a new database on MongoDB. For example, use `myapp-djongo-db` in your `settings.py` file.
+
+1. Into `settings.py` file of your project, add:
+
+ ```python
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'djongo',
+ 'NAME': 'myapp-djongo-db',
+ }
+ }
+ ```
+
+2. Run `manage.py makemigrations <myapp>` followed by `manage.py migrate`.
+3. Open Django Admin and you should find all Models defined in your app, showing up in the Admin.
+4. While the relevant collections have been created in MongoDB, they have have no data inside.
+5. Continue by inserting data into the collections manually, or use Django Admin for a GUI.
+
+## Setting up an existing MongoDB database on Django
+
+### The internal `__schema__` collection
+
+There is no concept of an AUTOINCREMENT field in MongoDB. Therefore, Djongo internally creates a `__schema__` collection to track such fields. The `__schema__` collection looks like:
+
+```python
+{
+ "_id" : ObjectId("5a5c3c87becdd9fe2fb255a9"),
+ "name" : "django_migrations",
+ "auto" : {
+ "field_names" : [
+ "id"
+ ],
+ "seq" : NumberInt(14)
+ }
+}
+```
+For every collection in the DB that has an autoincrement field, there is an corresponding entry in the `__schema__` collection. Running `manage.py migrate` automatically creates these entries.
+
+Now there are 2 approaches to setting up your existing data onto MongoDB:
+
+### Zero risk
+
+1. Start with a new database name in `settings.py`.
+2. If you have not already done so, define your models in the `models.py` file. The model names and model fields have to be exactly the same, as the existing data that you want to setup.
+3. Run `manage.py makemigrations <app_name>` followed by `manage.py migrate`.
+4. Now your empty DB should have a `__schema__` collection, and other collections defined in the `model.py` file.
+5. Copy collection data (of your custom models defined in `model.py`) to the new DB.
+6. In `__schema__` collection make sure that the `seq` number of your AUTOINCREMENT fields is **set to the latest value**. This should correspond to the document count for each model. For example, if your model has 16 entries (16 documents in the DB), then `seq` should be set as 16. Usually the AUTOINCREMENT field is called `id`.
+
+However, if you do not want to create a new database (and copy existing data into this new database), you can try this approach:
+
+### Medium risk
+
+1. Start with an empty database. You can always delete this later.
+2. Same as before.
+3. Same as before.
+4. Now copy the `__schema__` collection from the new database (from step1) to the existing database.
+5. Same as step 6 from before.
+6. You can now delete the database created in step 1.
+
+*You are now done setting up Django with MongoDB. Start using Django with MongoDB, like you would with any other database backend.*
+
diff --git a/docs/docs/creating-django-capped-models-using-mongodb.md b/docs/docs/djongonxt/creating-django-capped-models-using-mongodb.md
similarity index 100%
rename from docs/docs/creating-django-capped-models-using-mongodb.md
rename to docs/docs/djongonxt/creating-django-capped-models-using-mongodb.md
diff --git a/docs/docs/get-started.md b/docs/docs/get-started.md
index 95580b8b8913dc7512f3c14567fedaaa02a9f1ea..394bfd35f8a18e4d2ae7ce9efad73dad5060b29b 100644
--- a/docs/docs/get-started.md
+++ b/docs/docs/get-started.md
@@ -1,250 +1,158 @@
---
-title: Django and MongoDB connector
-permalink: "/get-started/"
+title: Integrating Django with MongoDB
+permalink: /integrating-django-with-mongodb/
+description: "Djongo is a python connector for using the Django ORM with MongoDB. Use MongoDB as a backend database for your Django project, without changing the Django ORM. Start using Django with MongoDB by adding just one line of code"
---
+Use MongoDB as a backend database for your Django project, without changing the Django ORM. Use Django Admin to add and modify documents in MongoDB. Start using Django with MongoDB by adding just one line of code.
-## Database configuration
+## Usage
+1. pip install djongo
+2. Into `settings.py` file of your project, add:
-The `settings.py` supports (but is not limited to) the following options:
+ ```python
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'djongo',
+ 'NAME': 'your-db-name',
+ }
+ }
+ ```
-```python
- DATABASES = {
- 'default': {
- 'ENGINE': 'djongo',
- 'NAME': 'your-db-name',
- 'ENFORCE_SCHEMA': False,
- 'CLIENT': {
- 'host': 'host-name or ip address',
- 'port': port_number,
- 'username': 'db-username',
- 'password': 'password',
- 'authSource': 'db-name',
- 'authMechanism': 'SCRAM-SHA-1'
- }
- 'LOGGING': {
- 'version': 1,
- 'loggers': {
- 'djongo': {
- 'level': 'DEBUG',
- 'propogate': False,
- }
- },
- },
- }
- }
-```
+3. YOU ARE SET! Have fun!
-Attribute | Value | Description
----------|------|-------------
-ENGINE | djongo | The MongoDB connection engine for interfacing with Django.
-ENFORCE_SCHEMA | True | Ensures that the model schema and database schema are exactly the same. Raises `Migration Error` in case of discrepancy.
-ENFORCE_SCHEMA | False | (Default) Implicitly creates collections. Returns missing fields as `None` instead of raising an exception.
-NAME | your-db-name | Specify your database name. This field cannot be left empty.
-LOGGING | dict | A [dictConfig](https://docs.python.org/3.6/library/logging.config.html) for the type of logging to run on djongo.
-CLIENT | dict | A set of key-value pairs that will be passed directly to [`MongoClient`]((http://api.mongodb.com/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient)) as kwargs while creating a new client connection.
+## Requirements
+1. Python 3.6 or higher.
+2. MongoDB 3.4 or higher.
+3. If your models use nested queries or sub querysets like:
-All options except `ENGINE` and `ENFORCE_SCHEMA` are the same those listed in the [pymongo documentation](http://api.mongodb.com/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient).
+ ```python
+ inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
+ entries = Entry.objects.filter(blog__name__in=inner_qs)
+ ```
+ MongoDB 3.6 or higher is required.
-### Enforce schema
+## Support
+[](https://www.patreon.com/nesdis/)
-MongoDB is *schemaless*, which means no schema rules are enforced by the database. You can add and exclude fields per entry and MongoDB will not complain. This can make life easier, especially when there are frequent changes to the data model. Take for example the `Blog` Model (version 1).
+I am inundated daily with your appreciation, queries and feature requests for Djongo. Djongo has grown into a highly complex project. To support the requests, I have decided to follow an organized approach.
-```python
-class Blog(models.Model):
- name = models.CharField(max_length=100)
- tagline = models.TextField()
-```
+Djongo as a project is at a stage where its development must be transformed into a sustained effort. Djongo has more than [1,000,000 downloads](https://pypistats.org/packages/djongo) on pypi and continues to grow. I am trying to establish a sustainable development model for the project, and would [love to hear your thoughts.](https://www.patreon.com/posts/to-only-take-22611438)
+
+Visit my [Patreon page](https://www.patreon.com/nesdis/) to make requests and for support. You can expect immediate answers to your questions.
-You can save several entries into the DB and later modify it to version 2:
+## How it works
+Djongo makes **zero changes** to the existing Django ORM framework, which means unnecessary bugs and security vulnerabilities do not crop up. It simply translates a SQL query string into a [MongoDB query document](https://docs.mongodb.com/manual/tutorial/query-documents/). As a result, all Django features, models, etc., work as is.
+
+Django contrib modules:
```python
-class Blog(models.Model):
- name = models.CharField(max_length=100)
- tagline = models.TextField()
- description = models.TextField()
+'django.contrib.admin',
+'django.contrib.auth',
+'django.contrib.sessions',
```
+and others... fully supported.
+
+## What you get
+Djongo ensures that you:
-The modified Model can be saved **without running any migrations**.
+ * Reuse Django Models/ORM.
+ * Work with the original Django variant.
+ * Future proof your code.
+ * Atomic SQL JOIN operations.
+
+Get [expert support](https://www.patreon.com/nesdis) for complex projects.
-This works fine if you know what you are doing. Consider a query that retrieves entries belonging to both the 'older' model (with just 2 fields) and the current model. What will the value of `description` now be? To handle such scenarios Djongo comes with the `ENFORCE_SCHEMA` option.
+## Rapid Prototyping
+Djongo lets you rapidly develop and evolve your app models. Modifying your models is **much faster** with Djongo compared to traditional Django ORM. Since MongoDB is a schema-less database, every time you redefine a model, MongoDB does not expect you to redefine the schema.
-When connecting to Djongo you can set `ENFORCE_SCHEMA: True`. In this case, a `MigrationError` will be raised when field values are missing from the retrieved documents. You can then check what went wrong.
+### Goodbye Migrations
+With Djongo you **permanently say goodbye** to Django Migrations. To enable migration free model evolution simply set `ENFORCE_SCHEMA: False` in your database configuration. Djongo no longer interprets SQL DDL statements (example CREATE TABLE) to emit pymongo `create_collection` commands. With `ENFORCE_SCHEMA: False` collections are created implicitly, on the fly.
-`ENFORCE_SCHEMA: False` works by silently setting the missing fields with the value `None`. If your app is programmed to expect this (which means it is not a bug) you can get away by not calling any migrations.
+## Data security and integrity checks
+Djongo allows for checks on data fields before they are saved to the database. Running the correct integrity checks and field value validators before writing data into the database is important.
-## Use Django Admin to add documents
-The Django Admin interface can be used to work with MongoDB. Additionally, several MongoDB specific features are supported using [EmbeddedField](/djongo/using-django-with-mongodb-data-fields/), [ArrayField](/djongo/using-django-with-mongodb-array-field/) and other fields. Let’s say you want to create a blogging platform using Django with MongoDB as your backend. In your Blog `app/models.py` file define the `Blog` model:
+### Validators
+Apply validators to each field before they are saved.
```python
+from django.core.exceptions import ValidationError
+from django.utils.translation import gettext_lazy as _
from djongo import models
+from django.core.validators import URLValidator
-class Blog(models.Model):
- name = models.CharField(max_length=100)
- tagline = models.TextField()
+def script_injection(value):
+ if value.find('<script>') != -1:
+ raise ValidationError(_('Script injection in %(value)s'),
+ params={'value': value})
+class Address(models.Model)
+ city = models.CharField(max_length=50)
+ homepage = models.URLField(validators=[URLValidator, script_injection])
class Meta:
- abstract = True
-```
-
-Now ‘embed’ your `Blog` inside a `Entry` using the `EmbeddedField`:
+ abstract=True
-```python
class Entry(models.Model):
- blog = models.EmbeddedField(
- model_container=Blog,
- )
-
- headline = models.CharField(max_length=255)
+ _id = models.ObjectIdField()
+ address = models.EmbeddedField(model_container=Address)
```
-Register your `Entry` in `admin.py`:
+### Integrity checks
```python
-from django.contrib import admin
-from .models import Entry
-
-admin.site.register(Entry)
-```
-
-That’s it you are set! Fire up Django Admin on localhost:8000/admin/ and this is what you get:
-
-
-
-
-
-### Querying Embedded fields
-
-In the above example, to query all Entries with Blogs which have names that start with *Beatles*, use the following query:
-
-```python
-entries = Entry.objects.filter(blog__startswith={'name': 'Beatles'})
-```
-
-Refer to [Using Django with MongoDB data fields](/djongo/using-django-with-mongodb-data-fields/) for more details.
-
-## Djongo Manager
-
-Djongo Manager extends the functionality of the usual [Django Manager](https://docs.djangoproject.com/en/dev/topics/db/managers/). It gives direct access to the pymongo collection API. To use this manager define your manager as `DjongoManager` in the model.
-
- ```python
class Entry(models.Model):
- blog = models.EmbeddedField(
- model_container=Blog,
- )
- headline = models.CharField(max_length=255)
- objects = models.DjongoManager()
+ _id = models.ObjectIdField()
+ address = models.EmbeddedField(model_container=Address,
+ null=False,
+ blank=False)
```
-Use it like the usual Django manager:
+By setting `null=False, blank=False` in `EmbeddedField`, missing values are never stored.
-```python
-post = Entry.objects.get(pk=p_key)
-```
+<!--
+## Using MongoDB fields
-Will [get a model object](https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-a-single-object-with-get) having primary key `p_key`.
+## Simplify complex queries
-### Using Pymongo commands
+## Django Admin
-MongoDB has powerful query syntax and `DjongoManager` lets you exploit it fully. For the above `Entry` model define a custom query function:
+-->
-```python
-class EntryView(DetailView):
+## DjongoNxt
- def get_object(self, queryset=None):
- index = [i for i in Entry.objects.mongo_aggregate([
- {
- '$match': {
- 'headline': self.kwargs['path']
- }
- },
- ])]
+> Features supported in DjongoNxt are not a part of the standard Djongo package. Visit the [sponsors page](https://www.patreon.com/nesdis/) for more information.
- return index
+DjongoNxt is a Django and MongoDB connector for full featured database usage. It provides many features of MongoDB enabled through Django. It comes with support for:
-```
+### Indexes
-You can directly *access any [pymongo](https://api.mongodb.com/python/current/) command* by prefixing `mongo_` to the command name. For example, to perform `aggregate` on the BlogPage collection (BlogPage is stored as a table in SQL or a collection in MongoDB) the function name becomes `mongo_aggregate`. To directly insert a document (instead of `.save()` a model) use `mongo_insert_one()`
+Support for all indexes provided by MongoDB, for example 2dSphere Index, Text Index and Compound Indexes.
-## GridFS
+### Model Query
-To save files using [GridFS](https://docs.mongodb.com/manual/core/gridfs/) you must create a file storage instance of `GridFSStorage`:
+Support for GeoSpatial Queries and Tailable Cursors.
-```python
-grid_fs_storage = GridFSStorage(collection='myfiles')
-```
+### Model Update
-In your model define your field as `FileField` or `ImageField` as usual:
+Unordered and Ordered Bulk Writes.
-```python
-avatar = models.ImageField(storage=grid_fs_storage, upload_to='')
-```
+### Database Transactions
-Refer to [Using GridFSStorage](/djongo/using-django-with-mongodb-gridfs/) for more details.
+Atomic multi document transactions with commit and rollback support.
+### Schema Validation and Model Creation
-## Migrating an existing Django app to MongoDB
+Automatic JSON Schema validation document generation and options to add Read and Write Concerns for the Models.
-When migrating an existing Django app to MongoDB, it is recommended to start a new database on MongoDB. For example, use `myapp-djongo-db` in your `settings.py` file.
+### Aggregation Operators
-1. Into `settings.py` file of your project, add:
+Support for various aggregation operators provided by MongoDB.
- ```python
- DATABASES = {
- 'default': {
- 'ENGINE': 'djongo',
- 'NAME': 'myapp-djongo-db',
- }
- }
- ```
+## Contribute
+
+If you think djongo is useful, **please share it** with the world! Your endorsements and online reviews will help get more support for this project.
-2. Run `manage.py makemigrations <myapp>` followed by `manage.py migrate`.
-3. Open Django Admin and you should find all Models defined in your app, showing up in the Admin.
-4. While the relevant collections have been created in MongoDB, they have have no data inside.
-5. Continue by inserting data into the collection directly, or from Django Admin.
-
-## Setting up an existing MongoDB database on Django
-
-### The internal `__schema__` collection
-
-There is no concept of an AUTOINCREMENT field in MongoDB. Therefore, Djongo internally creates a `__schema__` collection to track such fields. The `__schema__` collection looks like:
-
-```python
-{
- "_id" : ObjectId("5a5c3c87becdd9fe2fb255a9"),
- "name" : "django_migrations",
- "auto" : {
- "field_names" : [
- "id"
- ],
- "seq" : NumberInt(14)
- }
-}
-```
-For every collection in the DB that has an autoincrement field, there is an corresponding entry in the `__schema__` collection. Running `manage.py migrate` automatically creates these entries.
-
-Now there are 2 approaches to setting up your existing data onto MongoDB:
-
-### Zero risk
-
-1. Start with a new database name in `settings.py`.
-2. If you have not already done so, define your models in the `models.py` file. The model names and model fields have to be exactly the same, as the existing data that you want to setup.
-3. Run `manage.py makemigrations <app_name>` followed by `manage.py migrate`.
-4. Now your empty DB should have a `__schema__` collection, and other collections defined in the `model.py` file.
-5. Copy collection data (of your custom models defined in `model.py`) to the new DB.
-6. In `__schema__` collection make sure that the `seq` number of your AUTOINCREMENT fields is **set to the latest value**. This should correspond to the document count for each model. For example, if your model has 16 entries (16 documents in the DB), then `seq` should be set as 16. Usually the AUTOINCREMENT field is called `id`.
-
-However, if you do not want to create a new database (and copy existing data into this new database), you can try this approach:
-
-### Medium risk
-
-1. Start with an empty database. You can always delete this later.
-2. Same as before.
-3. Same as before.
-4. Now copy the `__schema__` collection from the new database (from step1) to the existing database.
-5. Same as step 6 from before.
-6. You can now delete the database created in step 1.
-
-*You are now done setting up Django with MongoDB. Start using Django with MongoDB, like you would with any other database backend.*
-
+You can contribute to the source code or the documentation by creating a simple pull request! You may want to refer to the design documentation to get an idea on how [Django MongoDB connector](/djongo/django-mongodb-connector-design-document/) is implemented.
+
+Please contribute to the continued development and success of Djongo by [making a donation](https://www.patreon.com/nesdis/).
\ No newline at end of file
diff --git a/docs/docs/home.md b/docs/docs/home.md
index 277225776844509449951abe6777fb36e592dc1e..352a4a2d36349600962b8704c364857056b66223 100644
--- a/docs/docs/home.md
+++ b/docs/docs/home.md
@@ -3,7 +3,7 @@ permalink: /
layout: splash
title: "Django MongoDB connector"
excerpt: "Djongo"
-description: "Djongo is a python Object Document Mapper (ODM) to be used with Django and MongoDB. Use Django Admin to directly add and modify documents stored in MongoDB. Use other contrib modules such as Auth and Sessions without any changes"
+description: "Djongo is a python connector for using the Django ORM with MongoDB. Use Django Admin to directly add and modify documents stored in MongoDB. Use other contrib modules such as Auth and Sessions without any changes"
header:
overlay_image: /assets/images/landing-banner3.jpg
diff --git a/docs/docs/integrating-django-with-mongodb.md b/docs/docs/integrating-django-with-mongodb.md
deleted file mode 100644
index 6793517597187966c30d9eb14011a7ea018f6469..0000000000000000000000000000000000000000
--- a/docs/docs/integrating-django-with-mongodb.md
+++ /dev/null
@@ -1,164 +0,0 @@
----
-title: Integrating Django with MongoDB
-permalink: /integrating-django-with-mongodb/
----
-
-Use MongoDB as a backend database for your Django project, without changing the Django ORM. Use the Django Admin app to add and modify documents in MongoDB.
-
-## Usage
-
-1. pip install djongo
-2. Into `settings.py` file of your project, add:
-
- ```python
- DATABASES = {
- 'default': {
- 'ENGINE': 'djongo',
- 'NAME': 'your-db-name',
- }
- }
- ```
-
-3. Run `manage.py makemigrations <app_name>` followed by `manage.py migrate` (ONLY the first time to create collections in MongoDB)
-4. YOU ARE SET! Have fun!
-
-## Requirements
-
-1. Python 3.6 or higher.
-2. MongoDB 3.4 or higher.
-3. If your models use nested queries or sub querysets like:
-
- ```python
- inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
- entries = Entry.objects.filter(blog__name__in=inner_qs)
- ```
- MongoDB 3.6 or higher is required.
-
-## Support
-
-[](https://www.patreon.com/nesdis/)
-
-I am inundated daily with your appreciation, queries and feature requests for Djongo. Djongo has grown into a highly complex project. To support the requests, I have decided to follow an organized approach.
-
-Djongo as a project is at a stage where its development must be transformed into a sustained effort. Djongo has more than [1,000,000 downloads](https://pypistats.org/packages/djongo) on pypi and continues to grow. I am trying to establish a sustainable development model for the project, and would [love to hear your thoughts.](https://www.patreon.com/posts/to-only-take-22611438)
-
-Visit my [Patreon page](https://www.patreon.com/nesdis/) to make requests and for support. You can expect immediate answers to your questions.
-
-## How it works
-
-Djongo makes **zero changes** to the existing Django ORM framework, which means unnecessary bugs and security vulnerabilities do not crop up. It simply translates a SQL query string into a [MongoDB query document](https://docs.mongodb.com/manual/tutorial/query-documents/). As a result, all Django features, models, etc., work as is.
-
-Django contrib modules:
-
-```python
-'django.contrib.admin',
-'django.contrib.auth',
-'django.contrib.sessions',
-```
-and others... fully supported.
-
-## What you get
-
-Djongo ensures that you:
-
- * Reuse Django Models/ORM
- * Work with the original Django variant
- * Future proof your code
- * Atomic SQL JOIN operations
-
-Get [expert support](https://www.patreon.com/nesdis) for complex projects.
-
-
-## Contribute
-
-If you think djongo is useful, **please share it** with the world! Your endorsements and online reviews will help get more support for this project.
-
-You can contribute to the source code or the documentation by creating a simple pull request! You may want to refer to the design documentation to get an idea on how [Django MongoDB connector](/djongo/django-mongodb-connector-design-document/) is implemented.
-
-Please contribute to the continued development and success of Djongo by [making a donation](https://www.patreon.com/nesdis/).
-
-## Data validation and integrity checks
-Djongo allows for checks on data fields before they are saved to the database. Running accurate integrity checks and field value validators before writing data into the database is extremely important.
-
-
-### Validators
-Apply validators on each of the field values before they are saved.
-
-
-### Integrity checks
-
-```python
-class Entry(models.Model):
- _id = models.ObjectIdField()
- blog = models.EmbeddedField(
- model_container=Blog,
- null=True
- )
-```
-## Rapid Prototyping
-
-### Goodbye Migrations
-
-## Using MongoDB fields
-
-## Simplify complex queries
-
-## Django Admin
-
-## Data security and integrity checks
-Djongo allows for checks on data fields before they are saved to the database. Running accurate integrity checks and field value validators before writing data into the database is extremely important.
-
-
-### Validators
-Apply validators on each of the field values before they are saved.
-
-
-### Integrity checks
-
-```python
-class Entry(models.Model):
- _id = models.ObjectIdField()
- blog = models.EmbeddedField(
- model_container=Blog,
- null=True
- )
-```
-## Rapid Prototyping
-
-### Goodbye Migrations
-
-## Using MongoDB fields
-
-## Simplify complex queries
-
-## Django Admin
-
-## DjongoNxt
-
-> Features supported in DjongoNxt are not a part of the standard Djongo package. Visit the [sponsors page](https://www.patreon.com/nesdis/) for more information.
-
-DjongoNxt is a Django and MongoDB connector for full featured database usage. It provides many features of MongoDB enabled through Django. It comes with support for:
-
-### Indexes
-
-Support for all indexes provided by MongoDB, for example 2dSphere Index, Text Index and Compound Indexes.
-
-### Model Query
-
-Support for GeoSpatial Queries and Tailable Cursors.
-
-### Model Update
-
-Unordered and Ordered Bulk Writes.
-
-### Database Transactions
-
-Atomic multi document transactions with commit and rollback support.
-
-### Schema Validation and Model Creation
-
-Automatic JSON Schema validation document generation and options to add Read and Write Concerns for the Models.
-
-### Aggregation Operators
-
-Support for various aggregation operators provided by MongoDB.