Fix db name on two encryption tests + doc updates

Author: aclark4life

docs/source/faq.rst

@@ -52,3 +52,71 @@ logging::
 If running ``manage.py dumpdata`` results in ``CommandError: Unable to
 serialize database: 'EmbeddedModelManager' object has no attribute using'``,
 see :ref:`configuring-database-routers-setting`.
+
+.. _queryable-encryption:
+
+Queryable Encryption
+====================
+
+What about client side configuration?
+-------------------------------------
+
+In the :doc:`Queryable Encryption how-to guide <howto/queryable-encryption>`,
+server side Queryable Encryption configuration is covered.
+
+Client side Queryable Encryption configuration requires that the entire schema
+for encrypted fields is known at the time of client connection.
+
+Schema Map
+~~~~~~~~~~
+
+In addition to the
+:ref:`settings described in the how-to guide <server-side-queryable-encryption-settings>`,
+you will need to provide a ``schema_map`` to the ``AutoEncryptionOpts``.
+
+Fortunately, this is easy to do with Django MongoDB Backend. You can use
+the ``showschemamap`` management command to generate the schema map
+for your encrypted fields, and then use the results in your settings.
+
+To generate the schema map, run the following command in your Django project:
+::
+
+    python manage.py showschemamap
+
+.. note:: The ``showschemamap`` command is only available if you have the
+    ``django_mongodb_backend`` app included in the :setting:`INSTALLED_APPS`
+    setting.
+
+Settings
+~~~~~~~~
+
+Now include the generated schema map in your Django settings.
+
+::
+
+    …
+    DATABASES["encrypted"] = {
+        …
+        "OPTIONS": {
+            "auto_encryption_opts": AutoEncryptionOpts(
+                …
+                schema_map= {
+                    "encryption__patientrecord": {
+                        "fields": [
+                            {
+                                "bsonType": "string",
+                                "path": "ssn",
+                                "queries": {"queryType": "equality"},
+                                "keyId": Binary(b"\x14F\x89\xde\x8d\x04K7\xa9\x9a\xaf_\xca\x8a\xfb&", 4),
+                            },
+                        }
+                    },
+                    # Add other models with encrypted fields here
+                },
+            ),
+            …
+        },
+        …
+    }
+
+You are now ready to use client side :doc:`Queryable Encryption </topics/queryable-encryption>` in your Django project.

docs/source/howto/queryable-encryption.rst

@@ -4,73 +4,73 @@ Configuring Queryable Encryption
 
 Configuring Queryable Encryption in Django is similar to
 `configuring Queryable Encryption in Python <https://www.mongodb.com/docs/manual/core/queryable-encryption/quick-start/>`_
-but with some additional steps to integrate with Django's operations. Below
-are the steps needed to set up Queryable Encryption in a Django project.
+but with some additional steps required for Django.
+
+.. note:: This section describes how to configure server side Queryable Encryption in Django.
+    For configuration of client side Queryable Encryption, please refer to this :ref:`FAQ question <queryable-encryption>`.
 
 Prerequisites
 -------------
 
-.. note:: You can use Queryable Encryption on a MongoDB 7.0 or later replica
-    set or sharded cluster, but not a standalone instance.
-    `This table <https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/compatibility/#std-label-qe-compatibility-reference>`_
-    shows which MongoDB server products support which Queryable Encryption mechanisms.
-
 In addition to :doc:`installing </intro/install>` and
 :doc:`configuring </intro/configure>` Django MongoDB Backend,
 you will need to install PyMongo with Queryable Encryption support::
 
     pip install django-mongodb-backend[encryption]
 
+.. note:: You can use Queryable Encryption on a MongoDB 7.0 or later replica
+    set or sharded cluster, but not a standalone instance.
+    `This table <https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/compatibility/#std-label-qe-compatibility-reference>`_
+    shows which MongoDB server products support which Queryable Encryption mechanisms.
+
+.. _server-side-queryable-encryption-settings:
+
 Settings
 --------
 
-Add an encrypted database, encrypted database router and KMS credentials to
-your Django settings.
-
-.. note:: Use of the helpers provided in ``django_mongodb_backend.encryption``
-    requires an encrypted database named "other".
+Queryable Encryption in Django requires the use of an additional encrypted database
+and Key Management Service (KMS) credentials as well as an encrypted database
+router. Here's how to set it up in your Django settings.
 
 ::
 
