Docs Home → Develop Applications → MongoDB Manual
Mongo()![](/docs/v5.3/assets/link.svg)
Description![](/docs/v5.3/assets/link.svg)
Changed in version 4.2.
Mongo(host, ClientSideFieldLevelEncryptionOptions)
JavaScript constructor to instantiate a database connection from
mongosh
or from a JavaScript file.The
Mongo()
method has the following parameters:ParameterTypeDescriptionhost
stringOptional. The host, either in the form of
<host>
or<host><:port>
.If omitted,
Mongo()
instantiates a connection to the localhost interface on the default port27017
.ClientSideFieldLevelEncryptionOptions
DocumentOptional
New in version 4.2.
Configuration parameters for enabling Client-Side Field Level Encryption.
ClientSideFieldLevelEncryptionOptions
overrides the existing client-side field level encryption configuration of the database connection. If omitted,Mongo()
inherits the client-side field level encryption configuration of the current database connection.For documentation of usage and syntax, see
ClientSideFieldLevelEncryptionOptions
.
Tip
See also:
ClientSideFieldLevelEncryptionOptions
![](/docs/v5.3/assets/link.svg)
New in version 4.2.
The ClientSideFieldLevelEncryptionOptions
document specifies
configuration options for Client-Side Field Level Encryption.
If the database connection has an existing client-side field level
encryption configuration, specifying
ClientSideFieldLevelEncryptionOptions
overrides that configuration.
For example, starting mongosh
with client-side field level encryption command-line options enables
client-side encryption for that connection. New database connections
created using Mongo()
inherit the encryption settings unless
Mongo()
includes ClientSideFieldLevelEncryptionOptions
.
The ClientSideFieldLevelEncryptionOptions
document has the following
syntax:
{ "keyVaultClient" : <object>, "keyVaultNamespace" : "<string>", "kmsProviders" : <object>, "schemaMap" : <object>, "bypassAutoEncryption" : <boolean> }
The ClientSideFieldLevelEncryptionOptions
document takes the
following parameters:
Parameter | Type | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
keyVaultClient | Mongo() connection object. | (Optional) The MongoDB cluster hosting the key vault collection. Specify a
If | ||||||||||||||||||||||||
keyVaultNamespace | string | (Required) The full namespace of the key vault
collection. | ||||||||||||||||||||||||
kmsProviders | document | (Required) The Key Management Service (KMS) used by client-side field level encryption for managing a Customer Master Key (CMK). Client-side field level encryption uses the CMK for encrypting and decrypting data encryption keys. Client-side field level encryption supports the following KMS providers: If possible, consider defining the credentials provided in
| ||||||||||||||||||||||||
schemaMap | document | (Optional) The automatic client-side field level encryption rules specified using the JSON schema Draft 4 standard syntax and encryption-specific keywords. For complete documentation, see Automatic Encryption Rules. | ||||||||||||||||||||||||
bypassAutoEncryption | boolean | (Optional) Specify true to bypass automatic client-side field
level encryption rules and perform explicit (manual) per-field
encryption. |
Example![](/docs/v5.3/assets/link.svg)
Connect to a MongoDB Cluster![](/docs/v5.3/assets/link.svg)
The following operation creates a new connection object from within a
mongosh
session:
cluster = Mongo("mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster")
Issue operations against the cluster
object to interact with the
mymongo.example.net:27017
cluster:
myDB = cluster.getDB("myDB"); //returns the database object myColl = myDB.getCollection("myColl"); // returns the collection object
Connect to a MongoDB Cluster with Client-Side Encryption Enabled![](/docs/v5.3/assets/link.svg)
Configuring client-side field level encryption for a locally
managed key requires specifying a
base64-encoded 96-byte string with no line breaks. The following
operation generates a key that meets the stated requirements and loads
it into mongosh
:
TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"
The following operation creates a new connection object from within a
mongosh
session. The
ClientSideFieldLevelEncryptionOptions
option specifies
the required options for enabling client-side field level encryption
using a locally managed key:
var ClientSideFieldLevelEncryptionOptions = { "keyVaultNamespace" : "encryption.dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, TEST_LOCAL_KEY) } } } cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", ClientSideFieldLevelEncryptionOptions )
Issue operations against the cluster
object to interact with the
mymongo.example.net:27017
cluster and perform explicit encryption:
// returns the database object myDB = cluster.getDB("myDB"); // returns the collection object myColl = myDB.getCollection("myColl"); // returns object for managing data encryption keys keyVault = cluster.getKeyVault(); // returns object for explicit encryption/decryption clientEncryption = cluster.getClientEncryption();
See Client-Side Field Level Encryption Methods for a complete list of client-side field level encryption methods.
Connect to a MongoDB Cluster with Automatic Client-Side Encryption Enabled![](/docs/v5.3/assets/link.svg)
Configuring client-side field level encryption for a locally
managed key requires specifying a
base64-encoded 96-byte string with no line breaks. The following
operation generates a key that meets the stated requirements and loads
it into mongosh
:
TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"
The following operation creates a new connection object from within a
mongosh
session. The
ClientSideFieldLevelEncryptionOptions
option specifies
the required options for enabling automatic client-side encryption on the hr.employees
collection:
var ClientSideFieldLevelEncryptionOptions = { "keyVaultNamespace" : "encryption.dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0,"BASE64-ENCODED-96-BYTE-LOCAL-KEY") } }, schemaMap : { "hr.employees" : { "bsonType": "object", "properties" : { "taxid" : { "encrypt" : { "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")], "bsonType" : "string", "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } }, "taxid-short": { "encrypt": { "keyId": [UUID("33408ee9-e499-43f9-89fe-5f8533870617")], "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", "bsonType": "string" } } } } } } cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", ClientSideFieldLevelEncryptionOptions )
Issue operations against the cluster
object to interact with the
mymongo.example.net:27017
cluster and utilize automatic encryption:
// returns the database object myDB = cluster.getDB("myDB"); // returns the collection object myColl = myDB.getCollection("myColl"); myColl.insertOne( { "name" : "J Doe", "taxid" : "123-45-6789", "taxid-short" : "6789" } )
The specified automatic encryption rules encrypt the taxid
and
taxid-short
fields using the specified data encryption key and
algorithm. Only clients configured for the correct KMS and access to
the specified data encryption key can decrypt the field.
See Client-Side Field Level Encryption Methods for a complete list of client-side field level encryption methods.