feat: add deprecation on explain

Author: coratgerl

DEPRECATIONS.md

@@ -14,7 +14,8 @@ The following is a list of deprecations, according to the [Deprecation Policy](h
 | DEPPS8 | Login with expired 3rd party authentication token defaults to `false` | [#7079](https://github.com/parse-community/parse-server/pull/7079)   | 5.3.0 (2022)                    | 7.0.0 (2024)                    | removed            | -     |
 | DEPPS9 | Rename LiveQuery `fields` option to `keys` | [#8389](https://github.com/parse-community/parse-server/issues/8389)   | 6.0.0 (2023)                    | 7.0.0 (2024)                    | removed            | -     |
 | DEPPS10 | Encode `Parse.Object` in Cloud Function and remove option `encodeParseObjectInCloudFunction` | [#8634](https://github.com/parse-community/parse-server/issues/8634)   | 6.2.0 (2023)                    | 9.0.0 (2026)                    | deprecated            | -     |
-| DEPPS11 | Replace `PublicAPIRouter` with `PagesRouter` | [#7625](https://github.com/parse-community/parse-server/issues/7625)   | 8.0.0 (2025)                    | 9.0.0 (2026)                    | deprecated            | -     |
+| DEPPS11 | Replace `PublicAPIRouter` with `PagesRouter` | [#7625](https://github.com/parse-community/parse-server/issues/7625)   | 8.0.0 (2025)                    | 9.0.0 (2026)     
+| DEPPS12 | Restrict `explain` query parameter to master key                                             | [#7519](https://github.com/parse-community/parse-server/issues/7519) | 8.3.0 (2025)                    | 9.0.0 (2027)                    | deprecated            |               | deprecated            | -     |
 
 [i_deprecation]: ## "The version and date of the deprecation."
 [i_removal]: ## "The version and date of the planned removal."

changelogs/CHANGELOG_alpha.md

@@ -1,3 +1,9 @@
+# [8.3.0-alpha.13](https://github.com/parse-community/parse-server/compare/8.3.0-alpha.12...8.3.0-alpha.13) (2025-10-25)
+
+### Features
+
+- Deprecation DEPPS12: `explain` query parameter without master key ([#7519](https://github.com/parse-community/parse-server/issues/7519)) ([DEPPS12](https://github.com/parse-community/parse-server/blob/alpha/DEPRECATIONS.md#depps12))
+
 # [8.3.0-alpha.12](https://github.com/parse-community/parse-server/compare/8.3.0-alpha.11...8.3.0-alpha.12) (2025-10-25)
 
 

spec/ParseQuery.spec.js

@@ -5384,4 +5384,40 @@ describe('Parse.Query testing', () => {
       expect(query1.length).toEqual(1);
     });
   });
+
+  it_id('DEPPS12')(it_only_db('mongo'))(
+    'throws error when using explain without master key',
+    async () => {
+      const obj = new TestObject({ foo: 'bar' });
+      await obj.save();
+
+      const spyLogRuntimeDeprecation = spyOn(Deprecator, 'logRuntimeDeprecation');
+
+      // Test that explain without master key throws an error
+      const query = new Parse.Query(TestObject);
+      query.explain();
+
+      try {
+        await query.find();
+
+        expect(spyLogRuntimeDeprecation).toHaveBeenCalledTimes(1);
+        expect(spyLogRuntimeDeprecation).toHaveBeenCalledWith({
+          usage: 'Using the explain query parameter without the master key',
+        });
+        // fail('Should have thrown an error');
+      } catch (error) {
+        // Uncomment this after the Deprecation DEPPS12
+        // expect(error.code).toEqual(Parse.Error.INVALID_QUERY);
+        // expect(error.message).toEqual('Using the explain query parameter without the master key');
+      }
+
+      // Test that explain with master key works fine
+      const queryWithMasterKey = new Parse.Query(TestObject);
+      queryWithMasterKey.explain();
+      const result = await queryWithMasterKey.find({ useMasterKey: true });
+
+      // Should return explain result (not throw error)
+      expect(result).toBeDefined();
+    }
+  );
 });

src/rest.js

@@ -13,6 +13,7 @@ var RestQuery = require('./RestQuery');
 var RestWrite = require('./RestWrite');
 var triggers = require('./triggers');
 const { enforceRoleSecurity } = require('./SharedRest');
+const Deprecator = require('./Deprecator/Deprecator');
 
 function checkTriggers(className, config, types) {
   return types.some(triggerType => {
@@ -35,6 +36,19 @@ async function runFindTriggers(
 ) {
   const { isGet } = options;
 
+  if (restOptions && restOptions.explain && !auth.isMaster) {
+    // After the Deprecation DEPPS12 uncomment this to throw an error
+    // throw new Parse.Error(
+    //   Parse.Error.INVALID_QUERY,
+    //   'Using the explain query parameter without the master key'
+    // );
+
+    // Deprecation DEPPS12
+    Deprecator.logRuntimeDeprecation({
+      usage: 'Using the explain query parameter without the master key',
+    });
+  }
+
   // Run beforeFind trigger - may modify query or return objects directly
   const result = await triggers.maybeRunQueryTrigger(
     triggers.Types.beforeFind,