MongoDB

// Package.swift (excerpt)
dependencies: [
    .package(url: "https://github.com/vapor/vapor.git", from: "4.122.2"),
    .package(url: "https://github.com/vapor/fluent.git", from: "4.13.0"),
    .package(url: "https://github.com/vapor/fluent-mongo-driver.git", from: "1.4.0"),
],
targets: [
    .executableTarget(name: "App", dependencies: [
        .product(name: "Vapor", package: "vapor"),
        .product(name: "Fluent", package: "fluent"),
        .product(name: "FluentMongoDriver", package: "fluent-mongo-driver"),
    ]),
]

error: type 'ObjectId' does not conform to the 'Sendable' protocol
error: type 'Document' does not conform to the 'Sendable' protocol
error: stored property 'userID' of 'Sendable'-conforming struct 'ReviewSnapshot' has non-Sendable type 'ObjectId'
warning: add '@preconcurrency' to treat 'Sendable'-related errors from module 'BSON' as warnings

import Fluent
@preconcurrency import FluentMongoDriver
import Vapor

enum BookStatus: String, Codable, Sendable { case draft, published, archived }

/// A review embedded in its book document instead of living in its own collection.
struct ReviewSnapshot: Content {
    var userID: ObjectId
    var rating: Int
    var body: String
}

final class Author: Model, @unchecked Sendable {
    static let schema = "authors"

    @ID(custom: .id) var id: ObjectId?
    @Field(key: "name") var name: String
    @OptionalField(key: "bio") var bio: String?
    @Children(for: \.$author) var books: [Book]

    init() {}
    init(id: ObjectId? = nil, name: String, bio: String? = nil) {
        self.id = id
        self.name = name
        self.bio = bio
    }
}

final class Book: Model, @unchecked Sendable {
    static let schema = "books"

    @ID(custom: .id) var id: ObjectId?
    @Field(key: "title") var title: String
    @Field(key: "isbn") var isbn: String
    @Field(key: "published_year") var publishedYear: Int
    @Field(key: "price_cents") var priceCents: Int
    @Enum(key: "status") var status: BookStatus
    @Parent(key: "author_id") var author: Author
    @Timestamp(key: "created_at", on: .create) var createdAt: Date?
    @Timestamp(key: "updated_at", on: .update) var updatedAt: Date?

    // Page-local additions: nested data instead of the tags/reviews tables of the SQL model set.
    @Field(key: "tags") var tags: [String]
    @Field(key: "reviews") var reviews: [ReviewSnapshot]
    @OptionalField(key: "metadata") var metadata: Document?

    init() {}
    init(
        id: ObjectId? = nil, title: String, isbn: String, publishedYear: Int, priceCents: Int,
        status: BookStatus = .draft, authorID: ObjectId, tags: [String] = []
    ) {
        self.id = id
        self.title = title
        self.isbn = isbn
        self.publishedYear = publishedYear
        self.priceCents = priceCents
        self.status = status
        self.$author.id = authorID
        self.tags = tags
        self.reviews = []
        self.metadata = nil
    }
}

import Fluent
@preconcurrency import FluentMongoDriver
import Vapor

struct CreateBookshelfCollections: AsyncMigration {
    func prepare(on database: any Database) async throws {
        // On MongoDB a schema builder only creates indexes for unique constraints; fields are ignored.
        try await database.schema(Author.schema).create()
        try await database.schema(Book.schema).unique(on: "isbn").create()
    }

    func revert(on database: any Database) async throws {
        try await database.schema(Book.schema).delete()
        try await database.schema(Author.schema).delete()
    }
}

/// Indexes the schema builder cannot express: plain (non-unique), text and TTL indexes need MongoKitten.
struct AddBookSearchIndexes: AsyncMigration {
    func prepare(on database: any Database) async throws {
        guard let mongo = database as? any MongoDatabaseRepresentable else { throw FluentMongoError.notMongoDB }
        let books = mongo.raw[Book.schema]
        // Legacy bridge: MongoKitten 6.7.15's createIndex returns EventLoopFuture and has no async overload.
        try await books.createIndex(named: "published_year_1", keys: ["published_year": 1]).get()
        try await books.createIndex(named: "title_text", keys: ["title": "text"]).get()
    }

    func revert(on database: any Database) async throws {
        // MongoKitten 6.7.15 has no dropIndex helper; run db.books.dropIndex("title_text") in mongosh,
        // or drop the whole collection in the migration that created it.
    }
}

func createBook(_ book: Book, on database: any Database) async throws {
    do {
        try await book.create(on: database)
    } catch FluentMongoError.insertFailed {
        // A duplicate isbn reaches Fluent as insertFailed: the driver does not surface the 11000 code.
        throw Abort(.conflict, reason: "A book with this ISBN may already exist")
    }
}

@testable import App
import Fluent
@preconcurrency import FluentMongoDriver
import Testing
import Vapor
import VaporTesting

