MongoDB Setup

Before you can map documents you need a running MongoDB instance and the right connection properties. Spring Boot’s spring.data.mongodb.* properties let you connect with either a single connection URI or discrete host/port/database settings.

Connection with a URI

The simplest and most portable approach is a single connection string. The database name goes at the end of the path.

spring.data.mongodb.uri=mongodb://localhost:27017/shopdb

The equivalent YAML:

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/shopdb

Tip: Prefer the URI form. It is the same string MongoDB tools and other languages use, and it cleanly carries options like replica set, auth source, and TLS as query parameters.

Connection with discrete properties

If you would rather not build a URI, set the parts individually. Do not combine these with spring.data.mongodb.uri — the URI wins and the discrete properties are ignored.

spring:
  data:
    mongodb:
      host: localhost
      port: 27017
      database: shopdb

Authentication

Production MongoDB requires credentials. With a URI, put them before the host and set the authSource (the database that holds the user, often admin).

spring.data.mongodb.uri=mongodb://appuser:s3cret@localhost:27017/shopdb?authSource=admin

With discrete properties:

spring:
  data:
    mongodb:
      host: localhost
      port: 27017
      database: shopdb
      username: appuser
      password: ${MONGO_PASSWORD}
      authentication-database: admin

Warning: Never commit credentials. Inject the password from an environment variable or a secrets manager using a placeholder like ${MONGO_PASSWORD}. See Externalized Configuration.

Running MongoDB with Docker

The fastest way to get a local instance is Docker. This starts MongoDB 7 with a root user.

docker run -d --name mongo \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=root \
  -e MONGO_INITDB_ROOT_PASSWORD=example \
  mongo:7

Connect with credentials and authSource=admin:

spring.data.mongodb.uri=mongodb://root:example@localhost:27017/shopdb?authSource=admin

For tests, prefer Testcontainers, which spins up a throwaway MongoDB per test run. See Testcontainers.

MongoDB Atlas

Atlas is MongoDB’s managed cloud service. Create a free cluster, add a database user, allow your IP, then copy the mongodb+srv connection string from the Connect dialog. The +srv scheme resolves the replica set hosts via DNS automatically.

spring.data.mongodb.uri=mongodb+srv://appuser:${MONGO_PASSWORD}@cluster0.ab12c.mongodb.net/shopdb?retryWrites=true&w=majority

Atlas requires TLS, which is on by default for mongodb+srv, so no extra configuration is needed.

Note: retryWrites=true and w=majority are sensible defaults for Atlas — they retry transient write failures and acknowledge writes only after a majority of nodes confirm them.

Auto-index creation

Spring Data can create the indexes you declare with @Indexed or @CompoundIndex automatically. In Spring Boot 3.x this is disabled by default for safety, so enable it explicitly during development.

spring:
  data:
    mongodb:
      auto-index-creation: true

When true, Spring scans your @Document classes on startup and ensures the declared indexes exist. See @Document Mapping for the index annotations.

Warning: Building indexes on a large existing collection can be expensive and block writes. In production, prefer to create indexes deliberately as part of a managed migration rather than relying on auto-index-creation.

Verifying the connection

A simple health check confirms wiring. With the actuator on the classpath, the MongoDB health indicator pings the server.

GET /actuator/health

{
  "status": "UP",
  "components": {
    "mongo": { "status": "UP", "details": { "maxWireVersion": 21 } }
  }
}

You can also assert the connection at startup with a CommandLineRunner:

@Bean
CommandLineRunner ping(MongoTemplate template) {
    return args -> System.out.println(
        "Connected to: " + template.getDb().getName());
}

Output:

Connected to: shopdb