-    from django_mongodb_backend import encryption
-    from pymongo.encryption import AutoEncryptionOpts
+    from django_mongodb_backend import parse_uri
+    from pymongo.encryption_options import AutoEncryptionOpts
 
     DATABASES = {
         "default": parse_uri(
-            MONGODB_URI,
+            DATABASE_URL,
             db_name="my_database",
         ),
-        "other": parse_uri(
-            MONGODB_URI,
-            db_name="other",
-            options={
-                "auto_encryption_opts": AutoEncryptionOpts(
-                    kms_providers=encryption.KMS_PROVIDERS,
-                    key_vault_namespace="other.keyvault",
-                )
-            },
-        ),
-
-    DATABASES["other"]["KMS_CREDENTIALS"] = encryption.KMS_CREDENTIALS
-    DATABASE_ROUTERS = [encryption.EncryptedRouter()]
-
-You are now ready to use :doc:`Queryable Encryption </topics/queryable-encryption>` in your Django project.
-
-
-Helper classes and settings
-===========================
-
-``KMS_CREDENTIALS``
--------------------
-
-``KMS_PROVIDERS``
------------------
-
-``EncryptedRouter``
--------------------
-
-Query Types
------------
-
-- ``EqualityQuery``
-- ``RangeQuery``
+    }
+
+    DATABASES["encrypted"] = {
+        "ENGINE": "django_mongodb_backend",
+        "NAME": "my_encrypted_database",
+        "OPTIONS": {
+            "auto_encryption_opts": AutoEncryptionOpts(
+                key_vault_namespace="my_encrypted_database.keyvault",
+                kms_providers={"local": {"key": os.urandom(96)}},
+            ),
+            "directConnection": True,
+        },
+        "KMS_PROVIDERS": {},
+        "KMS_CREDENTIALS": {},
+    }
+
+    class EncryptedRouter:
+        def allow_migrate(self, db, app_label, model_name=None, **hints):
+            # The encryption_ app's models are only created in the encrypted database.
+            if app_label == "encryption_":
+                return db == "encrypted"
+            # Don't create other app's models in the encrypted database.
+            if db == "encrypted":
+                return False
+            return None
+
+        def kms_provider(self, model, **hints):
+            return "local"
+
+    DATABASE_ROUTERS = [EncryptedRouter()]
+
+You are now ready to use server side :doc:`Queryable Encryption </topics/queryable-encryption>` in your Django project.

docs/source/ref/models/fields.rst

@@ -419,10 +419,9 @@ they encrypt the data before storing it in the database.
 
 .. _encrypted-fields-unsupported-fields:
 
-Fields unsupported with Queryable Encryption
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. admonition:: Unsupported fields
 
-The following fields are supported by Django MongoDB Backend but not by Queryable Encryption.
+    The following fields are supported by Django MongoDB Backend but are not supported by
+    Queryable Encryption.
 
-- :class:`~django.db.models.DurationField`
-- :class:`~django.db.models.SlugField`
+    :class:`~django.db.models.SlugField`

docs/source/ref/models/models.rst

@@ -3,7 +3,7 @@ Model reference
 
 .. module:: django_mongodb_backend.models
 
-Two MongoDB-specific models are available in ``django_mongodb_backend.models``.
+One MongoDB-specific model is available in ``django_mongodb_backend.models``.
 
 .. class:: EmbeddedModel
 

docs/source/topics/known-issues.rst

@@ -106,4 +106,4 @@ backend rather than Django's built-in database cache backend,
 Queryable Encryption
 ====================
 
-TODO: Add Django core limitations that affect Queryable Encryption.
+.. TODO: Add Django core limitations that affect Queryable Encryption.

docs/source/topics/queryable-encryption.rst

@@ -50,6 +50,10 @@ the patient data looks like this:
       ssn: Binary.createFromBase64('DkrbD67ejkt2u…', 6),
     }
 
+.. admonition:: List of encrypted fields
+
+    See the full list of :ref:`encrypted fields <encrypted-fields>` in the :doc:`Model field reference </ref/models/fields>`.
+
 Querying encrypted fields
 -------------------------
 

tests/encryption_/tests.py

@@ -345,9 +345,7 @@ def test_patientrecord(self):
             # get_new_connection will return the encrypted connection
             # from the connection pool.
             with pymongo.MongoClient(**conn_params) as new_connection:
-                patientrecords = new_connection[
-                    "test_django_encrypted"
-                ].encryption__patientrecord.find()
+                patientrecords = new_connection["test_encrypted"].encryption__patientrecord.find()
                 ssn = patientrecords[0]["ssn"]
                 self.assertTrue(isinstance(ssn, Binary))