@Suite("Query translation without a server")
struct QueryTranslationTests {
    /// Runs `body` against an application whose MongoDB host does not exist.
    /// The driver connects lazily and logs the command it builds before it needs a connection,
    /// so the debug log shows the translation even though every query then fails.
    func withOfflineApp(_ body: (Application) async throws -> Void) async throws {
        let app = try await Application.make(.testing)
        app.logger.logLevel = .debug
        try app.databases.use(.mongo(connectionString: "mongodb://127.0.0.1:1/bookshelf?connectTimeoutMS=300"), as: .mongo)
        do {
            try await body(app)
        } catch {
            try await app.asyncShutdown()
            throw error
        }
        try await app.asyncShutdown()
    }

    @Test func fluentDatabaseIsMongoDatabaseRepresentable() async throws {
        try await withOfflineApp { app in
            let mongo = try #require(app.db as? any MongoDatabaseRepresentable)
            #expect(mongo.raw.name == "bookshelf")
        }
    }

    @Test func containsBuildsAnUnescapedRegex() async throws {
        try await withOfflineApp { app in
            // Fails with a connection error, after logging: filter=["title": ["$regex": ".*a.b.*"]]
            _ = try? await Book.query(on: app.db).filter(\.$title ~~ "a.b").all()
        }
    }

    @Test func deleteWithLimitIsRejected() async throws {
        try await withOfflineApp { app in
            await #expect(throws: FluentMongoError.self) {
                try await Book.query(on: app.db).limit(5).delete()
            }
        }
    }

    @Test func missingDatabaseNameIsRejected() throws {
        #expect(throws: FluentMongoError.self) {
            _ = try DatabaseConfigurationFactory.mongo(connectionString: "mongodb://127.0.0.1:27017")
        }
    }

    @Test func malformedUriIsRejected() throws {
        #expect(throws: (any Error).self) {
            _ = try DatabaseConfigurationFactory.mongo(connectionString: "postgres://127.0.0.1/bookshelf")
        }
    }

    @Test func objectIdIsAHexStringInJSON() throws {
        let review = ReviewSnapshot(userID: ObjectId(), rating: 5, body: "Great")
        let json = String(decoding: try JSONEncoder().encode(review), as: UTF8.self)
        let back = try JSONDecoder().decode(ReviewSnapshot.self, from: Data(json.utf8))
        #expect(back.userID == review.userID)
        #expect(json.contains(review.userID.hexString))
    }
}

filter(\.$title ~~ "a.b")
  find "books" filter: ["title": ["$regex": ".*a.b.*"]]

filter(\.$title =~ "Swift").filter(\.$isbn ~= "X")
  find "books" filter: ["$and": [["title": ["$regex": "Swift.*"]], ["isbn": ["$regex": ".*X"]]]]

group(.or) { status == .draft, publishedYear > 2020 }.sort(\.$title, .descending).range(10..<20)
  find "books" filter: ["$or": [["status": ["$eq": "draft"]], ["published_year": ["$gt": 2020]]]]
       sort: ["title": -1]  skip: 10  limit: 10

filter("tags", .equal, "swift").filter("metadata.publisher", .equal, "Packt")
  find "books" filter: ["$and": [["tags": ["$eq": "swift"]], ["metadata.publisher": ["$eq": "Packt"]]]]

filter(.custom(["title": ["$regex": "^swift", "$options": "i"]]))
  find "books" filter: ["title": ["$regex": "^swift", "$options": "i"]]

filter(\.$status == .published).count()
  count condition: ["status": ["$eq": "published"]]

sum(\.$priceCents)
  find-group operation=$sum field=price_cents condition=[]

batch: filter(\.$status == .draft).set(\.$priceCents, to: 0).update()
  update filter: ["status": ["$eq": "draft"]]  updates: [["price_cents": 0, "updated_at": 2026-10-17 15:29:31 +0000]]

import Fluent
@preconcurrency import FluentMongoDriver
@preconcurrency import MongoKitten
import Vapor

struct BookDTO: Content {
    var id: String?
    var title: String
    var isbn: String
    var tags: [String]
    var reviewCount: Int
}

extension Book {
    func toDTO() -> BookDTO {
        BookDTO(id: id?.hexString, title: title, isbn: isbn, tags: tags, reviewCount: reviews.count)
    }
}

struct BookSearch: Content {
    var q: String?
    var tag: String?
    var publisher: String?
}

struct AuthorStats: Content {
    var authorID: ObjectId
    var books: Int
    var avgPriceCents: Double
}

struct BookController: RouteCollection {
    func boot(routes: any RoutesBuilder) throws {
        let books = routes.grouped("books")
        books.get("search", use: search)
        books.get("stats", use: stats)
        books.post(":bookID", "reviews", use: addReview)
    }

    @Sendable func search(req: Request) async throws -> [BookDTO] {
        let criteria = try req.query.decode(BookSearch.self)
        let query = Book.query(on: req.db).sort(\.$title)
        if let text = criteria.q {
            // Case-insensitive title match; the text is escaped, so "C++" matches literally.
            var title = Document()
            title["title"]["$regex"] = NSRegularExpression.escapedPattern(for: text)
            title["title"]["$options"] = "i"
            query.filter(.custom(title))
        }
        if let tag = criteria.tag {
            query.filter("tags", .equal, tag) // matches when the array contains the element
        }
        if let publisher = criteria.publisher {
            query.filter("metadata.publisher", .equal, publisher) // dot-notation into a nested document
        }
        return try await query.all().map { $0.toDTO() }
    }

