Skip to content

Commit 5f13170

Browse files
committed
reorder "Configuring the Automatic Encryption Shared Library" to make it part of the normal flow
1 parent ee3e2bf commit 5f13170

File tree

1 file changed

+56
-56
lines changed

1 file changed

+56
-56
lines changed

docs/howto/queryable-encryption.rst

Lines changed: 56 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,62 @@ The database name of the key vault must be the same as in ``"NAME"``. The
8181
vault's collection name can be whatever you wish, but by convention, it's often
8282
``__keyVault``.
8383

84+
Configuring the Automatic Encryption Shared Library
85+
===================================================
86+
87+
Next, you'll need to configure the :ref:`manual:qe-reference-shared-library`.
88+
89+
First, :ref:`download the shared library
90+
<manual:qe-csfle-shared-library-download>`. You can choose the latest version,
91+
even if it doesn't match your MongoDB server version.
92+
93+
After extracting the shared library archive, configure your Django settings to
94+
point to the shared library. For example, on macOS, the name of the shared
95+
library is ``mongo_crypt_shared_v1.dylib``::
96+
97+
DATABASES = {
98+
# ...
99+
"encrypted": {
100+
# ...
101+
"OPTIONS": {
102+
"auto_encryption_opts": AutoEncryptionOpts(
103+
# ...
104+
crypt_shared_lib_path="/path/to/mongo_crypt_shared_v1.dylib",
105+
crypt_shared_lib_required=True,
106+
),
107+
},
108+
},
109+
}
110+
111+
.. admonition:: Dynamic library path configuration
112+
113+
If you encounter ``Pymongocrypt.errors.MongoCryptError: An existing
114+
crypt_shared library is loaded by the application at
115+
[/path/to/mongo_crypt_v1.so], but the current call to mongocrypt_init()
116+
failed to find that same library.``, you probably need to configure an
117+
environment variable so that your system can locate the library:
118+
119+
+---------------+---------------------------------+
120+
| **Platform** | **Environment Variable** |
121+
+---------------+---------------------------------+
122+
| Windows | ``PATH`` |
123+
+---------------+---------------------------------+
124+
| macOS | ``DYLD_FALLBACK_LIBRARY_PATH`` |
125+
+---------------+---------------------------------+
126+
| Linux | ``LD_LIBRARY_PATH`` |
127+
+---------------+---------------------------------+
128+
129+
For example, on macOS you can set ``DYLD_FALLBACK_LIBRARY_PATH`` in your
130+
shell before starting your Django application:
131+
132+
.. code-block:: console
133+
134+
$ export DYLD_FALLBACK_LIBRARY_PATH="/path/to/mongo_crypt_shared/:$DYLD_FALLBACK_LIBRARY_PATH"
135+
136+
Unlike ``crypt_shared_lib_path`` earlier, the environment variable points
137+
to the directory that contains the shared library, not the shared library
138+
itself.
139+
84140
.. _qe-configuring-database-routers-setting:
85141

86142
Configuring the ``DATABASE_ROUTERS`` setting
@@ -313,59 +369,3 @@ fields map::
313369
},
314370
},
315371
}
316-
317-
Configuring the Automatic Encryption Shared Library
318-
===================================================
319-
320-
Next, you'll need to configure the :ref:`manual:qe-reference-shared-library`.
321-
322-
First, :ref:`download the shared library
323-
<manual:qe-csfle-shared-library-download>`. You can choose the latest version,
324-
even if it doesn't match your MongoDB server version.
325-
326-
After extracting the shared library archive, configure your Django settings to
327-
point to the shared library. For example, on macOS, the name of the shared
328-
library is ``mongo_crypt_shared_v1.dylib``::
329-
330-
DATABASES = {
331-
# ...
332-
"encrypted": {
333-
# ...
334-
"OPTIONS": {
335-
"auto_encryption_opts": AutoEncryptionOpts(
336-
# ...
337-
crypt_shared_lib_path="/path/to/mongo_crypt_shared_v1.dylib",
338-
crypt_shared_lib_required=True,
339-
),
340-
},
341-
},
342-
}
343-
344-
.. admonition:: Dynamic library path configuration
345-
346-
If you encounter ``Pymongocrypt.errors.MongoCryptError: An existing
347-
crypt_shared library is loaded by the application at
348-
[/path/to/mongo_crypt_v1.so], but the current call to mongocrypt_init()
349-
failed to find that same library.``, you probably need to configure an
350-
environment variable so that your system can locate the library:
351-
352-
+---------------+---------------------------------+
353-
| **Platform** | **Environment Variable** |
354-
+---------------+---------------------------------+
355-
| Windows | ``PATH`` |
356-
+---------------+---------------------------------+
357-
| macOS | ``DYLD_FALLBACK_LIBRARY_PATH`` |
358-
+---------------+---------------------------------+
359-
| Linux | ``LD_LIBRARY_PATH`` |
360-
+---------------+---------------------------------+
361-
362-
For example, on macOS you can set ``DYLD_FALLBACK_LIBRARY_PATH`` in your
363-
shell before starting your Django application:
364-
365-
.. code-block:: console
366-
367-
$ export DYLD_FALLBACK_LIBRARY_PATH="/path/to/mongo_crypt_shared/:$DYLD_FALLBACK_LIBRARY_PATH"
368-
369-
Unlike ``crypt_shared_lib_path`` earlier, the environment variable points
370-
to the directory that contains the shared library, not the shared library
371-
itself.

0 commit comments

Comments
 (0)