From c7b9f0f56303cac3123407761c8aad5ba2d1acdc Mon Sep 17 00:00:00 2001 From: Gregor Billing Date: Thu, 21 Aug 2025 00:31:19 +0800 Subject: [PATCH] fix(db-mongodb): disable join aggregations in DocumentDB compatibility mode (#13270) ### What? The PR #12763 added significant improvements for third-party databases that are compatible with the MongoDB API. While the original PR was focused on Firestore, other databases like DocumentDB also benefit from these compatibility features. In particular, the aggregate JOIN strategy does not work on AWS DocumentDB and thus needs to be disabled. The current PR aims to provide this as a sensible default in the `compatibilityOptions` that are provided by Payload out-of-the-box. As a bonus, it also fixes a small typo from `compat(a)bility` to `compat(i)bility`. ### Why? Because our Payload instance, which is backed by AWS DocumentDB, crashes upon trying to access any `join` field. ### How? By adding the existing `useJoinAggregations` with value `false` to the compatiblity layer. Individual developers can still choose to override it in their own local config as needed. --- docs/database/mongodb.mdx | 8 ++++---- packages/db-mongodb/src/index.ts | 2 +- .../{compatabilityOptions.ts => compatibilityOptions.ts} | 5 +++-- test/generateDatabaseAdapter.ts | 4 ++-- 4 files changed, 10 insertions(+), 9 deletions(-) rename packages/db-mongodb/src/utilities/{compatabilityOptions.ts => compatibilityOptions.ts} (80%) diff --git a/docs/database/mongodb.mdx b/docs/database/mongodb.mdx index 26a139bae..f258ae92d 100644 --- a/docs/database/mongodb.mdx +++ b/docs/database/mongodb.mdx @@ -60,21 +60,21 @@ You can access Mongoose models as follows: ## Using other MongoDB implementations -You can import the `compatabilityOptions` object to get the recommended settings for other MongoDB implementations. Since these databases aren't officially supported by payload, you may still encounter issues even with these settings (please create an issue or PR if you believe these options should be updated): +You can import the `compatibilityOptions` object to get the recommended settings for other MongoDB implementations. Since these databases aren't officially supported by payload, you may still encounter issues even with these settings (please create an issue or PR if you believe these options should be updated): ```ts -import { mongooseAdapter, compatabilityOptions } from '@payloadcms/db-mongodb' +import { mongooseAdapter, compatibilityOptions } from '@payloadcms/db-mongodb' export default buildConfig({ db: mongooseAdapter({ url: process.env.DATABASE_URI, // For example, if you're using firestore: - ...compatabilityOptions.firestore, + ...compatibilityOptions.firestore, }), }) ``` -We export compatability options for [DocumentDB](https://aws.amazon.com/documentdb/), [Azure Cosmos DB](https://azure.microsoft.com/en-us/products/cosmos-db) and [Firestore](https://cloud.google.com/firestore/mongodb-compatibility/docs/overview). Known limitations: +We export compatibility options for [DocumentDB](https://aws.amazon.com/documentdb/), [Azure Cosmos DB](https://azure.microsoft.com/en-us/products/cosmos-db) and [Firestore](https://cloud.google.com/firestore/mongodb-compatibility/docs/overview). Known limitations: - Azure Cosmos DB does not support transactions that update two or more documents in different collections, which is a common case when using Payload (via hooks). - Azure Cosmos DB the root config property `indexSortableFields` must be set to `true`. diff --git a/packages/db-mongodb/src/index.ts b/packages/db-mongodb/src/index.ts index 08c8e6cb6..eaa30b435 100644 --- a/packages/db-mongodb/src/index.ts +++ b/packages/db-mongodb/src/index.ts @@ -331,7 +331,7 @@ export function mongooseAdapter({ } } -export { compatabilityOptions } from './utilities/compatabilityOptions.js' +export { compatibilityOptions } from './utilities/compatibilityOptions.js' /** * Attempt to find migrations directory. diff --git a/packages/db-mongodb/src/utilities/compatabilityOptions.ts b/packages/db-mongodb/src/utilities/compatibilityOptions.ts similarity index 80% rename from packages/db-mongodb/src/utilities/compatabilityOptions.ts rename to packages/db-mongodb/src/utilities/compatibilityOptions.ts index bf797895b..6391c1421 100644 --- a/packages/db-mongodb/src/utilities/compatabilityOptions.ts +++ b/packages/db-mongodb/src/utilities/compatibilityOptions.ts @@ -2,9 +2,9 @@ import type { Args } from '../index.js' /** * Each key is a mongo-compatible database and the value - * is the recommended `mongooseAdapter` settings for compatability. + * is the recommended `mongooseAdapter` settings for compatibility. */ -export const compatabilityOptions = { +export const compatibilityOptions = { cosmosdb: { transactionOptions: false, useJoinAggregations: false, @@ -12,6 +12,7 @@ export const compatabilityOptions = { }, documentdb: { disableIndexHints: true, + useJoinAggregations: false, }, firestore: { disableIndexHints: true, diff --git a/test/generateDatabaseAdapter.ts b/test/generateDatabaseAdapter.ts index dd079d4f6..f0f6f4906 100644 --- a/test/generateDatabaseAdapter.ts +++ b/test/generateDatabaseAdapter.ts @@ -22,10 +22,10 @@ export const allDatabaseAdapters = { }, })`, firestore: ` - import { mongooseAdapter, compatabilityOptions } from '@payloadcms/db-mongodb' + import { mongooseAdapter, compatibilityOptions } from '@payloadcms/db-mongodb' export const databaseAdapter = mongooseAdapter({ - ...compatabilityOptions.firestore, + ...compatibilityOptions.firestore, url: process.env.DATABASE_URI || process.env.MONGODB_MEMORY_SERVER_URI ||