Mongo()
On this page
Description
Mongo(host, autoEncryptionOpts, api)
JavaScript constructor to instantiate a database connection from
mongosh
or from a JavaScript file.The
Mongo()
method has the following parameters:ParameterTypeDescriptionhost
string orMongo
instanceOptional. Host or connection string.
The host can either be a connection string or in the form of
<host>
or<host><:port>
. The connection string can be in the form of aMongo
instance. If you specify aMongo
instance, theMongo()
constructor uses the connection string of the specified Mongo instance.If omitted,
Mongo()
instantiates a connection to the localhost interface on the default port27017
.autoEncryptionOpts
documentOptional. Configuration parameters for enabling Client-Side Field Level Encryption.
autoEncryptionOpts
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.See
AutoEncryptionOpts
for usage and syntax details.api
documentOptional. Configuration options for enabling the Stable API.
See
api
for usage and syntax details.
AutoEncryptionOpts
The autoEncryptionOpts
document specifies
configuration options for Client-Side Field Level Encryption.
If the database connection has an existing client-side field level
encryption configuration, specifying
autoEncryptionOpts
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 autoEncryptionOpts
.
The autoEncryptionOpts
document has the following
syntax:
{ "keyVaultClient" : <object>, "keyVaultNamespace" : "<string>", "kmsProviders" : <object>, "schemaMap" : <object>, "bypassAutoEncryption" : <boolean>, "tlsOptions": <object> }
The autoEncryptionOpts
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. This option is mutually exclusive
with For complete documentation, see Encryption Schemas. | |||||||||||||||||||||||||||
bypassAutoEncryption | boolean | (Optional) Specify true to bypass automatic client-side field
level encryption rules and perform explicit (manual) per-field
encryption. | |||||||||||||||||||||||||||
bypassQueryAnalysis | boolean | (Optional) Specify true to use explicit encryption on
indexed fields without the crypt_shared library. For details,
see MongoClient Options for Queryable Encryption. | |||||||||||||||||||||||||||
explicitEncryptionOnly | boolean | (Optional) Specify true to use neither automatic encryption
nor automatic decryption. You can use getKeyVault() and
getClientEncryption() to perform explicit
encryption. This option is mutually exclusive with schemaMap .
If omitted, defaults to false . | |||||||||||||||||||||||||||
tlsOptions | object | (Optional) The path to the TLS client certificate and private key file in PEM format
( tlsCertificateKeyFile ), TLS client certificate and private key file password
(tlsCertificateKeyFilePassword ), or TLS certificate authority file
(tlsCAFile ) to use to connect to the KMS in PEM format. To learn more
about these options, see TLS Options. |
api
The api
parameter specifies configuration options for the
Stable API. You can enable or disable optional
behavior using the following options:
Option | Type | Description |
---|---|---|
version | string | Specifies the API Version. "1" is
currently the only supported version. |
strict | boolean |
If you specify If not specified, defaults to |
deprecationErrors | boolean | If If not specified, defaults to |
The api
parameter has the following syntax:
{ api: { version: <string>, strict: <boolean>, deprecationErrors: <boolean> } }
Examples
Connect to a MongoDB Cluster
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 Cluster with Client-Side Encryption Enabled
Create Your Encrypted Client
Use the Mongo()
constructor with the client-side field level
encryption options configured to create a database connection. Replace
the mongodb://myMongo.example.net
URI with the connection
string URI of the target cluster.
encryptedClient = Mongo( "mongodb://myMongo.example.net:27017/?replSetName=myMongo", autoEncryptionOpts )
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 Cluster with Automatic Client-Side Encryption Enabled
To configure client-side field level encryption for a locally managed key:
generate a base64-encoded 96-byte string with no line breaks
use
mongosh
to load the key
export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb
The following operation creates a new connection object from within a
mongosh
session. The
AutoEncryptionOpts
option specifies
the required options for enabling automatic client-side encryption on the hr.employees
collection:
var autoEncryptionOpts = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, process.env["TEST_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", autoEncryptionOpts )
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.
The following operation creates a new connection object from within a
mongosh
session. The mongo.tlsOptions
option enables
a connection using KMIP as the KMS provider:
var csfleConnection = { keyVaultNamespace: "encryption.__keyVault", kmsProviders: { kmip: { endpoint: "kmip.example.com:123" } }, tlsOptions: { kmip: { tlsCertificateKeyFile: "/path/to/client/cert-and-key-bundle.pem" } } } cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", csfleConnection );
See Client-Side Field Level Encryption Methods for a complete list of client-side field level encryption methods.
Connect to a Cluster with the Stable API Enabled
The following operation creates a new connection object from within a
mongosh
session. The api
option
enables Stable API V1 and specifies that you cannot
run deprecated command or commands outside of the Stable API.
cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", null, { api: { version: "1", strict: true, deprecationErrors: true } } )
To interact with the mymongo.example.net:27017
cluster, issue
operations against the cluster
object. For a full list of Stable API
commands, see Stable API Commands.