From e1586f403d70f15fcf0d9686742c5bcdf6bc9520 Mon Sep 17 00:00:00 2001 From: Jib Date: Fri, 17 Jan 2025 00:31:48 -0500 Subject: [PATCH 1/6] Revised README --- DEV_NOTES.md | 239 ++++++++++++++++++++++++++++++++++++++ README.md | 318 ++++++++++++++++++++++----------------------------- 2 files changed, 374 insertions(+), 183 deletions(-) create mode 100644 DEV_NOTES.md diff --git a/DEV_NOTES.md b/DEV_NOTES.md new file mode 100644 index 000000000..b44891281 --- /dev/null +++ b/DEV_NOTES.md @@ -0,0 +1,239 @@ +# Developer Details + +### Specifying the default primary key field + +In your Django settings, you must specify that all models should use +`ObjectIdAutoField`. + +You can create a new project that's configured based on these steps using a +project template: + +```bash +$ django-admin startproject mysite --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip +``` +(where "5.0" matches the version of Django that you're using.) + +This template includes the following line in `settings.py`: + +```python +DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField" +``` + +But this setting won't override any apps that have an `AppConfig` that +specifies `default_auto_field`. For those apps, you'll need to create a custom +`AppConfig`. + +For example, the project template includes `/apps.py`: + +```python +from django.contrib.admin.apps import AdminConfig +from django.contrib.auth.apps import AuthConfig +from django.contrib.contenttypes.apps import ContentTypesConfig + + +class MongoAdminConfig(AdminConfig): + default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" + + +class MongoAuthConfig(AuthConfig): + default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" + + +class MongoContentTypesConfig(ContentTypesConfig): + default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" +``` + +Each app reference in the `INSTALLED_APPS` setting must point to the +corresponding ``AppConfig``. For example, instead of `'django.contrib.admin'`, +the template uses `'.apps.MongoAdminConfig'`. + +### Configuring migrations + +Because all models must use `ObjectIdAutoField`, each third-party and contrib app +you use needs to have its own migrations specific to MongoDB. + +For example, `settings.py` in the project template specifies: + +```python +MIGRATION_MODULES = { + "admin": "mongo_migrations.admin", + "auth": "mongo_migrations.auth", + "contenttypes": "mongo_migrations.contenttypes", +} +``` + +The project template includes these migrations, but you can generate them if +you're setting things up manually or if you need to create migrations for +third-party apps. For example: + +```console +$ python manage.py makemigrations admin auth contenttypes +Migrations for 'admin': + mongo_migrations/admin/0001_initial.py + - Create model LogEntry +... +``` + +### Creating Django applications + +Whenever you run `python manage.py startapp`, you must remove the line: + +`default_auto_field = 'django.db.models.BigAutoField'` + +from the new application's `apps.py` file (or change it to reference + `"django_mongodb_backend.fields.ObjectIdAutoField"`). + +Alternatively, you can use the following `startapp` template which includes +this change: + +```bash +$ python manage.py startapp myapp --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip +``` +(where "5.0" matches the version of Django that you're using.) + +### Configuring the `DATABASES` setting + +After you've set up a project, configure Django's `DATABASES` setting similar +to this: + +```python +DATABASES = { + "default": { + "ENGINE": "django_mongodb_backend", + "HOST": "mongodb+srv://cluster0.example.mongodb.net", + "NAME": "my_database", + "USER": "my_user", + "PASSWORD": "my_password", + "PORT": 27017, + "OPTIONS": { + # Example: + "retryWrites": "true", + "w": "majority", + "tls": "false", + }, + }, +} +``` + +For a localhost configuration, you can omit `HOST` or specify +`"HOST": "localhost"`. + +`HOST` only needs a scheme prefix for SRV connections (`mongodb+srv://`). A +`mongodb://` prefix is never required. + +`OPTIONS` is an optional dictionary of parameters that will be passed to +[`MongoClient`](https://pymongo.readthedocs.io/en/stable/api/pymongo/mongo_client.html). + +`USER`, `PASSWORD`, and `PORT` (if 27017) may also be optional. + +For a replica set or sharded cluster where you have multiple hosts, include +all of them in `HOST`, e.g. +`"mongodb://mongos0.example.com:27017,mongos1.example.com:27017"`. + +Alternatively, if you prefer to simply paste in a MongoDB URI rather than parse +it into the format above, you can use: + +```python +import django_mongodb_backend + +MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/myDatabase?retryWrites=true&w=majority&tls=false" +DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI) +``` + +This constructs a `DATABASES` setting equivalent to the first example. + +#### `django_mongodb_backend.parse_uri(uri, conn_max_age=0, test=None)` + +`parse_uri()` provides a few options to customize the resulting `DATABASES` +setting, but for maximum flexibility, construct `DATABASES` manually as +described above. + +- Use `conn_max_age` to configure [persistent database connections]( + https://docs.djangoproject.com/en/stable/ref/databases/#persistent-database-connections). +- Use `test` to provide a dictionary of [settings for test databases]( + https://docs.djangoproject.com/en/stable/ref/settings/#test). + +Congratulations, your project is ready to go! + +## Notes on Django QuerySets + +* `QuerySet.explain()` supports the [`comment` and `verbosity` options]( + https://www.mongodb.com/docs/manual/reference/command/explain/#command-fields). + + Example: `QuerySet.explain(comment="...", verbosity="...")` + + Valid values for `verbosity` are `"queryPlanner"` (default), + `"executionStats"`, and `"allPlansExecution"`. + +## Known issues and limitations + +- The following `QuerySet` methods aren't supported: + - `bulk_update()` + - `dates()` + - `datetimes()` + - `distinct()` + - `extra()` + - `prefetch_related()` + +- `QuerySet.delete()` and `update()` do not support queries that span multiple + collections. + +- `DateTimeField` doesn't support microsecond precision, and correspondingly, + `DurationField` stores milliseconds rather than microseconds. + +- The following database functions aren't supported: + - `Chr` + - `ExtractQuarter` + - `MD5` + - `Now` + - `Ord` + - `Pad` + - `Repeat` + - `Reverse` + - `Right` + - `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512` + - `Sign` + +- The `tzinfo` parameter of the `Trunc` database functions doesn't work + properly because MongoDB converts the result back to UTC. + +- When querying `JSONField`: + - There is no way to distinguish between a JSON "null" (represented by + `Value(None, JSONField())`) and a SQL null (queried using the `isnull` + lookup). Both of these queries return both of these nulls. + - Some queries with `Q` objects, e.g. `Q(value__foo="bar")`, don't work + properly, particularly with `QuerySet.exclude()`. + - Filtering for a `None` key, e.g. `QuerySet.filter(value__j=None)` + incorrectly returns objects where the key doesn't exist. + - You can study the skipped tests in `DatabaseFeatures.django_test_skips` for + more details on known issues. + +- Due to the lack of ability to introspect MongoDB collection schema, + `migrate --fake-initial` isn't supported. + + +### Debug logging + +To troubleshoot MongoDB connectivity issues, you can enable [PyMongo's logging]( +https://pymongo.readthedocs.io/en/stable/examples/logging.html) using +[Django's `LOGGING` setting](https://docs.djangoproject.com/en/stable/topics/logging/). + +This is a minimal `LOGGING` setting that enables PyMongo's `DEBUG` logging: + +```python +LOGGING = { + "version": 1, + "disable_existing_loggers": False, + "handlers": { + "console": { + "class": "logging.StreamHandler", + }, + }, + "loggers": { + "pymongo": { + "handlers": ["console"], + "level": "DEBUG", + }, + }, +} +``` diff --git a/README.md b/README.md index defd6e661..abb07bc31 100644 --- a/README.md +++ b/README.md @@ -4,247 +4,199 @@ This backend is currently in development and is not advised for Production workf changes may be made without notice. We welcome your feedback as we continue to explore and build. The best way to share this is via our [MongoDB Community Forum](https://www.mongodb.com/community/forums/tag/python) -## Install and usage +## Install The development version of this package supports Django 5.0.x. To install it: -`pip install git+https://github.com/mongodb-labs/django-mongodb-backend` +`pip install django-mongodb-backend` -### Specifying the default primary key field +## Get Started -In your Django settings, you must specify that all models should use -`ObjectIdAutoField`. +This tutorial shows you how to create a Django app, connect to a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster. -You can create a new project that's configured based on these steps using a -project template: +### Start a Project -```bash -$ django-admin startproject mysite --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip -``` -(where "5.0" matches the version of Django that you're using.) - -This template includes the following line in `settings.py`: +From your shell, run the following command to create a new Django project called example based on a custom template: -```python -DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField" +```bash +$ django-admin startproject example --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip ``` -But this setting won't override any apps that have an `AppConfig` that -specifies `default_auto_field`. For those apps, you'll need to create a custom -`AppConfig`. - -For example, the project template includes `/apps.py`: - -```python -from django.contrib.admin.apps import AdminConfig -from django.contrib.auth.apps import AuthConfig -from django.contrib.contenttypes.apps import ContentTypesConfig - - -class MongoAdminConfig(AdminConfig): - default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" +### Create a Connection String +Check out [Create a Connection String](https://deploy-preview-132--docs-pymongo.netlify.app/get-started/create-a-connection-string/) in our documentation to learn how to obtain a free MongoDB Atlas cluster. -class MongoAuthConfig(AuthConfig): - default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" +Once finished, your URI should look something like this: +```bash +mongodb+srv://:@samplecluster.jkiff1s.mongodb.net/?retryWrites=true&w=majority&appName=SampleCluster +``` +Replace the `` and `` placeholders with your database user's username and password. +Then, specify a connection to your example database from the Atlas sample datasets by adding it after the hostname, as shown in the following example: -class MongoContentTypesConfig(ContentTypesConfig): - default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" +```bash +mongodb+srv://:@samplecluster.jkiff1s.mongodb.net/?retryWrites=true&w=majority&appName=SampleCluster ``` -Each app reference in the `INSTALLED_APPS` setting must point to the -corresponding ``AppConfig``. For example, instead of `'django.contrib.admin'`, -the template uses `'.apps.MongoAdminConfig'`. +Replacing `` with your database name of choice. -### Configuring migrations -Because all models must use `ObjectIdAutoField`, each third-party and contrib app -you use needs to have its own migrations specific to MongoDB. +### Connect to the Database -For example, `settings.py` in the project template specifies: +Navigate to your `example/settings.py` file and find the variable named `DATABASES` Replace the `DATABASES` setting with this: ```python -MIGRATION_MODULES = { - "admin": "mongo_migrations.admin", - "auth": "mongo_migrations.auth", - "contenttypes": "mongo_migrations.contenttypes", +DATABASES = { + "default": django_mongodb_backend.parse_uri(""), } ``` -The project template includes these migrations, but you can generate them if -you're setting things up manually or if you need to create migrations for -third-party apps. For example: +Where `` is your connection string from the previous step. -```console -$ python manage.py makemigrations admin auth contenttypes -Migrations for 'admin': - mongo_migrations/admin/0001_initial.py - - Create model LogEntry -... +### Start the Server +To verify that you installed Django MongoDB Backend and correctly configured your project, run the following command from your project root: +```bash +python manage.py runserver ``` +Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" message and an image of a rocket. -### Creating Django applications - -Whenever you run `python manage.py startapp`, you must remove the line: - -`default_auto_field = 'django.db.models.BigAutoField'` - -from the new application's `apps.py` file (or change it to reference - `"django_mongodb_backend.fields.ObjectIdAutoField"`). +Once you've done that, you'll see messages saying you haven't run migrations yet. Make sure to run this command: +```bash +python manage.py migrate +``` +### Create an app +An app is a web application that does something – e.g., a blog system, a database of public records or a small poll app. -Alternatively, you can use the following `startapp` template which includes -this change: +From your project's root directory, run the following command to create a new Django app called polls based on a custom template: ```bash -$ python manage.py startapp myapp --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip +python manage.py startapp polls --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip ``` -(where "5.0" matches the version of Django that you're using.) -### Configuring the `DATABASES` setting - -After you've set up a project, configure Django's `DATABASES` setting similar -to this: +This will register a new `polls` app in your project, and provide the necessary files to have your polls app be a registered in `INSTALLED_APPS` within `example/settings.py` setting. It’ll look like this: ```python -DATABASES = { - "default": { - "ENGINE": "django_mongodb_backend", - "HOST": "mongodb+srv://cluster0.example.mongodb.net", - "NAME": "my_database", - "USER": "my_user", - "PASSWORD": "my_password", - "PORT": 27017, - "OPTIONS": { - # Example: - "retryWrites": "true", - "w": "majority", - "tls": "false", - }, - }, -} +INSTALLED_APPS = [ + "polls.apps.PollsConfig", + 'example.apps.MongoAdminConfig', + 'example.apps.MongoAuthConfig', + 'example.apps.MongoContentTypesConfig', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.staticfiles', +] ``` -For a localhost configuration, you can omit `HOST` or specify -`"HOST": "localhost"`. - -`HOST` only needs a scheme prefix for SRV connections (`mongodb+srv://`). A -`mongodb://` prefix is never required. - -`OPTIONS` is an optional dictionary of parameters that will be passed to -[`MongoClient`](https://pymongo.readthedocs.io/en/stable/api/pymongo/mongo_client.html). +### Make a Django Model -`USER`, `PASSWORD`, and `PORT` (if 27017) may also be optional. - -For a replica set or sharded cluster where you have multiple hosts, include -all of them in `HOST`, e.g. -`"mongodb://mongos0.example.com:27017,mongos1.example.com:27017"`. - -Alternatively, if you prefer to simply paste in a MongoDB URI rather than parse -it into the format above, you can use: +Go to `example/polls/models.py` and paste this example code to creat a `Poll` and `Question` model. ```python -import django_mongodb_backend +from django.db import models -MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/myDatabase?retryWrites=true&w=majority&tls=false" -DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI) -``` -This constructs a `DATABASES` setting equivalent to the first example. +class Question(models.Model): + question_text = models.CharField(max_length=200) + pub_date = models.DateTimeField("date published") -#### `django_mongodb_backend.parse_uri(uri, conn_max_age=0, test=None)` -`parse_uri()` provides a few options to customize the resulting `DATABASES` -setting, but for maximum flexibility, construct `DATABASES` manually as -described above. - -- Use `conn_max_age` to configure [persistent database connections]( - https://docs.djangoproject.com/en/stable/ref/databases/#persistent-database-connections). -- Use `test` to provide a dictionary of [settings for test databases]( - https://docs.djangoproject.com/en/stable/ref/settings/#test). +class Choice(models.Model): + question = models.ForeignKey(Question, on_delete=models.CASCADE) + choice_text = models.CharField(max_length=200) + votes = models.IntegerField(default=0) +``` -Congratulations, your project is ready to go! +With your new models defined and configs set, call the `makemigrations` command from the root of your directory. +```bash +python manage.py makemigrations polls +``` -## Notes on Django QuerySets +### Query your data +Hop into the interactive Python shell provided by the Django api with this command: +```bash +python manage.py shell +``` -* `QuerySet.explain()` supports the [`comment` and `verbosity` options]( - https://www.mongodb.com/docs/manual/reference/command/explain/#command-fields). +Within the shell, play around with creating, reading, updating, and deleting your models. Here's a few steps to start (provided by django tutorial): +```python +>>> from polls.models import Choice, Question # Import the model classes we just wrote. + +# No questions are in the system yet. +>>> Question.objects.all() + + +# Create a new Question. +# Support for time zones is enabled in the default settings file, so +# Django expects a datetime with tzinfo for pub_date. Use timezone.now() +# instead of datetime.datetime.now() and it will do the right thing. +>>> from django.utils import timezone +>>> q = Question(question_text="What's new?", pub_date=timezone.now()) + +# Save the object into the database. You have to call save() explicitly. +>>> q.save() + +# Now it has an ID. +>>> q.id +1 + +# Access model field values via Python attributes. +>>> q.question_text +"What's new?" +>>> q.pub_date +datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=datetime.timezone.utc) + +# Change values by changing the attributes, then calling save(). +>>> q.question_text = "What's up?" +>>> q.save() + +# objects.all() displays all the questions in the database. +>>> Question.objects.all() +]> +``` - Example: `QuerySet.explain(comment="...", verbosity="...")` +Check out the Django [database API](https://docs.djangoproject.com/en/5.1/topics/db/queries/) documentation for more information on queries. - Valid values for `verbosity` are `"queryPlanner"` (default), - `"executionStats"`, and `"allPlansExecution"`. +### View the Admin Dashboard +1. Make the poll app modifiable in the admin site. Route to the `polls/admin.py` file and include this code: + ```python + from django.contrib import admin -## Known issues and limitations + from .models import Question -- The following `QuerySet` methods aren't supported: - - `bulk_update()` - - `dates()` - - `datetimes()` - - `distinct()` - - `extra()` - - `prefetch_related()` + admin.site.register(Question) + ``` +2. Create a superuser. When prompted, enter your desired username, password, and email address. + ```bash + $ python manage.py createsuperuser + ``` +3. Start the Development Server + ```bash + $ python manage.py runserver + ``` +4. Open a web browser and go to “/admin/” on your local domain – e.g., http://127.0.0.1:8000/admin/. Login and explore the free admin functionality! -- `QuerySet.delete()` and `update()` do not support queries that span multiple - collections. +### Congrats! You've made your first Django MongoDB Backend Project -- `DateTimeField` doesn't support microsecond precision, and correspondingly, - `DurationField` stores milliseconds rather than microseconds. +Check back soon as we aim to provide more links that will dive deeper into our library! -- The following database functions aren't supported: - - `Chr` - - `ExtractQuarter` - - `MD5` - - `Now` - - `Ord` - - `Pad` - - `Repeat` - - `Reverse` - - `Right` - - `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512` - - `Sign` + -- The `tzinfo` parameter of the `Trunc` database functions doesn't work - properly because MongoDB converts the result back to UTC. +### Issues & Help -- When querying `JSONField`: - - There is no way to distinguish between a JSON "null" (represented by - `Value(None, JSONField())`) and a SQL null (queried using the `isnull` - lookup). Both of these queries return both of these nulls. - - Some queries with `Q` objects, e.g. `Q(value__foo="bar")`, don't work - properly, particularly with `QuerySet.exclude()`. - - Filtering for a `None` key, e.g. `QuerySet.filter(value__j=None)` - incorrectly returns objects where the key doesn't exist. - - You can study the skipped tests in `DatabaseFeatures.django_test_skips` for - more details on known issues. +We're glad to have such a vibrant community of users of Django MongoDB Backend. We recommend seeking support for general questions through the MongoDB Community Forums. -- Due to the lack of ability to introspect MongoDB collection schema, - `migrate --fake-initial` isn't supported. +#### Bugs / Feature Requests +To report a bug or to request a new feature in Django MongoDB Backend, please open an issue in JIRA, our issue-management tool, using the following steps: -## Troubleshooting +1. [Create a JIRA account.](https://jira.mongodb.org/) -### Debug logging +2. Navigate to the [Python Integrations project](https://jira.mongodb.org/projects/INTPYTHON/). -To troubleshoot MongoDB connectivity issues, you can enable [PyMongo's logging]( -https://pymongo.readthedocs.io/en/stable/examples/logging.html) using -[Django's `LOGGING` setting](https://docs.djangoproject.com/en/stable/topics/logging/). +3. Click **Create Issue**. Please provide as much information as possible about the issue and the steps to reproduce it. -This is a minimal `LOGGING` setting that enables PyMongo's `DEBUG` logging: +Bug reports in JIRA for the Django MongoDB Backend project can be viewed by everyone. -```python -LOGGING = { - "version": 1, - "disable_existing_loggers": False, - "handlers": { - "console": { - "class": "logging.StreamHandler", - }, - }, - "loggers": { - "pymongo": { - "handlers": ["console"], - "level": "DEBUG", - }, - }, -} -``` +If you identify a security vulnerability in the driver or in any other MongoDB project, please report it according to the instructions found in [Create a Vulnerability Report](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report/). \ No newline at end of file From 3234a85aada0d6fcda3c5654dde561c737f4a9ba Mon Sep 17 00:00:00 2001 From: Jib Date: Mon, 27 Jan 2025 12:50:51 -0500 Subject: [PATCH 2/6] revised docs --- README.md | 191 ++++++++++++++++++++---------------------------------- 1 file changed, 70 insertions(+), 121 deletions(-) diff --git a/README.md b/README.md index abb07bc31..40943fa26 100644 --- a/README.md +++ b/README.md @@ -10,36 +10,25 @@ The development version of this package supports Django 5.0.x. To install it: `pip install django-mongodb-backend` -## Get Started +### Resources -This tutorial shows you how to create a Django app, connect to a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster. + Check back soon as we aim to provide more links that will dive deeper into our library! -### Start a Project - -From your shell, run the following command to create a new Django project called example based on a custom template: +* [Developer Notes](DEV_NOTES.md) -```bash -$ django-admin startproject example --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip -``` -### Create a Connection String +## Quickstart -Check out [Create a Connection String](https://deploy-preview-132--docs-pymongo.netlify.app/get-started/create-a-connection-string/) in our documentation to learn how to obtain a free MongoDB Atlas cluster. +This tutorial shows you how to create a Django project, connect to a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster. To read more, please check our MongoDB Backend for Django tutorials page. -Once finished, your URI should look something like this: -```bash -mongodb+srv://:@samplecluster.jkiff1s.mongodb.net/?retryWrites=true&w=majority&appName=SampleCluster -``` -Replace the `` and `` placeholders with your database user's username and password. +### Start a Project -Then, specify a connection to your example database from the Atlas sample datasets by adding it after the hostname, as shown in the following example: +From your shell, run the following command to create a new Django project called example based on a custom template: ```bash -mongodb+srv://:@samplecluster.jkiff1s.mongodb.net/?retryWrites=true&w=majority&appName=SampleCluster +$ django-admin startproject example --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip ``` -Replacing `` with your database name of choice. - ### Connect to the Database @@ -60,129 +49,89 @@ python manage.py runserver ``` Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" message and an image of a rocket. -Once you've done that, you'll see messages saying you haven't run migrations yet. Make sure to run this command: -```bash -python manage.py migrate -``` -### Create an app -An app is a web application that does something – e.g., a blog system, a database of public records or a small poll app. -From your project's root directory, run the following command to create a new Django app called polls based on a custom template: +## Capabilities of Django Backend for MongoDB -```bash -python manage.py startapp polls --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip -``` +- **Database Connectivity** + + - Directly tune MongoDB connection settings within your Django configuration\! + - Work against a persisted cloud instance of MongoDB for free\! -This will register a new `polls` app in your project, and provide the necessary files to have your polls app be a registered in `INSTALLED_APPS` within `example/settings.py` setting. It’ll look like this: -```python -INSTALLED_APPS = [ - "polls.apps.PollsConfig", - 'example.apps.MongoAdminConfig', - 'example.apps.MongoAuthConfig', - 'example.apps.MongoContentTypesConfig', - 'django.contrib.sessions', - 'django.contrib.messages', - 'django.contrib.staticfiles', -] -``` +- **Model MongoDB Documents Through Django’s ORM** + + - Translate Django model instances to MongoDB documents. + - Create new collections corresponding to models. + - Supports field validation, data storage, updating, and deletion. + - Maps Django's built-in fields to MongoDB data types. + - Provides new custom fields for arrays (ArrayField) and embedded documents (EmbeddedModelField). + - Supports core migration functionalities including creating, deleting, and updating indexes and collections -### Make a Django Model -Go to `example/polls/models.py` and paste this example code to creat a `Poll` and `Question` model. +- **Index Management** + + - Create single, compound, and unique indexes using Django Indexes + - Create MongoDB partial indexes in Django using Q notation. -```python -from django.db import models +- **Querying Data** + + - Querying API powered through the amazing MongoDB Aggregation Pipeline + - Supports most functions of the Django QuerySet API + - Support Query Annotations and common SQL AGGREGATE operators + - We support foreign keys and execute JOIN operations all in 1 database call + - Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet results\! -class Question(models.Model): - question_text = models.CharField(max_length=200) - pub_date = models.DateTimeField("date published") +- **Administrator Dashboard & Authentication** + + - Manage your data in Django’s admin site. + - Fully integrated with Django's authentication framework. + - Supports native user management features like creating users and sessions. -class Choice(models.Model): - question = models.ForeignKey(Question, on_delete=models.CASCADE) - choice_text = models.CharField(max_length=200) - votes = models.IntegerField(default=0) -``` -With your new models defined and configs set, call the `makemigrations` command from the root of your directory. -```bash -python manage.py makemigrations polls -``` +- **Management Commands** + + - Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more. -### Query your data -Hop into the interactive Python shell provided by the Django api with this command: -```bash -python manage.py shell -``` -Within the shell, play around with creating, reading, updating, and deleting your models. Here's a few steps to start (provided by django tutorial): -```python ->>> from polls.models import Choice, Question # Import the model classes we just wrote. - -# No questions are in the system yet. ->>> Question.objects.all() - - -# Create a new Question. -# Support for time zones is enabled in the default settings file, so -# Django expects a datetime with tzinfo for pub_date. Use timezone.now() -# instead of datetime.datetime.now() and it will do the right thing. ->>> from django.utils import timezone ->>> q = Question(question_text="What's new?", pub_date=timezone.now()) - -# Save the object into the database. You have to call save() explicitly. ->>> q.save() - -# Now it has an ID. ->>> q.id -1 - -# Access model field values via Python attributes. ->>> q.question_text -"What's new?" ->>> q.pub_date -datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=datetime.timezone.utc) - -# Change values by changing the attributes, then calling save(). ->>> q.question_text = "What's up?" ->>> q.save() - -# objects.all() displays all the questions in the database. ->>> Question.objects.all() -]> -``` +## Future Commitments of Django Backend for MongoDB + +- **Advanced Indexing** + + - Support for advanced index types like geospatial, text, and vector search indexes. + +- **Improved Data Modeling** + + - Support ArrayFields containing Embedded Models + - Support Collections with multiple Django Models + - Possible support for additional Django fields such as ImageField + + +- **Extended Querying Features** + + - Exploring smoother ways to allow users to use full-text search, vector search, or geospatial querying. + -Check out the Django [database API](https://docs.djangoproject.com/en/5.1/topics/db/queries/) documentation for more information on queries. +- **Enhanced Transactions Support** + + - Investigation and support for transactions, allowing features like `ATOMIC_REQUESTS` and `AUTOCOMMIT`. -### View the Admin Dashboard -1. Make the poll app modifiable in the admin site. Route to the `polls/admin.py` file and include this code: - ```python - from django.contrib import admin +- **Asynchronous Capabilities** + + - Evaluation and support for Django’s asynchronous callback functions. - from .models import Question - admin.site.register(Question) - ``` -2. Create a superuser. When prompted, enter your desired username, password, and email address. - ```bash - $ python manage.py createsuperuser - ``` -3. Start the Development Server - ```bash - $ python manage.py runserver - ``` -4. Open a web browser and go to “/admin/” on your local domain – e.g., http://127.0.0.1:8000/admin/. Login and explore the free admin functionality! +- **Performance Optimization** + + - Focus on performance tuning, especially concerning JOIN operations and ensure competitive performance relative to SQL databases. -### Congrats! You've made your first Django MongoDB Backend Project -Check back soon as we aim to provide more links that will dive deeper into our library! +- **Expanded Third-Party Library Support** + + - Vet our backend library works effortlessly with major Django Third-Party solutions - +These future capabilities are intended to enhance the functionality of the Django Backend for MongoDB as it progresses towards a General Availability (GA) release. If you have any more specific questions or need further details, feel free to ask\! ### Issues & Help From f869a3021f320a0d0f0fb069e9a2de4a767d45dd Mon Sep 17 00:00:00 2001 From: Jib Date: Tue, 28 Jan 2025 16:23:55 -0500 Subject: [PATCH 3/6] revisions to readme. Included limitations. removed marketing cruft --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 40943fa26..62a5c639f 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,7 @@ explore and build. The best way to share this is via our [MongoDB Community Foru The development version of this package supports Django 5.0.x. To install it: -`pip install django-mongodb-backend` - -### Resources - - Check back soon as we aim to provide more links that will dive deeper into our library! - -* [Developer Notes](DEV_NOTES.md) +`pip install django-mongodb-backend~=5.0.0` ## Quickstart @@ -52,12 +46,6 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess ## Capabilities of Django Backend for MongoDB -- **Database Connectivity** - - - Directly tune MongoDB connection settings within your Django configuration\! - - Work against a persisted cloud instance of MongoDB for free\! - - - **Model MongoDB Documents Through Django’s ORM** - Translate Django model instances to MongoDB documents. @@ -75,12 +63,11 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess - **Querying Data** - - - Querying API powered through the amazing MongoDB Aggregation Pipeline + - Supports most functions of the Django QuerySet API - Support Query Annotations and common SQL AGGREGATE operators - - We support foreign keys and execute JOIN operations all in 1 database call - - Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet results\! + Support foreign key usage and execute JOIN operations + - Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet resutts, - **Administrator Dashboard & Authentication** @@ -89,10 +76,64 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess - Fully integrated with Django's authentication framework. - Supports native user management features like creating users and sessions. +## Limitations of django-mongodb-backend -- **Management Commands** - - - Use commands like `migrate`, `makemigrations`, `flush`, `sqlmigrate`, many more. +- Database Variables `ATOMIC_REQUESTS`, `AUTOCOMMIT`, `CONN_HEALTH_CHECKS`, `TIME_ZONE` not supported +- No support for GeoDjango +- Functions such as `Chr`, `ExtractQuarter`, `MD5`, `Now`, `Ord`, `Pad`, `Repeat`, `Reverse`, `Right`, `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`, and `Sign`. +- The `tzinfo` parameter of the `Trunc` database functions does not work properly because MongoDB converts the result back to UTC. +- Schema Validation is not enforced. Refer to MongoDB documentation for how to enforce schema validation. +- Django DDL Transactions are not supported. +- The `migrate --fake-initial` command is not supported due to the inability to introspect MongoDB collection schema. +- The asynchronous functionality of the Django API has not yet been tested. +- `BSONRegExp` has no custom field class. It is best represented as a `CharField`. + + +#### **Model Limitations** + + - `$vectorSearch` and `$search` and Geospatial index creation through the Django Indexes API is not yet available. + - Updating indexes in `EmbeddedModels` do not work after the first table creation. + + - **ArrayField** + - Does not support `EmbeddedModel` within `ArrayField`. + + - **EmbeddedModel** + - Limited schema change support (no changing of embedded models). + - Embedded documents cannot take Django ForeignKeys. + - Arbitrary or untyped `EmbeddedModelField` is not supported. All fields must derive from an `EmbeddedModel` class. + + - **JSONField** + - There is no way to distinguish between a JSON "null" and a SQL null in specific queries. + - Some queries with Q objects, e.g., `Q(value__foo="bar")`, don't work properly, particularly with `QuerySet.exclude()`. + - Filtering for a `None` key, e.g., `QuerySet.filter(value__j=None)`, incorrectly returns objects where the key doesn't exist. + + - **DateTimeField** + - No support for microsecond granularity. + + - **DurationField**: + - Stores milliseconds rather than microseconds. + + - **Unavailable Fields**: + - `GeneratedField` + - `ImageField` + + +- **These QuerySet API methods do not work** + + - `distinct()` + - `dates()` + - `datetimes()` + - `prefetch_related()` + - `extra()` + - `QuerySet.delete()` and `update()` do not support queries that span multiple collections. + + +- **Django Management Commands that do not work** + - `createcachetable` + - `inspectdb` + - `optimizemigration` + - `sqlflush` + - `sqlsequencereset` ## Future Commitments of Django Backend for MongoDB @@ -133,6 +174,7 @@ Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" mess These future capabilities are intended to enhance the functionality of the Django Backend for MongoDB as it progresses towards a General Availability (GA) release. If you have any more specific questions or need further details, feel free to ask\! + ### Issues & Help We're glad to have such a vibrant community of users of Django MongoDB Backend. We recommend seeking support for general questions through the MongoDB Community Forums. From 846c98f879ba032a4756c3b286300174518159e9 Mon Sep 17 00:00:00 2001 From: Jib Date: Tue, 28 Jan 2025 18:33:25 -0500 Subject: [PATCH 4/6] removed DEV_NOTES and paired down README --- DEV_NOTES.md | 239 --------------------------------------------------- README.md | 158 ++++++++-------------------------- 2 files changed, 34 insertions(+), 363 deletions(-) delete mode 100644 DEV_NOTES.md diff --git a/DEV_NOTES.md b/DEV_NOTES.md deleted file mode 100644 index b44891281..000000000 --- a/DEV_NOTES.md +++ /dev/null @@ -1,239 +0,0 @@ -# Developer Details - -### Specifying the default primary key field - -In your Django settings, you must specify that all models should use -`ObjectIdAutoField`. - -You can create a new project that's configured based on these steps using a -project template: - -```bash -$ django-admin startproject mysite --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip -``` -(where "5.0" matches the version of Django that you're using.) - -This template includes the following line in `settings.py`: - -```python -DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField" -``` - -But this setting won't override any apps that have an `AppConfig` that -specifies `default_auto_field`. For those apps, you'll need to create a custom -`AppConfig`. - -For example, the project template includes `/apps.py`: - -```python -from django.contrib.admin.apps import AdminConfig -from django.contrib.auth.apps import AuthConfig -from django.contrib.contenttypes.apps import ContentTypesConfig - - -class MongoAdminConfig(AdminConfig): - default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" - - -class MongoAuthConfig(AuthConfig): - default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" - - -class MongoContentTypesConfig(ContentTypesConfig): - default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" -``` - -Each app reference in the `INSTALLED_APPS` setting must point to the -corresponding ``AppConfig``. For example, instead of `'django.contrib.admin'`, -the template uses `'.apps.MongoAdminConfig'`. - -### Configuring migrations - -Because all models must use `ObjectIdAutoField`, each third-party and contrib app -you use needs to have its own migrations specific to MongoDB. - -For example, `settings.py` in the project template specifies: - -```python -MIGRATION_MODULES = { - "admin": "mongo_migrations.admin", - "auth": "mongo_migrations.auth", - "contenttypes": "mongo_migrations.contenttypes", -} -``` - -The project template includes these migrations, but you can generate them if -you're setting things up manually or if you need to create migrations for -third-party apps. For example: - -```console -$ python manage.py makemigrations admin auth contenttypes -Migrations for 'admin': - mongo_migrations/admin/0001_initial.py - - Create model LogEntry -... -``` - -### Creating Django applications - -Whenever you run `python manage.py startapp`, you must remove the line: - -`default_auto_field = 'django.db.models.BigAutoField'` - -from the new application's `apps.py` file (or change it to reference - `"django_mongodb_backend.fields.ObjectIdAutoField"`). - -Alternatively, you can use the following `startapp` template which includes -this change: - -```bash -$ python manage.py startapp myapp --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip -``` -(where "5.0" matches the version of Django that you're using.) - -### Configuring the `DATABASES` setting - -After you've set up a project, configure Django's `DATABASES` setting similar -to this: - -```python -DATABASES = { - "default": { - "ENGINE": "django_mongodb_backend", - "HOST": "mongodb+srv://cluster0.example.mongodb.net", - "NAME": "my_database", - "USER": "my_user", - "PASSWORD": "my_password", - "PORT": 27017, - "OPTIONS": { - # Example: - "retryWrites": "true", - "w": "majority", - "tls": "false", - }, - }, -} -``` - -For a localhost configuration, you can omit `HOST` or specify -`"HOST": "localhost"`. - -`HOST` only needs a scheme prefix for SRV connections (`mongodb+srv://`). A -`mongodb://` prefix is never required. - -`OPTIONS` is an optional dictionary of parameters that will be passed to -[`MongoClient`](https://pymongo.readthedocs.io/en/stable/api/pymongo/mongo_client.html). - -`USER`, `PASSWORD`, and `PORT` (if 27017) may also be optional. - -For a replica set or sharded cluster where you have multiple hosts, include -all of them in `HOST`, e.g. -`"mongodb://mongos0.example.com:27017,mongos1.example.com:27017"`. - -Alternatively, if you prefer to simply paste in a MongoDB URI rather than parse -it into the format above, you can use: - -```python -import django_mongodb_backend - -MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/myDatabase?retryWrites=true&w=majority&tls=false" -DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI) -``` - -This constructs a `DATABASES` setting equivalent to the first example. - -#### `django_mongodb_backend.parse_uri(uri, conn_max_age=0, test=None)` - -`parse_uri()` provides a few options to customize the resulting `DATABASES` -setting, but for maximum flexibility, construct `DATABASES` manually as -described above. - -- Use `conn_max_age` to configure [persistent database connections]( - https://docs.djangoproject.com/en/stable/ref/databases/#persistent-database-connections). -- Use `test` to provide a dictionary of [settings for test databases]( - https://docs.djangoproject.com/en/stable/ref/settings/#test). - -Congratulations, your project is ready to go! - -## Notes on Django QuerySets - -* `QuerySet.explain()` supports the [`comment` and `verbosity` options]( - https://www.mongodb.com/docs/manual/reference/command/explain/#command-fields). - - Example: `QuerySet.explain(comment="...", verbosity="...")` - - Valid values for `verbosity` are `"queryPlanner"` (default), - `"executionStats"`, and `"allPlansExecution"`. - -## Known issues and limitations - -- The following `QuerySet` methods aren't supported: - - `bulk_update()` - - `dates()` - - `datetimes()` - - `distinct()` - - `extra()` - - `prefetch_related()` - -- `QuerySet.delete()` and `update()` do not support queries that span multiple - collections. - -- `DateTimeField` doesn't support microsecond precision, and correspondingly, - `DurationField` stores milliseconds rather than microseconds. - -- The following database functions aren't supported: - - `Chr` - - `ExtractQuarter` - - `MD5` - - `Now` - - `Ord` - - `Pad` - - `Repeat` - - `Reverse` - - `Right` - - `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512` - - `Sign` - -- The `tzinfo` parameter of the `Trunc` database functions doesn't work - properly because MongoDB converts the result back to UTC. - -- When querying `JSONField`: - - There is no way to distinguish between a JSON "null" (represented by - `Value(None, JSONField())`) and a SQL null (queried using the `isnull` - lookup). Both of these queries return both of these nulls. - - Some queries with `Q` objects, e.g. `Q(value__foo="bar")`, don't work - properly, particularly with `QuerySet.exclude()`. - - Filtering for a `None` key, e.g. `QuerySet.filter(value__j=None)` - incorrectly returns objects where the key doesn't exist. - - You can study the skipped tests in `DatabaseFeatures.django_test_skips` for - more details on known issues. - -- Due to the lack of ability to introspect MongoDB collection schema, - `migrate --fake-initial` isn't supported. - - -### Debug logging - -To troubleshoot MongoDB connectivity issues, you can enable [PyMongo's logging]( -https://pymongo.readthedocs.io/en/stable/examples/logging.html) using -[Django's `LOGGING` setting](https://docs.djangoproject.com/en/stable/topics/logging/). - -This is a minimal `LOGGING` setting that enables PyMongo's `DEBUG` logging: - -```python -LOGGING = { - "version": 1, - "disable_existing_loggers": False, - "handlers": { - "console": { - "class": "logging.StreamHandler", - }, - }, - "loggers": { - "pymongo": { - "handlers": ["console"], - "level": "DEBUG", - }, - }, -} -``` diff --git a/README.md b/README.md index 62a5c639f..140a083a3 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,36 @@ # Django MongoDB Backend + + This backend is currently in development and is not advised for Production workflows. Backwards incompatible changes may be made without notice. We welcome your feedback as we continue to -explore and build. The best way to share this is via our [MongoDB Community Forum](https://www.mongodb.com/community/forums/tag/python) +explore and build. The best way to share this is via our [MongoDB Community Forum](https://www.mongodb.com/community/forums/tag/python). ## Install -The development version of this package supports Django 5.0.x. To install it: +Use the version of django-mongodb-backend that corresponds to your version of +Django. For example, to get the latest compatible release for Django 5.0.x: -`pip install django-mongodb-backend~=5.0.0` +`pip install --pre django-mongodb-backend==5.0.*` +(Until the package is out of beta, you must use pip's `--pre` option.) -## Quickstart -This tutorial shows you how to create a Django project, connect to a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster. To read more, please check our MongoDB Backend for Django tutorials page. +## Quickstart -### Start a Project +### Start Project -From your shell, run the following command to create a new Django project called example based on a custom template: +From your shell, run the following command to create a new Django project +called example based on a custom template. Make sure the version referenced +from `django-mongodb-labs` corresponds to your version of Django similar +to the install stage. For example, this command works for Django 5.0.x: ```bash $ django-admin startproject example --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip ``` -### Connect to the Database +### Connect to the database Navigate to your `example/settings.py` file and find the variable named `DATABASES` Replace the `DATABASES` setting with this: @@ -34,9 +40,13 @@ DATABASES = { } ``` -Where `` is your connection string from the previous step. +> The MongoDB connection string must also specify a database for the parse_uri function. +> If not already included, make sure you provide a value for `` +> in your URI as shown in the example below: +> `mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@cluster0.example.mongodb.net/?retryWrites=true&w=majority` + -### Start the Server +### Run the Server To verify that you installed Django MongoDB Backend and correctly configured your project, run the following command from your project root: ```bash python manage.py runserver @@ -44,140 +54,40 @@ python manage.py runserver Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" message and an image of a rocket. -## Capabilities of Django Backend for MongoDB +## Capabilties for Django MongoDB Backend - **Model MongoDB Documents Through Django’s ORM** - - Translate Django model instances to MongoDB documents. - - Create new collections corresponding to models. + - Store Django model instances as MongoDB documents. - Supports field validation, data storage, updating, and deletion. - Maps Django's built-in fields to MongoDB data types. - - Provides new custom fields for arrays (ArrayField) and embedded documents (EmbeddedModelField). - - Supports core migration functionalities including creating, deleting, and updating indexes and collections + - Provides custom fields for arrays (`ArrayField`) and embedded documents (`EmbeddedModelField`). + - Supports core migration functionalities. - **Index Management** - - - Create single, compound, and unique indexes using Django Indexes - - Create MongoDB partial indexes in Django using Q notation. - + - Create single, compound, partial, and unique indexes using Django Indexes. - **Querying Data** - - Supports most functions of the Django QuerySet API - - Support Query Annotations and common SQL AGGREGATE operators - Support foreign key usage and execute JOIN operations - - Through our custom raw\_aggregate call, MQL operations like Vector Search, Atlas Search, and GeoSpatial querying still yield Django QuerySet resutts, + - Supports most of the Django QuerySet API. + - Supports foreign key usage and executes JOIN operations. + - A custom `QuerySet.raw_aggregate` method allows MQL operations like Vector Search, Atlas Search, and GeoSpatial querying to yield Django QuerySet results. - **Administrator Dashboard & Authentication** - - Manage your data in Django’s admin site. - - Fully integrated with Django's authentication framework. + - Manage your data in Django’s admin site. + - Fully integrated with Django's authentication framework. - Supports native user management features like creating users and sessions. -## Limitations of django-mongodb-backend - -- Database Variables `ATOMIC_REQUESTS`, `AUTOCOMMIT`, `CONN_HEALTH_CHECKS`, `TIME_ZONE` not supported -- No support for GeoDjango -- Functions such as `Chr`, `ExtractQuarter`, `MD5`, `Now`, `Ord`, `Pad`, `Repeat`, `Reverse`, `Right`, `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`, and `Sign`. -- The `tzinfo` parameter of the `Trunc` database functions does not work properly because MongoDB converts the result back to UTC. -- Schema Validation is not enforced. Refer to MongoDB documentation for how to enforce schema validation. -- Django DDL Transactions are not supported. -- The `migrate --fake-initial` command is not supported due to the inability to introspect MongoDB collection schema. -- The asynchronous functionality of the Django API has not yet been tested. -- `BSONRegExp` has no custom field class. It is best represented as a `CharField`. - - -#### **Model Limitations** - - - `$vectorSearch` and `$search` and Geospatial index creation through the Django Indexes API is not yet available. - - Updating indexes in `EmbeddedModels` do not work after the first table creation. - - - **ArrayField** - - Does not support `EmbeddedModel` within `ArrayField`. - - - **EmbeddedModel** - - Limited schema change support (no changing of embedded models). - - Embedded documents cannot take Django ForeignKeys. - - Arbitrary or untyped `EmbeddedModelField` is not supported. All fields must derive from an `EmbeddedModel` class. - - - **JSONField** - - There is no way to distinguish between a JSON "null" and a SQL null in specific queries. - - Some queries with Q objects, e.g., `Q(value__foo="bar")`, don't work properly, particularly with `QuerySet.exclude()`. - - Filtering for a `None` key, e.g., `QuerySet.filter(value__j=None)`, incorrectly returns objects where the key doesn't exist. - - - **DateTimeField** - - No support for microsecond granularity. - - - **DurationField**: - - Stores milliseconds rather than microseconds. - - - **Unavailable Fields**: - - `GeneratedField` - - `ImageField` - - -- **These QuerySet API methods do not work** - - - `distinct()` - - `dates()` - - `datetimes()` - - `prefetch_related()` - - `extra()` - - `QuerySet.delete()` and `update()` do not support queries that span multiple collections. - - -- **Django Management Commands that do not work** - - `createcachetable` - - `inspectdb` - - `optimizemigration` - - `sqlflush` - - `sqlsequencereset` - - -## Future Commitments of Django Backend for MongoDB - -- **Advanced Indexing** - - - Support for advanced index types like geospatial, text, and vector search indexes. - -- **Improved Data Modeling** - - - Support ArrayFields containing Embedded Models - - Support Collections with multiple Django Models - - Possible support for additional Django fields such as ImageField - - -- **Extended Querying Features** - - - Exploring smoother ways to allow users to use full-text search, vector search, or geospatial querying. - - -- **Enhanced Transactions Support** - - - Investigation and support for transactions, allowing features like `ATOMIC_REQUESTS` and `AUTOCOMMIT`. - -- **Asynchronous Capabilities** - - - Evaluation and support for Django’s asynchronous callback functions. - - -- **Performance Optimization** - - - Focus on performance tuning, especially concerning JOIN operations and ensure competitive performance relative to SQL databases. - - -- **Expanded Third-Party Library Support** - - - Vet our backend library works effortlessly with major Django Third-Party solutions - -These future capabilities are intended to enhance the functionality of the Django Backend for MongoDB as it progresses towards a General Availability (GA) release. If you have any more specific questions or need further details, feel free to ask\! - + ### Issues & Help -We're glad to have such a vibrant community of users of Django MongoDB Backend. We recommend seeking support for general questions through the MongoDB Community Forums. +We're glad to have such a vibrant community of users of Django MongoDB Backend. We recommend seeking support for general questions through the [MongoDB Community Forums](https://www.mongodb.com/community/forums/tag/python). #### Bugs / Feature Requests To report a bug or to request a new feature in Django MongoDB Backend, please open an issue in JIRA, our issue-management tool, using the following steps: From 6efce63c2664fa44182af37517a0c0920582cbc7 Mon Sep 17 00:00:00 2001 From: Jib Date: Wed, 29 Jan 2025 18:55:54 -0500 Subject: [PATCH 5/6] linter fixes --- README.md | 76 +++++++++++++++++++++++++------------------------------ 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 140a083a3..90cbbcd50 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,27 @@ # Django MongoDB Backend - - -This backend is currently in development and is not advised for Production workflows. Backwards incompatible +This backend is currently in development and is not advised for production workflows. Backwards incompatible changes may be made without notice. We welcome your feedback as we continue to explore and build. The best way to share this is via our [MongoDB Community Forum](https://www.mongodb.com/community/forums/tag/python). ## Install -Use the version of django-mongodb-backend that corresponds to your version of +Use the version of `django-mongodb-backend` that corresponds to your version of Django. For example, to get the latest compatible release for Django 5.0.x: - -`pip install --pre django-mongodb-backend==5.0.*` - +```bash +$ pip install --pre django-mongodb-backend==5.0.* +``` (Until the package is out of beta, you must use pip's `--pre` option.) ## Quickstart -### Start Project +### Start project From your shell, run the following command to create a new Django project -called example based on a custom template. Make sure the version referenced -from `django-mongodb-labs` corresponds to your version of Django similar -to the install stage. For example, this command works for Django 5.0.x: +called `example` based on a custom template. Make sure the zipfile referenced +at the end of the template link corresponds to your +version of Django. This snippet useso get the latest compatible release for Django 5.0.x: ```bash $ django-admin startproject example --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip @@ -32,63 +30,57 @@ $ django-admin startproject example --template https://github.com/mongodb-labs/d ### Connect to the database -Navigate to your `example/settings.py` file and find the variable named `DATABASES` Replace the `DATABASES` setting with this: +Navigate to your `example/settings.py` file and find the variable named +`DATABASES` Replace the `DATABASES` variable with this: ```python DATABASES = { - "default": django_mongodb_backend.parse_uri(""), + "default": django_mongodb_backend.parse_uri(""), } ``` -> The MongoDB connection string must also specify a database for the parse_uri function. -> If not already included, make sure you provide a value for `` -> in your URI as shown in the example below: -> `mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@cluster0.example.mongodb.net/?retryWrites=true&w=majority` +The MongoDB `` must also specify a database for the +`parse_uri` function to work. +If not already included, make sure you provide a value for `` +in your URI as shown in the example below: +```bash +mongodb+srv://myDatabaseUser:D1fficultP%40ssw0rd@cluster0.example.mongodb.net/?retryWrites=true&w=majority +``` -### Run the Server +### Run the server To verify that you installed Django MongoDB Backend and correctly configured your project, run the following command from your project root: ```bash -python manage.py runserver +$ python manage.py runserver ``` Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!" message and an image of a rocket. -## Capabilties for Django MongoDB Backend +## Capabilities of Django MongoDB Backend + +- **Model MongoDB Documents Through Django’s ORM** -- **Model MongoDB Documents Through Django’s ORM** - - Store Django model instances as MongoDB documents. - - Supports field validation, data storage, updating, and deletion. - - Maps Django's built-in fields to MongoDB data types. - - Provides custom fields for arrays (`ArrayField`) and embedded documents (`EmbeddedModelField`). + - Maps Django's built-in fields to MongoDB data types. + - Provides custom fields for arrays (`ArrayField`) and embedded documents (`EmbeddedModelField`). - Supports core migration functionalities. - - -- **Index Management** +- **Index Management** - Create single, compound, partial, and unique indexes using Django Indexes. - -- **Querying Data** - +- **Querying Data** - Supports most of the Django QuerySet API. - - Supports foreign key usage and executes JOIN operations. - - A custom `QuerySet.raw_aggregate` method allows MQL operations like Vector Search, Atlas Search, and GeoSpatial querying to yield Django QuerySet results. - - -- **Administrator Dashboard & Authentication** - + - Supports relational field usage and executes `JOIN` operations with MQL. + - A custom `QuerySet.raw_aggregate` method exposes MongoDB-specific operations like Vector Search, Atlas Search, and GeoSpatial querying to yield Django QuerySet results. +- **Administrator Dashboard & Authentication** - Manage your data in Django’s admin site. - Fully integrated with Django's authentication framework. - - Supports native user management features like creating users and sessions. + - Supports native user management features like creating users and session management. - ### Issues & Help We're glad to have such a vibrant community of users of Django MongoDB Backend. We recommend seeking support for general questions through the [MongoDB Community Forums](https://www.mongodb.com/community/forums/tag/python). + #### Bugs / Feature Requests To report a bug or to request a new feature in Django MongoDB Backend, please open an issue in JIRA, our issue-management tool, using the following steps: @@ -100,4 +92,4 @@ To report a bug or to request a new feature in Django MongoDB Backend, please op Bug reports in JIRA for the Django MongoDB Backend project can be viewed by everyone. -If you identify a security vulnerability in the driver or in any other MongoDB project, please report it according to the instructions found in [Create a Vulnerability Report](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report/). \ No newline at end of file +If you identify a security vulnerability in the driver or in any other MongoDB project, please report it according to the instructions found in [Create a Vulnerability Report](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report/). From 0d662e0ed32cd9e561b93e809dff0964c5809a87 Mon Sep 17 00:00:00 2001 From: Jib Date: Wed, 29 Jan 2025 19:20:34 -0500 Subject: [PATCH 6/6] revised template explanation --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 90cbbcd50..cea132b0a 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,10 @@ $ pip install --pre django-mongodb-backend==5.0.* ### Start project From your shell, run the following command to create a new Django project -called `example` based on a custom template. Make sure the zipfile referenced +called `example` using our custom template. Make sure the zipfile referenced at the end of the template link corresponds to your -version of Django. This snippet useso get the latest compatible release for Django 5.0.x: +version of Django. The snippet below specifies `5.0.x.zip` at the end of +the template url to get the template for any Django version matching 5.0: ```bash $ django-admin startproject example --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/5.0.x.zip