Skip to main content

Getting started

Maven Central

mongo4cats is a Scala wrapper around the MongoDB Java Reactive Streams driver. It provides a purely functional, type-safe API for working with MongoDB, built on top of Cats Effect and FS2. A ZIO 2 integration is also available.

Features​

  • Purely functional API using IO / ZIO
  • Streaming support via FS2 / ZIO Streams for large result sets
  • Type-safe query builders for filters, projections, sorts, updates, and aggregations
  • Automatic BSON codec derivation via Circe or ZIO JSON
  • Transaction support
  • Bulk write operations
  • Change stream (watch) support
  • Embedded MongoDB for testing

Supported Scala versions​

Scala 2.12, Scala 2.13, and Scala 3.9.0 or later are supported.

Dependencies​

Add the core module to your build.sbt:

libraryDependencies += "io.github.kirill5k" %% "mongo4cats-core" % "<version>"

For automatic BSON codec derivation via Circe:

libraryDependencies += "io.github.kirill5k" %% "mongo4cats-circe" % "<version>"

For automatic BSON codec derivation via ZIO JSON:

libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-json" % "<version>"

For embedded MongoDB in tests (Cats Effect):

libraryDependencies += "io.github.kirill5k" %% "mongo4cats-embedded" % "<version>" % Test

For ZIO 2 integration:

libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio" % "<version>"
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-embedded" % "<version>" % Test

Quick example​

import cats.effect.{IO, IOApp}
import mongo4cats.bson.Document
import mongo4cats.bson.syntax._
import mongo4cats.client.MongoClient
import mongo4cats.operations.Filter

object QuickStart extends IOApp.Simple {
  override val run: IO[Unit] =
    MongoClient.fromConnectionString[IO]("mongodb://localhost:27017").use { client =>
      for {
        db   <- client.getDatabase("mydb")
        coll <- db.getCollection("users")
        _    <- coll.insertMany(List(
                  Document("name" := "Alice", "age" := 30),
                  Document("name" := "Bob",   "age" := 25)
                ))
        docs <- coll.find(Filter.gte("age", 28)).all
        _    <- IO.println(s"Found: $docs")
      } yield ()
    }
}

Next steps​