Misc updates

- Add mongocryptd to atlas CI
- Doc updates
- Remove custom db_type, not needed after mongodb#414
- SupportsQueryableEncryptionTests require MongoDB 8
- Update test model names prefix and suffix

Author: aclark4life

.github/workflows/test-python-atlas.yml

@@ -51,7 +51,27 @@ jobs:
         run: cp .github/workflows/runtests.py django_repo/tests/runtests_.py
       - name: Start local Atlas
         working-directory: .
-        run: bash .github/workflows/start_local_atlas.sh mongodb/mongodb-atlas-local:7
+        run: bash .github/workflows/start_local_atlas.sh mongodb/mongodb-atlas-local:8.0.15
+      - name: Install mongosh
+        run: |
+          wget -q https://downloads.mongodb.com/compass/mongosh-2.2.10-linux-x64.tgz
+          tar -xzf mongosh-*-linux-x64.tgz
+          sudo cp mongosh-*-linux-x64/bin/mongosh /usr/local/bin/
+          mongosh --version
+      - name: Install mongocryptd from Enterprise tarball
+        run: |
+          curl -sSL -o mongodb-enterprise.tgz "https://downloads.mongodb.com/linux/mongodb-linux-x86_64-enterprise-ubuntu2204-8.0.15.tgz"
+          tar -xzf mongodb-enterprise.tgz
+          sudo cp mongodb-linux-x86_64-enterprise-ubuntu2204-8.0.15/bin/mongocryptd /usr/local/bin/
+      - name: Start mongocryptd
+        run: |
+          nohup mongocryptd --logpath=/tmp/mongocryptd.log &
+      - name: Verify MongoDB installation
+        run: |
+          mongosh --eval 'db.runCommand({ connectionStatus: 1 })'
+      - name: Verify mongocryptd is running
+        run: |
+          pgrep mongocryptd
       - name: Run tests
         run: python3 django_repo/tests/runtests_.py
     permissions:

docs/howto/queryable-encryption.rst

@@ -14,7 +14,7 @@ Encryption in your Django project.
 .. admonition:: MongoDB requirements
 
     Queryable Encryption can be used with MongoDB replica sets or sharded
-    clusters running version 7.0 or later. Standalone instances are not
+    clusters running version 8.0 or later. Standalone instances are not
     supported. The following table summarizes which MongoDB server products
     support each Queryable Encryption mechanism.
 
@@ -51,21 +51,36 @@ encryption keys.
 
     import os
 
-    from django_mongodb_backend import parse_uri
     from pymongo.encryption_options import AutoEncryptionOpts
 
     DATABASES = {
-        # ...
-        "encrypted": parse_uri(
-            DATABASE_URL,
-            options={
+        "default": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "my_database",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
+                "retryWrites": "true",
+                "w": "majority",
+                "tls": "false",
+            },
+        },
+        "encrypted": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "encrypted",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
                 "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="keyvault.keyvault",
+                    key_vault_namespace="encrypted.keyvault",
                     kms_providers={"local": {"key": os.urandom(96)}},
                 )
             },
-            db_name="encrypted",
-        ),
+        },
     }
 
 Configuring the ``DATABASE_ROUTERS`` setting
