Overview
This page describes the MongoDB connection and authentication options available in the Scala driver and explains how to specify them for your MongoDB connection.
Set Options in the Connection URI
If you pass a connection URI to the MongoClient() constructor, you can include connection options in the string as <name>=<value> pairs. In the following example, the connection URI contains the connectTimeoutMS option with a value of 60000 and the tls option with a value of true:
val uri = "mongodb://localhost:27017/?connectTimeoutMS=60000&tls=true" val mongoClient = MongoClient(uri)
Set Options in MongoClientSettings
You can set connection options in a MongoClientSettings instance by using methods from the MongoClientSettings.Builder class, then passing the settings object to the MongoClient() constructor.
Configuring the connection this way makes it easier to change settings at runtime and can help you catch errors at compile time.
The following example shows how to specify your connection target and set other options when creating a MongoClientSettings instance:
val settings = MongoClientSettings.builder() .applyToClusterSettings(builder => builder.hosts(List(new ServerAddress("localhost", 27017)).asJava)) .applyToSocketSettings(builder => builder.connectTimeout(60000, TimeUnit.MILLISECONDS)) .applyToSslSettings(builder => builder.enabled(true)) .build() val mongoClient = MongoClient(settings)
If you prefer to provide a connection string instead of specifying the hostname and port, you can use the applyConnectionString() method, then set other options by using builder methods, as shown in the following code:
val uri = "mongodb://localhost:27017/" val settings = MongoClientSettings.builder() .applyConnectionString(ConnectionString(uri)) .applyToSocketSettings(builder => builder.connectTimeout(60000, TimeUnit.MILLISECONDS)) .applyToSslSettings(builder => builder.enabled(true)) .build() val mongoClient = MongoClient(settings)
Network Compression
compressors
The preferred compression types, in order, for wire-protocol messages sent to or received from the server. You can enable "snappy", "zlib", and "zstd" as optional build time dependencies. The driver uses the first of these compression types that the server supports.
Data Type: comma-delimited string
Default Value: null
Example:
val uri = "mongodb://localhost:27017/?compressors=snappy,zstd,zlib" val mongoClient = MongoClient(uri)
zlibCompressionLevel
The compression level for zlib to use. This option accepts an integer value between -1 and 9:
-1: (Default). zlib uses its default compression level (usually
6).0: No compression.
1: Fastest speed but lowest compression.
9: Best compression but slowest speed.
Data Type: integer
Default Value: -1
Example:
val uri = "mongodb://localhost:27017/?compressors=zlib&zlibCompressionLevel=3" val mongoClient = MongoClient(uri)
compressors
The preferred compression types, in order, for wire-protocol messages sent to or received from the server. You can enable "snappy", "zlib", and "zstd" as optional build time dependencies. The driver uses the first of these compression types that the server supports.
Data Type: List[MongoCompressor]
Default Value: empty list
Example:
val settings = MongoClientSettings.builder() .compressorList(List( MongoCompressor.createSnappyCompressor(), MongoCompressor.createZstdCompressor(), MongoCompressor.createZlibCompressor() ).asJava) .build() val mongoClient = MongoClient(settings)
zlibCompressionLevel
The compression level for zlib to use. This option accepts an integer value between -1 and 9:
-1: (Default). zlib uses its default compression level (usually
6).0: No compression.
1: Fastest speed but lowest compression.
9: Best compression but slowest speed.
Data Type: integer
Default Value: -1
Example:
val settings = MongoClientSettings.builder() .compressorList(List( MongoCompressor.createZlibCompressor() .withProperty(MongoCompressor.LEVEL, 3) ).asJava) .build() val mongoClient = MongoClient(settings)
Timeouts
connectTimeoutMS
The length of time the driver tries to establish a single TCP socket connection to the server before timing out.
Data Type: integer
Default Value: 10000
Example:
val uri = "mongodb://localhost:27017/?connectTimeoutMS=10000" val mongoClient = MongoClient(uri)
socketTimeoutMS (deprecated)
This option is deprecated. Configure this timeout by setting the client-level timeout instead.
The length of time the driver tries to send or receive on a socket before timing out. The default value is set by the operating system.
Data Type: integer
Default Value: no timeout
Example:
val uri = "mongodb://localhost:27017/?socketTimeoutMS=5000" val mongoClient = MongoClient(uri)
connectTimeoutMS
The length of time the driver tries to establish a single TCP socket connection to the server before timing out.
Data Type: integer
Default Value: 10000
Example:
val settings = MongoClientSettings.builder() .applyToSocketSettings(builder => builder.connectTimeout(10, TimeUnit.SECONDS)) .build() val mongoClient = MongoClient(settings)
socketTimeoutMS (deprecated)
This option is deprecated. Configure this timeout by setting the client-level timeout instead.
The length of time the driver tries to send or receive on a socket before timing out. The default value is set by the operating system.
Data Type: integer
Default Value: no timeout
Example:
val settings = MongoClientSettings.builder() .applyToSocketSettings(builder => builder.readTimeout(5, TimeUnit.SECONDS)) .build() val mongoClient = MongoClient(settings)
Server Selection
serverSelectionTimeoutMS
The length of time the driver tries to select a server before timing out.
Data Type: integer
Default Value: 30000
Example:
val settings = MongoClientSettings.builder() .applyToClusterSettings(builder => builder.serverSelectionTimeout(30, TimeUnit.SECONDS)) .build() val mongoClient = MongoClient(settings)
Authentication
Tip
To learn more about authentication options, see the Authentication Mechanisms section.
authMechanism
The mechanism that the driver uses to authenticate to MongoDB Server. If you don't specify an authentication mechanism, the driver uses either SCRAM-SHA-1 or SCRAM-SHA-256, depending on the server version.
Data Type: string
Default Value: "SCRAM-SHA-256" when connecting to MongoDB v4.0 or later
Example:
val uri = "mongodb://<username>:<password>@localhost:27017/?authMechanism=SCRAM-SHA-256" val mongoClient = MongoClient(uri)
authMechanismProperties
Options specific to the authentication mechanism. Not required for all authentication mechanisms.
Data Type: string
Example:
val uri = "mongodb://localhost:27017/?authMechanismProperties=AWS_SESSION_TOKEN:12435" val mongoClient = MongoClient(uri)
authSource
The database to authenticate against.
Data Type: string
Default Value: "admin"
Example:
val uri = "mongodb://<username>:<password>@localhost:27017/?authSource=admin" val mongoClient = MongoClient(uri)
username
The username for authentication. When this option is included in a connection URI, you must percent-encode it.
Data Type: string
Example:
val uri = "mongodb://myUser:<password>@localhost:27017/" val mongoClient = MongoClient(uri)
password
The password for authentication. When this option is included in a connection URI, you must percent-encode it.
Data Type: string
Example:
val uri = "mongodb://<username>:myPassword@localhost:27017/" val mongoClient = MongoClient(uri)
authMechanism
The mechanism that the driver uses to authenticate to MongoDB Server. If you don't specify an authentication mechanism, the driver uses either SCRAM-SHA-1 or SCRAM-SHA-256, depending on the server version.
Data Type: string
Default Value: "SCRAM-SHA-256" when connecting to MongoDB v4.0 or later
Example:
val settings = MongoClientSettings.builder() .credential(MongoCredential.createScramSha256Credential( "<username>", "<authSource>", "<password>".toCharArray)) .build() val mongoClient = MongoClient(settings)
Note
To configure username, password, authentication source, and mechanism-specific properties in MongoClientSettings, use the appropriate MongoCredential factory method. To learn more, see the Authentication Mechanisms guide.
Read and Write Operations
replicaSet
The name of the replica set to connect to.
Data Type: string
Example:
val uri = "mongodb://localhost:27017/?replicaSet=myRS" val mongoClient = MongoClient(uri)
directConnection
Specifies whether to force dispatch all operations to the host. If you specify this option, the driver doesn't accept the SRV connection format. You must use the standard connection URI format instead. To learn more about the SRV connection and the standard connection formats, see the Connection Strings guide in the MongoDB Server manual.
This property must be set to false if you specify more than one host name.
Data Type: boolean
Default Value: false
Example:
val uri = "mongodb://localhost:27017/?directConnection=true" val mongoClient = MongoClient(uri)
readPreference
The client's default read-preference settings. See Read Preference in the MongoDB Server manual for more information.
Data Type: string
Default Value: primary
Example:
val uri = "mongodb://localhost:27017/?readPreference=primary" val mongoClient = MongoClient(uri)
readConcern
The client's read concern. For more information, see Read Concern in the MongoDB Server manual.
Data Type: string
Example:
val uri = "mongodb://localhost:27017/?readConcern=majority" val mongoClient = MongoClient(uri)
writeConcern
The client's write concern. For more information, see Write Concern in the MongoDB Server manual.
Data Type: string
Example:
val uri = "mongodb://localhost:27017/?writeConcern=majority" val mongoClient = MongoClient(uri)
localThresholdMS
The latency window for server eligibility. If a server's round trip takes longer than the fastest server's round-trip time plus this value, the server isn't eligible for selection.
Data Type: integer
Default Value: 15
Example:
val uri = "mongodb://localhost:27017/?localThresholdMS=35" val mongoClient = MongoClient(uri)
replicaSet
The name of the replica set to connect to.
Data Type: string
Example:
val settings = MongoClientSettings.builder() .applyToClusterSettings(builder => builder.requiredReplicaSetName("myRS")) .build() val mongoClient = MongoClient(settings)
directConnection
Specifies whether to force dispatch all operations to the host. If you specify this option, the driver doesn't accept the SRV connection format. You must use the standard connection URI format instead. To learn more about the SRV connection and the standard connection formats, see the Connection Strings guide in the MongoDB Server manual.
This property must be set to false if you specify more than one host name.
Data Type: boolean
Default Value: false
Example:
val settings = MongoClientSettings.builder() .applyToClusterSettings(builder => builder.mode(ClusterConnectionMode.SINGLE)) .build() val mongoClient = MongoClient(settings)
readPreference
The client's default read-preference settings. See Read Preference in the MongoDB Server manual for more information.
Data Type: string
Default Value: primary
Example:
val settings = MongoClientSettings.builder() .readPreference(ReadPreference.primary()) .build() val mongoClient = MongoClient(settings)
readConcern
The client's read concern. For more information, see Read Concern in the MongoDB Server manual.
Data Type: string
Example:
val settings = MongoClientSettings.builder() .readConcern(ReadConcern.MAJORITY) .build() val mongoClient = MongoClient(settings)
writeConcern
The client's write concern. For more information, see Write Concern in the MongoDB Server manual.
Data Type: string
Example:
val settings = MongoClientSettings.builder() .writeConcern(WriteConcern.MAJORITY) .build() val mongoClient = MongoClient(settings)
localThresholdMS
The latency window for server eligibility. If a server's round trip takes longer than the fastest server's round-trip time plus this value, the server isn't eligible for selection.
Data Type: integer
Default Value: 15
Example:
val settings = MongoClientSettings.builder() .applyToClusterSettings(builder => builder.localThreshold(35, TimeUnit.MILLISECONDS)) .build() val mongoClient = MongoClient(settings)
Additional Information
To view a full list of connection options, see Connection String Options in the MongoDB Server manual.
API Documentation
To learn more about the classes and methods mentioned in this guide, see the following API documentation: