Code review fixes (1/x)

Author: aclark4life

.github/workflows/mongodb_settings.py

@@ -39,7 +39,6 @@
         ),
         "directConnection": True,
     },
-    "KMS_PROVIDERS": {},
     "KMS_CREDENTIALS": {},
 }
 

django_mongodb_backend/management/commands/showencryptedfieldsmap.py

@@ -26,17 +26,16 @@ def add_arguments(self, parser):
 
     def handle(self, *args, **options):
         db = options["database"]
-        create = options.get("create", False)
+        create_data_keys = options.get("create_new_keys", False)
         connection = connections[db]
         client = connection.connection
         encrypted_fields_map = {}
         auto_encryption_opts = getattr(client._options, "auto_encryption_opts", None)
         for app_config in apps.get_app_configs():
             for model in router.get_migratable_models(app_config, db):
                 if model_has_encrypted_fields(model):
-                    from_db = not create
                     fields = connection.schema_editor()._get_encrypted_fields_map(
-                        model, client, auto_encryption_opts, from_db=from_db
+                        model, client, auto_encryption_opts, create_data_keys=create_data_keys
                     )
                     encrypted_fields_map[model._meta.db_table] = fields
         self.stdout.write(json_util.dumps(encrypted_fields_map, indent=2))

django_mongodb_backend/schema.py

@@ -423,7 +423,6 @@ def _field_should_have_unique(self, field):
         # The _id column is automatically unique.
         return db_type and field.unique and field.column != "_id"
 