@@ -88,10 +103,15 @@ configure a custom router for Queryable Encryption:
         Encryption.
         """
 
+        def db_for_read(self, model, **hints):
+            if model._meta.app_label == "myapp":
+                return "encrypted"
+            return None
+
+        db_for_write = db_for_read
+
         def allow_migrate(self, db, app_label, model_name=None, **hints):
-            # The patientdata app's models are only created in the encrypted
-            # database.
-            if app_label == "patientdata":
+            if app_label == "myapp":
                 return db == "encrypted"
             # Don't create other app's models in the encrypted database.
             if db == "encrypted":
@@ -132,15 +152,19 @@ Example of KMS configuration with AWS KMS:
 
 .. code-block:: python
 
-    from django_mongodb_backend import parse_uri
     from pymongo.encryption_options import AutoEncryptionOpts
 
     DATABASES = {
-        "encrypted": parse_uri(
-            DATABASE_URL,
-            options={
+        "encrypted": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "encrypted",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
                 "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="keyvault.keyvault",
+                    key_vault_namespace="encrypted.keyvault",
                     kms_providers={
                         "aws": {
                             "accessKeyId": "your-access-key-id",
@@ -149,14 +173,12 @@ Example of KMS configuration with AWS KMS:
                     },
                 )
             },
-            db_name="encrypted",
-        ),
-    }
-
-    DATABASES["encrypted"]["KMS_CREDENTIALS"] = {
-        "aws": {
-            "key": os.getenv("AWS_KEY_ARN", ""),
-            "region": os.getenv("AWS_KEY_REGION", ""),
+            "KMS_CREDENTIALS": {
+                "aws": {
+                    "key": os.getenv("AWS_KEY_ARN", ""),
+                    "region": os.getenv("AWS_KEY_REGION", ""),
+                },
+            },
         },
     }
 
@@ -208,6 +230,57 @@ If you do not want to use the data keys created by Django MongoDB Backend (when
 In this scenario, Django MongoDB Backend will use the newly created data keys
 to create collections for models with encrypted fields.
 
+Here is an example of how to configure the
+``encrypted_fields_map`` in your Django settings:
+
+.. code-block:: python
+
+    from pymongo.encryption_options import AutoEncryptionOpts
+    from bson import json_util
+
+    DATABASES = {
+        "encrypted": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "encrypted",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
+                "auto_encryption_opts": AutoEncryptionOpts(
+                    key_vault_namespace="encrypted.keyvault",
+                    kms_providers={
+                        "aws": {
+                            "accessKeyId": "your-access-key-id",
+                            "secretAccessKey": "your-secret-access-key",
+                        }
+                    },
+                    encrypted_fields_map=json_util.loads(
+                        """{
+                        "encrypt_patient": {
+                          "fields": [
+                            {
+                              "bsonType": "string",
+                              "path": "patient_record.ssn",
+                              "keyId": {
+                                "$binary": {
+                                  "base64": "2MA29LaARIOqymYHGmi2mQ==",
+                                  "subType": "04"
+                                }
+                              },
+                              "queries": {
+                                "queryType": "equality"
+                              }
+                            },
+                          ]
+                        }
+                    }"""
+                    ),
+                )
+            },
+        },
+    }
+
 Configuring the Automatic Encryption Shared Library
 ===================================================
 
@@ -222,25 +295,62 @@ recommended for use with Queryable Encryption.
 You can :ref:`download the shared library
 <manual:qe-csfle-shared-library-download>` from the
 :ref:`manual:enterprise-official-packages` and configure it in your Django
-settings as follows:
+settings using the ``crypt_shared_lib_path`` option in
+:class:`pymongo.encryption_options.AutoEncryptionOpts`. The following example
+shows how to configure the shared library in your Django settings:
 
 .. code-block:: python
 
-    from django_mongodb_backend import parse_uri
     from pymongo.encryption_options import AutoEncryptionOpts
 
     DATABASES = {
-        "encrypted": parse_uri(
-            DATABASE_URL,
-            options={
+        "encrypted": {
+            "ENGINE": "django_mongodb_backend",
+            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
+            "NAME": "encrypted",
+            "USER": "my_user",
+            "PASSWORD": "my_password",
+            "PORT": 27017,
+            "OPTIONS": {
                 "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="keyvault.keyvault",
-                    kms_providers={"local": {"key": os.urandom(96)}},
+                    key_vault_namespace="encrypted.keyvault",
+                    kms_providers={
+                        "aws": {
+                            "accessKeyId": "your-access-key-id",
+                            "secretAccessKey": "your-secret-access-key",
+                        }
+                    },
+                    encrypted_fields_map=json_util.loads(
+                        """{
+                        "encrypt_patient": {
+                          "fields": [
+                            {
+                              "bsonType": "string",
+                              "path": "patient_record.ssn",
+                              "keyId": {
+                                "$binary": {
+                                  "base64": "2MA29LaARIOqymYHGmi2mQ==",
+                                  "subType": "04"
+                                }
+                              },
+                              "queries": {
+                                "queryType": "equality"
+                              }
+                            },
+                          ]
+                        }
+                    }"""
+                    ),
                     crypt_shared_lib_path="/path/to/mongo_crypt_shared_v1.dylib",
                 )
             },
-            db_name="encrypted",
-        ),
+            "KMS_CREDENTIALS": {
+                "aws": {
+                    "key": os.getenv("AWS_KEY_ARN", ""),
+                    "region": os.getenv("AWS_KEY_REGION", ""),
+                },
+            },
+        },
     }
 
 You are now ready to :doc:`start developing applications

docs/ref/django-admin.rst

@@ -17,7 +17,7 @@ Available commands
 ``showencryptedfieldsmap``
 --------------------------
 
-.. versionadded:: 5.2.2
+.. versionadded:: 5.2.3
 
 .. django-admin:: showencryptedfieldsmap
 

docs/ref/models/encrypted-fields.rst

@@ -9,7 +9,7 @@ Django MongoDB Backend supports :doc:`manual:core/queryable-encryption`.
 See :doc:`/howto/queryable-encryption` for more information on how to use
 Queryable Encryption with Django MongoDB Backend.
 
-See the :doc:`Queryable Encryption topic </topics/queryable-encryption>` for
+See the :doc:`/topics/queryable-encryption` topic guide for
 more information on developing applications with Queryable Encryption.
 
 The following fields are supported by Django MongoDB Backend for use with

docs/topics/queryable-encryption.rst

@@ -106,7 +106,7 @@ For example, to find a patient by their SSN, you can do the following::
     'Bob'
 
 
-QuerySet Limitations
+QuerySet limitations
 ~~~~~~~~~~~~~~~~~~~~
 
 When using Django QuerySets with MongoDB Queryable Encryption, it’s important to
@@ -128,8 +128,6 @@ be done client-side after decryption. Key limitations include:
 - **No joins on encrypted fields** – Filtering across relationships using
   encrypted foreign keys is unsupported because matching must happen
   client-side.
-- **Admin/debug limitations** – You’ll need to integrate client-side decryption
-  for Django admin or tools, otherwise you’ll see ciphertext.
 
 In short, when working with Queryable Encryption, design your queries to use
 exact matches only on encrypted fields, and plan to handle any sorting or

tests/backend_/test_features.py

@@ -69,24 +69,24 @@ def non_enterprise_response(command):
         raise Exception("Unexpected command")
 
     def test_supported_on_atlas(self):
-        """Supported on MongoDB 7.0+ Atlas replica set or sharded cluster."""
+        """Supported on MongoDB 8.0+ Atlas replica set or sharded cluster."""
         with (
             patch(
                 "pymongo.synchronous.database.Database.command", wraps=self.non_enterprise_response
             ),
             patch("django.db.connection.features.supports_atlas_search", True),
             patch("django.db.connection.features._supports_transactions", True),
-            patch("django.db.connection.features.is_mongodb_7_0", True),
+            patch("django.db.connection.features.is_mongodb_8_0", True),
         ):
             self.assertIs(connection.features.supports_queryable_encryption, True)
 
     def test_supported_on_enterprise(self):
-        """Supported on MongoDB 7.0+ Enterprise replica set or sharded cluster."""
+        """Supported on MongoDB 8.0+ Enterprise replica set or sharded cluster."""
         with (
             patch("pymongo.synchronous.database.Database.command", wraps=self.enterprise_response),
             patch("django.db.connection.features.supports_atlas_search", False),
             patch("django.db.connection.features._supports_transactions", True),
-            patch("django.db.connection.features.is_mongodb_7_0", True),
+            patch("django.db.connection.features.is_mongodb_8_0", True),
         ):
             self.assertIs(connection.features.supports_queryable_encryption, True)
 
@@ -98,7 +98,7 @@ def test_atlas_or_enterprise_required(self):
             ),
             patch("django.db.connection.features.supports_atlas_search", False),
             patch("django.db.connection.features._supports_transactions", True),
-            patch("django.db.connection.features.is_mongodb_7_0", True),
+            patch("django.db.connection.features.is_mongodb_8_0", True),
         ):
             self.assertIs(connection.features.supports_queryable_encryption, False)
 
@@ -111,16 +111,16 @@ def test_transactions_required(self):
             patch("pymongo.synchronous.database.Database.command", wraps=self.enterprise_response),
             patch("django.db.connection.features.supports_atlas_search", False),
             patch("django.db.connection.features._supports_transactions", False),
-            patch("django.db.connection.features.is_mongodb_7_0", True),
+            patch("django.db.connection.features.is_mongodb_8_0", True),
         ):
             self.assertIs(connection.features.supports_queryable_encryption, False)
 
-    def test_mongodb_7_0_required(self):
-        """Not supported on MongoDB < 7.0"""
+    def test_mongodb_8_0_required(self):
+        """Not supported on MongoDB < 8.0"""
         with (
             patch("pymongo.synchronous.database.Database.command", wraps=self.enterprise_response),
             patch("django.db.connection.features.supports_atlas_search", False),
             patch("django.db.connection.features._supports_transactions", True),
-            patch("django.db.connection.features.is_mongodb_7_0", False),
+            patch("django.db.connection.features.is_mongodb_8_0", False),
         ):
             self.assertIs(connection.features.supports_queryable_encryption, False)