# Introduction

The concept of driver and how it works is already explained in the technical-overview and driver pages.

Here we explain how to use a driver with MongoDB and the different drivers Mongock provides.



# MongoDB driver options and compatibility

There are 4 drivers in the MongoDB family driver:

Mongock driver Driver library Version compatibility
SpringDataMongoV3Driver org.springframework.data:spring-data-mongodb 3.X.X
SpringDataMongoV2Driver org.springframework.data:spring-data-mongodb 2.X.X
MongoSync4Driver org.mongodb:mongodb-driver-sync 4.X.X
MongoSync3Driver org.mongodb:mongo-java-driver 3.X.X


# MongoDB common configuration

All the MongoDB drivers share the same configuration.

When setting configuration via properties file, it must be prefixed by mongock.mongo-db

# Properties

Property Description Type Default value
writeConcern Exactly the same MongoDB parameter write concern. For more information, visit the official MongoDB documentation for write concern. Object {w:majority,
wTimeoutMs: null,
j:true}
readConcern Exactly the same MongoDB parameter read concern. For more information, visit the official MongoDB documentation for read concern. String majority
readPreference Exactly the same MongoDB parameter read preference. For more information, visit the official MongoDB documentation for read preference. String primary


# MongoDB Springdata

Mongock offers two drivers for MongoDB springdata. The latest, version 3.x, and the previous major version 2.x, just for those who haven't upgraded yet.

# Get started

Following the get started section, this covers steps 3 and 5 and 6.

# Add maven dependency for the driver (step 2)

<dependency>
<groupId>io.mongock</groupId>
<artifactId>mongodb-springdata-v3-driver</artifactId>
<!--<artifactId>mongodb-springdata-v2-driver</artifactId> for MongoDB spring data v2-->
</dependency>

# Build the driver (setp 5)

This step is only required for builder approach. Mongock handles it for autoconfiguration.

These classes provide the same two static initializers:

SpringDataMongoV3Driver driver = SpringDataMongoV3Driver.withDefaultLock(mongoTemplate);

# Driver extra configuration (step 6)

# Transactions

In order to use native transactions, Mongock only needs the MongoTransactionManager injected in the Spring application context and the flag mongock.transaction-enabled not false(it accepts null, but it's highly recommended to explicitly set a value).

Keep in mind that your MongoDB database must allow multi-document ACID transactions

@Bean
public MongoTransactionManager transactionManager(MongoTemplate mongoTemplate) {
return new MongoTransactionManager(mongoTemplate.getMongoDbFactory());
}


# MongoDB native drivers

Mongock offers two drivers for MongoDB native drivers. The latest, version Sync 4.x, and the previous major version 3.x, just for those who haven't upgraded yet.

# Get started

Following the get started section, this covers steps 3 and 5 and 6.

# Add maven dependency for the driver (step 2)

<dependency>
<groupId>io.mongock</groupId>
<artifactId>mongodb-driver-sync</artifactId>
<!--<artifactId>mongodb-v3-driver</artifactId> for MongoDB driver v3-->
</dependency>

# Build the driver (setps 5)

These classes provide the same two static initializers

MongoSync4Driver driver = MongoSync4Driver.withDefaultLock(mongoClient, databaseName);

# Driver extra configuration (step 6)

# Transactions

Due to the MongoDB API design, to work with transactions the ClientSession object is required in every operation and then managed the transaction. Mongock make this very simple. The developer only needs to specify a ClientSession parameter in the contructor or method of the @ChangeUnit and use in the MongoDB operations. Mongock takes care of everything else.

The following code shows how to save documents inside the transaction using the ClientSession object.

@Execution
public void execution(ClientSession clientSession, MongoDatabase mongoDatabase) {
mongoDatabase.getCollection(CLIENTS_COLLECTION_NAME, Client.class)
.insertMany(clientSession, IntStream.range(0, INITIAL_CLIENTS)
.mapToObj(ClientInitializerChangeLog::getClient)
.collect(Collectors.toList()));
}


# Examples

Please visit out example projects in [this repo](https://github.com/mongock/mongock-examples/tree/master/mongodb) for more information

# Example autoconfiguration with Springboot

mongock:
mongo-db:
write-concern:
w: majority
wTimeoutMs: 1000
journal: true
read-concern: majority
read-preference: primary
@EnableMongock
@SpringBootApplication
public class QuickStartApp {
/**
* Be wared MongoTemplate needs to be injected
*/
public static void main(String[] args) {
SpringApplicationBuilder().sources(QuickStartApp.class)().run(args);
}
/**
* Transaction Manager.
* Needed to allow execution of changeSets in transaction scope.
*/
@Bean
public MongoTransactionManager transactionManager(MongoTemplate mongoTemplate) {
return new MongoTransactionManager(mongoTemplate.getMongoDbFactory());
}
}

# Example with builder

//this could be the SpringDataMongoV2Driver passing the same paremeter or MongoSync4Driver/MongoCore3Driver passing the MongoClient and databaseName
SpringDataMongoV3Driver driver = SpringDataMongoV3Driver.withDefaultLock(mongoTemplate);
driver.setWriteConcern(WriteConcern.MAJORITY.withJournal(true).withWTimeout(1000, TimeUnit.MILLISECONDS));
driver.setReadConcern(ReadConcern.MAJORITY);
driver.setReadPreference(ReadPreference.primary());