-
     def _create_collection(self, model):
         """
         Create a collection for the model with the encrypted fields. If
@@ -456,7 +455,9 @@ def _create_collection(self, model):
         else:
             db.create_collection(db_table)
 
-    def _get_encrypted_fields_map(self, model, client, auto_encryption_opts, from_db=False):
+    def _get_encrypted_fields_map(
+        self, model, client, auto_encryption_opts, create_data_keys=False
+    ):
         connection = self.connection
         fields = model._meta.fields
         kms_provider = router.kms_provider(model)
@@ -474,7 +475,7 @@ def _get_encrypted_fields_map(self, model, client, auto_encryption_opts, from_db
         for field in fields:
             if getattr(field, "encrypted", False):
                 key_alt_name = f"{db_table}_{field.column}"
-                if from_db:
+                if not create_data_keys:
                     key_doc = key_vault_collection.find_one({"keyAltNames": key_alt_name})
                     if not key_doc:
                         raise ValueError(f"No key found in keyvault for keyAltName={key_alt_name}")

docs/source/howto/queryable-encryption.rst

@@ -2,50 +2,50 @@
 Configuring Queryable Encryption
 ================================
 
+.. versionadded:: 5.2.0b2
+
+.. admonition:: Queryable Encryption Compatibility
+
+   You can use Queryable Encryption on a MongoDB 7.0 or later replica
+   set or sharded cluster, but not a standalone instance.
+   :ref:`This table <manual:qe-compatibility-reference>` shows which MongoDB
+   server products support which Queryable Encryption mechanisms.
+
 .. _server-side-queryable-encryption:
 
 Configuring Queryable Encryption in Django is similar to
 :doc:`manual:core/queryable-encryption/quick-start` but with some additional
 steps required for Django.
 
-Server-side Queryable Encryption
---------------------------------
-
-Server-side Queryable Encryption allows you to begin developing applications
-without needing to define the encrypted fields map at the time of connection
-to the database.
-
-.. admonition:: What about client-side Queryable Encryption?
-
-    For configuration of client-side Queryable Encryption,
-    please refer to this :ref:`see below <client-side-queryable-encryption>`.
-
 Prerequisites
 -------------
 
-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::
+In addition to :doc:`installing </intro/install>` and :doc:`configuring
+</intro/configure>` Django MongoDB Backend, you will need to install some
+additional packages to use Queryable Encryption. This can be done with the
+optional dependency ``encryption`` in the ``django-mongodb-backend`` package.
 
     pip install django-mongodb-backend[encryption]
 
-.. admonition:: Queryable Encryption Compatibility
+.. _server-side-queryable-encryption-settings:
 
-   You can use Queryable Encryption on a MongoDB 7.0 or later replica
-   set or sharded cluster, but not a standalone instance.
-   :ref:`This table <manual:qe-compatibility-reference>` shows which MongoDB
-   server products support which Queryable Encryption mechanisms.
+Server-side Queryable Encryption
+--------------------------------
 
-.. _server-side-queryable-encryption-settings:
+Queryable Encryption is considered "server-side" when the encrypted fields map
+is not known at the time of connection to the database and this approach allows
+you to begin developing applications without needing to define the encrypted
+fields map at the time of connection to the database.
 
 Settings
 --------
 
-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.
+Due to a limited set of
+:doc:`manual:core/queryable-encryption/reference/supported-operations`, a second
+encrypted database and corresponding database router are needed to use Queryable
+Encryption in Django, as well as a KMS provider and credentials.
 
-::
+Here's how to set it up in your Django settings::
 
     from django_mongodb_backend import parse_uri
     from pymongo.encryption_options import AutoEncryptionOpts
@@ -55,26 +55,28 @@ database router. Here's how to set it up in your Django settings.
             DATABASE_URL,
             db_name="my_database",
         ),
-    }
-
-    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": {},
+        "encrypted": parse_uri(
+            DATABASE_URL,
+            options: {
+                "auto_encryption_opts": AutoEncryptionOpts(
+                    key_vault_namespace="my_encrypted_database.keyvault",
+                    kms_providers={"local": {"key": os.urandom(96)}},
+                ),
+            },
+            db_name="my_encrypted_database",
+            "KMS_CREDENTIALS": {},
+        ),
     }
 
     class EncryptedRouter:
+        """
+        A database router for an encrypted database to be used with a
+        "patientdata" app that contains models with encrypted fields.
+        """
+
         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_":
+            # The patientdata app's models are only created in the encrypted database.
+            if app_label == "patientdata":
                 return db == "encrypted"
             # Don't create other app's models in the encrypted database.
             if db == "encrypted":
@@ -87,7 +89,7 @@ database router. Here's how to set it up in your Django settings.
     DATABASE_ROUTERS = [EncryptedRouter()]
 
 You are now ready to use server-side :doc:`Queryable Encryption
-</topics/queryable-encryption>` in your Django project.
+</topics/queryable-encryption>`.
 
 .. admonition:: KMS providers and credentials
 
@@ -100,37 +102,35 @@ You are now ready to use server-side :doc:`Queryable Encryption
     :doc:`manual:core/queryable-encryption/fundamentals/keys-key-vaults`
     for information on creating and managing data encryption keys.
 
+    You can also refer to the `Python Queryable Encryption Tutorial
+    <https://github.com/mongodb/docs/tree/adad2b1ae41ec81a6e5682842850030813adc1e5/source/includes/qe-tutorials/python>`_.
+
 .. _client-side-queryable-encryption:
 
 Client-side Queryable Encryption
 --------------------------------
 
-In the :ref:`section above <server-side-queryable-encryption-settings>`,
-server-side Queryable Encryption configuration is covered.
-
-Client side Queryable Encryption configuration requires that the entire
-encrypted fields map be known at the time of client connection.
+Queryable Encryption is considered "client-side" when the encrypted fields map
+is known at the time of connection to the database. This approach can be used
+when you have finished development and you have a fixed set of encrypted fields
+that you want to use in your production environment.
 
 Encrypted fields map
 ~~~~~~~~~~~~~~~~~~~~
 
-In addition to the
-:ref:`settings described in the how-to guide <server-side-queryable-encryption-settings>`,
-you will need to provide a ``encrypted_fields_map`` to the
-``AutoEncryptionOpts``.
+In addition to the :ref:`settings described in the how-to guide
+<server-side-queryable-encryption-settings>` you will need to provide a
+``encrypted_fields_map`` to the ``AutoEncryptionOpts``.
 
-Fortunately, this is easy to do with Django MongoDB Backend. You can use
-the ``showencryptedfieldsmap`` management command to generate the schema map
-for your encrypted fields, and then use the results in your settings.
-
-To generate the encrypted fields map, run the following command in your Django
-project::
+You can use the ``showencryptedfieldsmap`` management command to generate the
+schema map for your encrypted fields and then use the results in your settings::
 
     python manage.py showencryptedfieldsmap
 
-.. note:: The ``showencryptedfieldsmap`` command is only available if you
-   have the ``django_mongodb_backend`` app included in the
-   :setting:`INSTALLED_APPS` setting.
+.. admonition:: Didn't work?
+
+    If you get the error ``Unknown command: 'createcachecollection'``, ensure
+    ``"django_mongodb_backend"`` is in your :setting:`INSTALLED_APPS` setting.
 
 Settings
 ~~~~~~~~
@@ -162,6 +162,5 @@ Now include the generated schema map in your Django settings::
         …
     }
 
-You are now ready to use client-side
-:doc:`Queryable Encryption </topics/queryable-encryption>`
-in your Django project.
+You are now ready to use client-side :doc:`Queryable Encryption
+</topics/queryable-encryption>`.

docs/source/ref/django-admin.rst

@@ -17,16 +17,19 @@ Available commands
 ``showencryptedfieldsmap``
 --------------------------
 
+.. versionadded:: 5.2.0b2
+
 .. django-admin:: showencryptedfieldsmap
 
-   Show mapping of models and their encrypted fields.
+    This command shows the mapping of encrypted fields to attributes including
+    data type, data keys and query types. Defaults to showing existing keys from
+    the configured key vault.
 
     .. django-admin-option:: --database DATABASE
 
-        Specifies the database to use.
-        Defaults to ``default``.
+        Specifies the database to use. Defaults to ``default``.
 
     .. django-admin-option:: --create-new-keys
 
-        If specified, creates the data keys instead of getting them from the
-        database.
+        If specified, this option will create new encryption keys for use in
+        production workflows.

docs/source/ref/index.rst

@@ -11,3 +11,4 @@ API reference
    database
    django-admin
    utils
+   settings

docs/source/ref/models/fields.rst

@@ -415,9 +415,12 @@ These indexes use 0-based indexing.
 Encrypted fields
 ----------------
 
-Encrypted fields are used to store sensitive data with MongoDB's Queryable
-Encryption feature. They are subclasses of Django's built-in fields, and
-they encrypt the data before storing it in the database.
+.. versionadded:: 5.2.0b2
+
+Encrypted fields are subclasses of Django's built-in fields and can be used to
+store sensitive data with MongoDB's :ref:`Queryable Encryption
+<server-side-queryable-encryption>` feature. They are subclasses of Django's
+built-in fields before storing it in the database.
 
 +----------------------------------------+------------------------------------------------------+
 | Encrypted Field                        | Django Field                                         |
@@ -459,13 +462,15 @@ they encrypt the data before storing it in the database.
 
 .. admonition:: Unsupported fields
 
-    The following fields are supported by Django MongoDB Backend but are not supported by
-    Queryable Encryption.
+    The following fields are supported by Django MongoDB Backend but are not
+    supported by Queryable Encryption.
 
-    :class:`~django.db.models.SlugField`
+    :class:`~django.db.models.SlugField` - Queryable Encryption does not
+    :doc:`support unique indexes on encrypted fields
+    <manual:core/queryable-encryption/reference/limitations>`.
 
-EncryptedFieldMixin
--------------------
+``EncryptedFieldMixin``
+-----------------------
 
 You can use the ``EncryptedFieldMixin`` to create your own encrypted fields. This mixin
 supports the use of a ``queries`` argument in the field definition to specify query type

docs/source/ref/settings.rst

@@ -0,0 +1,9 @@
+========
+Settings
+========
+
+Core Settings
+=============
+
+Here's a list of settings available in Django MongoDB Backend and their default
+values.

docs/source/topics/index.rst

@@ -9,6 +9,6 @@ know:
    :maxdepth: 2
 
    embedded-models
+   queryable-encryption
    transactions
    known-issues
-   queryable-encryption

docs/source/topics/queryable-encryption.rst

@@ -20,8 +20,9 @@ Let's consider this example::
 
 
     class Patient(models.Model):
-        ssn = EncryptedCharField(max_length=11, queries={"queryType":
-        "equality"})
+        ssn = EncryptedCharField(
+            max_length=11, queries={"queryType": "equality"}
+        )
 
         def __str__(self):
             return self.ssn
@@ -39,11 +40,6 @@ unencrypted client connection, 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>`.
-
 You can query encrypted fields using a
 :ref:`manual:qe-supported-query-operators` which must be specified in the
 field definition. For example, to query the ``ssn`` field for equality, you
@@ -66,3 +62,10 @@ looks like this:
       ssn: '123-45-6789',
       __safeContent__: [b'\xe0)NOFB\x9a,\x08\xd7\xdd\xb8\xa6\xba$…']
     }
+
+.. admonition:: List of encrypted fields
+
+    See the full list of :ref:`encrypted fields <encrypted-fields>` in the
+    :doc:`/ref/models/fields`. Also see
+    :doc:`manual:core/queryable-encryption/features` for an explanation of
+    encrypted field data.