    @Sendable func stats(req: Request) async throws -> [AuthorStats] {
        guard let mongo = req.db as? any MongoDatabaseRepresentable else {
            throw Abort(.internalServerError, reason: "Not a MongoDB database")
        }
        var group = Document()
        group["_id"] = "$author_id"
        group["books"] = ["$sum": 1] as Document
        group["avgPriceCents"] = ["$avg": "$price_cents"] as Document
        let pipeline = mongo.raw[Book.schema].aggregate([
            AggregateBuilderStage(document: ["$group": group]),
            AggregateBuilderStage(document: ["$sort": ["avgPriceCents": -1] as Document]),
        ])
        let documents = try await pipeline.decode(Raw.self).allResults()
        return documents.map { AuthorStats(authorID: $0._id, books: $0.books, avgPriceCents: $0.avgPriceCents) }
    }

    private struct Raw: Decodable {
        var _id: ObjectId
        var books: Int
        var avgPriceCents: Double
    }

    @Sendable func addReview(req: Request) async throws -> HTTPStatus {
        guard let id = req.parameters.get("bookID", as: ObjectId.self) else { throw Abort(.badRequest) }
        let review = try req.content.decode(ReviewSnapshot.self)
        guard let book = try await Book.find(id, on: req.db) else { throw Abort(.notFound) }
        book.reviews.append(review)
        try await book.update(on: req.db)
        return .created
    }
}

func routes(_ app: Application) throws {
    try app.register(collection: BookController())
}

find "books" filter: ["$and": [["title": ["$regex": "C\\+\\+", "$options": "i"]],
                              ["tags": ["$eq": "swift"]],
                              ["metadata.publisher": ["$eq": "Packt"]]]]  sort: ["title": 1]

# not run against a live server
curl -s 'http://localhost:8080/books/search?q=swift&tag=vapor'
curl -s 'http://localhost:8080/books/stats'
curl -s -X POST http://localhost:8080/books/65f0a1b2c3d4e5f607182930/reviews \
  -H 'content-type: application/json' \
  -d '{"userID":"65f0a1b2c3d4e5f607182931","rating":5,"body":"Clear and practical"}'

POST /books/not-an-object-id/reviews  ->  400 {"error":true,"reason":"Bad Request"}

@testable import App
import Testing
import Vapor
import VaporTesting

@Suite("Routes that do not need MongoDB")
struct RouteStatusTests {
    @Test func malformedObjectIdIsABadRequest() async throws {
        let app = try await Application.make(.testing)
        try await configure(app)
        try await app.testing().test(.POST, "books/not-an-object-id/reviews", beforeRequest: { req in
            try req.content.encode(["rating": 5])
        }, afterResponse: { res async in
            #expect(res.status == .badRequest)
        })
        try await app.asyncShutdown()
    }
}

guard let mongo = req.db as? any MongoDatabaseRepresentable else {
    throw Abort(.internalServerError, reason: "Not a MongoDB database")
}
let books = mongo.raw[Book.schema]   // a MongoKitten MongoCollection

import Vapor
@preconcurrency import MongoKitten

/// A catalog entry stored by MongoKitten without Fluent.
struct CatalogEntry: Codable, Sendable {
    var _id: ObjectId
    var title: String
    var tags: [String]
}

/// MongoKitten's `MongoDatabase` is a reference type that is not marked `Sendable`.
struct DirectMongo: @unchecked Sendable {
    let database: MongoDatabase
}

extension Application {
    private struct DirectMongoKey: StorageKey { typealias Value = DirectMongo }

    var directMongo: DirectMongo {
        get {
            guard let value = self.storage[DirectMongoKey.self] else {
                fatalError("Call configureDirectMongo(_:url:) first")
            }
            return value
        }
        set { self.storage[DirectMongoKey.self] = newValue }
    }
}

struct DirectMongoShutdown: LifecycleHandler {
    func shutdownAsync(_ application: Application) async {
        if let cluster = application.directMongo.database.pool as? MongoCluster {
            try? await cluster.disconnect().get()
        }
    }
}

func configureDirectMongo(_ app: Application, url: String) throws {
    let database = try MongoDatabase.lazyConnect(url, on: app.eventLoopGroup)
    app.directMongo = DirectMongo(database: database)
    app.lifecycle.use(DirectMongoShutdown())
}

func catalogRoutes(_ app: Application) {
    app.get("catalog", "search") { req async throws -> [String] in
        let tag = try req.query.get(String.self, at: "tag")
        let entries = req.application.directMongo.database["catalog"]
        let found = try await entries.find(["tags": tag] as Document).decode(CatalogEntry.self).allResults()
        return found.map(\.title)
    }
    app.post("catalog") { req async throws -> HTTPStatus in
        let title = try req.query.get(String.self, at: "title")
        let entries = req.application.directMongo.database["catalog"]
        _ = try await entries.async.insertEncoded(CatalogEntry(_id: ObjectId(), title: title, tags: ["new"]))
        return .created
    }
}