From eeeb0585ee58ca782b247bb27d3bfef61e5d15c2 Mon Sep 17 00:00:00 2001 From: "Jeffrey A. Clark" Date: Tue, 28 Jan 2025 17:29:40 -0500 Subject: [PATCH] Update README.md --- README.md | 213 +----------------------------------------------------- 1 file changed, 1 insertion(+), 212 deletions(-) diff --git a/README.md b/README.md index defd6e66..50c190b5 100644 --- a/README.md +++ b/README.md @@ -8,218 +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 git+https://github.com/mongodb-labs/django-mongodb-backend` - -### 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. +`pip install django-mongodb-backend` ## Troubleshooting