MongoDB

This page covers what is different when Behemoth runs on MongoDB: what the server needs, and how the indexes your schema declares get created.

Setup #

go
import mongoAdapter "github.com/go-behemoth/behemoth/storage/adapters/mongo"

app, err := engine.Prepare(plugins, prepareCfg)
if err != nil {
    return err
}
db := mongoAdapter.NewMongoAdapter(client, "auth", app.Resolver)

// Create the indexes the schema declares. Safe to call on every start.
if err := db.EnsureIndexes(ctx, app.Schemas.All()); err != nil {
    return err
}

ac, err := engine.Boot(ctx, app, db, bootCfg)

Two things are required, and Boot checks both:

RequirementWhyIf it is missing
A replica set or a sharded clusterBehemoth writes users in a transaction, and a standalone server has none. A single-node replica set is enough.Boot returns a configuration error.
The unique indexes the schema declaresWithout them MongoDB stores what they were declared to refuse, for example two users with one email.Boot returns a configuration error that lists them.

Indexes #

There are no migrations for MongoDB. On the SQL databases a migration creates each table with its keys and indexes. On MongoDB you call EnsureIndexes instead.

What EnsureIndexes creates #

It reads the tables you pass and creates, for each one:

DeclaredIndexName
the primary keya unique indexpk_<table>
a column with Uniquea unique indexuq_<table>_<column>
an index of the tablethat indexthe name it was declared with

It behaves as follows:

  • Pass app.Schemas.All(). It holds every table, including the columns and indexes that plugins added to tables they do not own.
  • A unique index on a nullable column only covers documents that have a value, so any number of documents may have none. This matches how the SQL databases treat NULL. MongoDB does not use such an index for lookups, so a second, plain index named <name>_lookup is created with it.
  • Collection and field names are the physical ones the adapter writes.
  • To see the list without touching the database, call db.DeclaredIndexes(app.Schemas.All()).

What it does with indexes that already exist #

EnsureIndexes compares by fields and options, not by name, and it never drops or changes an index.

The collection hasResult
the index alreadynothing happens
the same index under another name, for example an email_1 you creatednothing happens. Your index counts.
a unique index where a plain one is declarednothing happens. It serves the same lookups.
a plain index where a unique one is declaredthe unique index is created next to yours
another index under the declared namean error that names it. Drop or rename that index, then call EnsureIndexes again
documents with the same value in a field that should be uniquean error that names the collection and fields. Remove the duplicates, then call EnsureIndexes again. No document is deleted for you

When an index can't be created, the others are still created, and one error reports every failure.

When to call it #

Follow these rules:

  • Call it before Boot, from a deploy step or at startup. Calling it again when everything exists costs one index listing per collection.
  • Call it again after adding a plugin or changing your schema, so new indexes are created.
  • Call it outside a transaction.
  • Building an index on a large collection takes time, and the call returns when the build is done. For a large existing database, run it from a deploy step and not on the request path of a starting server.

What Boot checks #

Boot compares the declared indexes with the database and creates nothing. It reacts to a missing index as follows:

  • A missing unique index stops Boot. The error lists each one and where it was declared.
  • A missing plain index only makes reads slower. Boot starts and logs a warning for each.

What you still do by hand #

EnsureIndexes only adds. These changes need a manual step in MongoDB:

  • removing the index of a table, column or index you no longer declare
  • replacing an index after you changed its columns, made a unique column not unique, or changed whether a unique column is nullable
  • moving indexes after you renamed a field

Other differences #

  • Foreign keys are not enforced. MongoDB has none, so a row that references a missing user is stored, and deleting a row does not delete the rows that reference it. Store.DeleteUser removes a user's sessions, accounts, and tokens itself, on every database. Delete your own rows that reference a user in a handler on data.user.beforeDelete. See Delete a user.
  • A sign-in that races a user's deletion can leave a session behind. A sign-in that found the user just before Store.DeleteUser commits can still create its session after the commit. A database with foreign keys refuses that insert. MongoDB stores it. Session validation reads the session and not the user, so that session stays valid until it expires, which is SessionConfig.ExpiresIn after sign-in (7 days by default). The window is the time between the sign-in's user lookup and its session insert, which is short. To remove what the race leaves, call RevokeAllForUser on your session manager for the deleted user's id once the deletion has finished. To shorten the exposure, lower ExpiresIn.
  • Hook handlers can run more than once. The driver retries a transaction on a transient error. See Hooks.
  • Dates are stored in milliseconds and read back in UTC.