Migration to MongoDB 8.0 - changes to be aware of!
brainCloud BaaS will be upgraded to MongoDB 8.0 on Monday, July 7th, starting at 8 p.m. Eastern. This rolling upgrade may take up to 6 hours to complete. All API and Portal services will be fully available during the upgrade; the portal will NOT be disabled.
[Full disclosure: It will take longer than usual because we are first upgrading to MongoDB 7.0, and then immediately upgrading to MongoDB 8.0.]
Note that all brainCloud Private Instances will be upgraded in the weeks before the end of July 2025.
Compatibility
brainCloud 5.7 has been tested to be fully compatible with MongoDB 8.0.
Important Change (READ THIS!)
MongoDB 8.0 contains an Important Change that brainCloud developers must be aware of.
Starting in MongoDB 8.0, comparisons to
null
in equality match expressions don't matchundefined
values.
Consider the following table:
Records | MongoDB 6 find( { name: null } ) | MongoDB 8 find( { name: null } ) |
{ _id: 1, name: null } | ✅ | ✅ |
{ _id: 2, name: undefined } | ✅ | ❌ |
{ _id:3, name: [ "Gabriel", undefined ] } | ✅ | ❌ |
{ _id:4, names: [ "Alice", "Charu" ] } | ✅ | ✅ |
In MongoDB 6, a query for { "name": null }
would return all 4 records, as per these conditions:
- The
name
field isnull
(_id: 1
) - The
name
field isundefined
or contains anundefined
array element (_id: 2
and_id: 3
) - The
name
field does not exist (_id: 4
)
But in MongoDB 8, the query for { "name": null }
only returns 2 of the records:
- The
name
field isnull
or contains anull
array element (_id: 1
) - The
name
field does not exist (_id: 4
)
Note that this change in query behaviour also affects $eq, $in, and $lookup operations.
For full details on MongoDB compatibility changes:
- MongoDB 7 - https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility/
- MongoDB 8 - https://www.mongodb.com/docs/manual/release-notes/8.0-compatibility/
brainCloud Customer Impact
This change only affects brainCloud's list and paging-style calls (which accept custom query JSON) - and ONLY apply if the JSON data itself somehow had undefined values -- which would be pretty unusual.
The affected calls include:
- Custom Entity - GetEntityPage(), SysGetEntityPage()
- Entity - GetList(), GetListCount(), GetPage()
- Global Entity - GetList(), GetListCount(), GetPage(), GetSystemEntityList() GetSystemEntityListCount(), GetSystemEntityPage()
- Group - ListGroupsPage(), GetRandomGroupsMatching(), ReadGroupEntitiesPage(), SysGetRandomGroupsMatching(), SysListGroupsPage(), SysReadGroupEntitiesPage()
- Item Catalog - GetCatalogItemsPage(), SysGetCatalogItemsPage()
- Leaderboard - SysGetLeaderboardConfigsPage()
- Messaging - GetMessagesPage(), SysGetMessagesPage()
- RedemptionCode - SysGetCodeTypePage()
- User - SysGetPage()
- User Items - GetUserItemsPage()
So - this is ONLY an issue if:
- Your app has "undefined" values in its JSON entities
- AND it is querying on those fields with "undefined" values
- AND it is specifically querying those fields for "null" and expects "undefined" values to be included with the query results.
Take action!
If you do feel that this issue may affect your app, reach out to us in support with the following information:
- appId
- category of entity affected (eg, User, Global, Custom, etc).
- entityType field
- field name <- name of the field with undefined values
We may be able to help you prepare the data so that "undefined" fields are replaced with "null" values to ensure that queries continue to work.