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
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
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
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
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
Authentication
Tip
To learn more about authentication options, see the Authentication Mechanisms section.
authMechanism
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
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
Data Type: string
Example:
val uri = "mongodb://localhost:27017/?replicaSet=myRS" val mongoClient = MongoClient(uri)
directConnection
Data Type: boolean
Default Value: false
Example:
val uri = "mongodb://localhost:27017/?directConnection=true" val mongoClient = MongoClient(uri)
readPreference
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
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
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
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: