From b4901f6f2af4ed6513f0ed1c3caf8746385af787 Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Thu, 13 Jun 2024 15:52:53 +0200
Subject: [PATCH 1/3] docs: add documentation for
 WordPress.DB.DirectDatabaseQuery

---
 .../Docs/DB/DirectDatabaseQueryStandard.xml   | 119 ++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 WordPress/Docs/DB/DirectDatabaseQueryStandard.xml

diff --git a/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
new file mode 100644
index 0000000000..c1312e7fc8
--- /dev/null
+++ b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
@@ -0,0 +1,119 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Direct Database Query"
+    >
+    <standard>
+    <![CDATA[
+    You should not make direct database queries, but instead use abstractions such as WP_Query.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using WP_Query to retrieve data.">
+        <![CDATA[
+$my_query = new WP_Query(
+    [
+        'post_type' => 'foo',
+    ]
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using a direct query to retrieve data.">
+        <![CDATA[
+$results = $wpdb->get_results(
+    $wpdb->prepare(
+        "SELECT * FROM x WHERE y = %s",
+        'foo',
+    ),
+);
+        ]]>
+        </code>
+    </code_comparison>
+
+    <standard>
+    <![CDATA[
+    You should not make direct database queries without caching.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: The results of a direct database query are stored in the object cache.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+    
+    $cached = wp_cache_get( 'foo' );
+    if ( false !== $cached ) {
+        return $cached;
+    }
+
+    $results = $wpdb->query(
+        'SELECT x FROM foo'
+    );
+
+    wp_cache_set( 'foo', $results );
+    return $results;
+}
+        ]]>
+        </code>
+        <code title="Invalid: Direct database query is made without leveraging the object cache.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+    return $wpdb->query( 'SELECT x FROM foo' );
+}
+        ]]>
+        </code>
+    </code_comparison>
+    <code_comparison>
+        <code title="Valid: The results of a direct database query are stored in the object cache.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+
+    $cached = wp_cache_get( 'foo' );
+    if ( false !== $cached ) {
+        return $cached;
+    }
+
+    $results = $wpdb->query(
+        'SELECT x FROM foo'
+    );
+
+    wp_cache_set( 'foo', $results );
+    return $results;
+}
+        ]]>
+        </code>
+        <code title="Invalid: Incorrect implementation of caching with a direct database query.">
+        <![CDATA[
+function foo() {
+    global $wpdb;
+    $results = $wpdb->query(
+        'SELECT * from foo'
+    );
+
+    wp_cache_set( 'foo', $results );
+    return $results;
+}
+        ]]>
+        </code>
+    </code_comparison>
+
+    <standard>
+    <![CDATA[
+    You should not make direct database queries to alter the database schema.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Altering database schema using the dbDelta function.">
+        <![CDATA[
+dbDelta( 'CREATE TABLE foo' );
+        ]]>
+        </code>
+        <code title="Invalid: Altering database schema using a direct database query.">
+        <![CDATA[
+$wpdb->query( 'CREATE TABLE foo' );
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>

From 910738f37e9089aca93a6ba05e40a72c1ef7f541 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Mon, 9 Feb 2026 15:16:26 -0300
Subject: [PATCH 2/3] Improve WordPress.DB.DirectDatabaseQuery documentation

- Rewrite standard descriptions to explain why each rule exists.
- Add <em> tags to highlight key parts in code examples.
- Use realistic code examples.
- Replace second caching example with a write + cache invalidation
  pattern.
- Wrap caching examples in functions, as the sniff always generates
  a NoCaching warning if the caching code is not inside a function.
- Remove dbDelta() recommendation from SchemaChange section. I
  believe the original intent of the rule is to discourage schema
  changes and not suggest dbDelta() is used.
- Remove SchemaChange code comparison (no valid alternative).
---
 .../Docs/DB/DirectDatabaseQueryStandard.xml   | 100 ++++++++----------
 1 file changed, 45 insertions(+), 55 deletions(-)

diff --git a/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
index c1312e7fc8..7b9c12b700 100644
--- a/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
+++ b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
@@ -5,115 +5,105 @@
     >
     <standard>
     <![CDATA[
-    You should not make direct database queries, but instead use abstractions such as WP_Query.
+    Direct database queries using $wpdb methods should be avoided. WordPress database abstraction layers handle caching, data integrity, and firing of hooks, which direct queries bypass.
     ]]>
     </standard>
     <code_comparison>
         <code title="Valid: Using WP_Query to retrieve data.">
         <![CDATA[
-$my_query = new WP_Query(
-    [
-        'post_type' => 'foo',
-    ]
+$page_query = new <em>WP_Query</em>(
+    array(
+        'post_type' => 'page',
+    )
 );
         ]]>
         </code>
         <code title="Invalid: Using a direct query to retrieve data.">
         <![CDATA[
-$results = $wpdb->get_results(
+$results = <em>$wpdb->get_results</em>(
     $wpdb->prepare(
-        "SELECT * FROM x WHERE y = %s",
-        'foo',
-    ),
+        "SELECT * FROM %i
+            WHERE post_type = %s",
+        $wpdb->posts,
+        'page'
+    )
 );
         ]]>
         </code>
     </code_comparison>
-
     <standard>
     <![CDATA[
-    You should not make direct database queries without caching.
+    When a direct database call is necessary, it should be paired with caching. For read queries, this avoids running expensive queries multiple times. For write queries, invalidating relevant caches prevents stale data.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: The results of a direct database query are stored in the object cache.">
+        <code title="Valid: Direct query results are cached and retrieved from cache when available.">
         <![CDATA[
-function foo() {
-    global $wpdb;
-    
-    $cached = wp_cache_get( 'foo' );
+function get_draft_ids() {
+    $key = 'my_plugin_draft_ids';
+    $cached = <em>wp_cache_get</em>( $key );
+
     if ( false !== $cached ) {
         return $cached;
     }
 
-    $results = $wpdb->query(
-        'SELECT x FROM foo'
+    $results = $wpdb->get_col(
+        "SELECT ID FROM $wpdb->posts
+            WHERE post_status = 'draft'"
     );
 
-    wp_cache_set( 'foo', $results );
+    <em>wp_cache_set</em>( $key, $results );
+
     return $results;
 }
         ]]>
         </code>
-        <code title="Invalid: Direct database query is made without leveraging the object cache.">
+        <code title="Invalid: Direct query without caching.">
         <![CDATA[
-function foo() {
-    global $wpdb;
-    return $wpdb->query( 'SELECT x FROM foo' );
+function get_draft_ids() {
+    $results = $wpdb->get_col(
+        "SELECT ID FROM $wpdb->posts
+            WHERE post_status = 'draft'"
+    );
+
+    return $results;
 }
         ]]>
         </code>
     </code_comparison>
     <code_comparison>
-        <code title="Valid: The results of a direct database query are stored in the object cache.">
+        <code title="Valid: Cache is invalidated after a write query.">
         <![CDATA[
-function foo() {
+function update_post_title() {
     global $wpdb;
 
-    $cached = wp_cache_get( 'foo' );
-    if ( false !== $cached ) {
-        return $cached;
-    }
-
-    $results = $wpdb->query(
-        'SELECT x FROM foo'
+    $wpdb->update(
+        $wpdb->posts,
+        array( 'post_title' => $title ),
+        array( 'ID' => $post_id )
     );
 
-    wp_cache_set( 'foo', $results );
-    return $results;
+    <em>clean_post_cache</em>( $post_id );
 }
         ]]>
         </code>
-        <code title="Invalid: Incorrect implementation of caching with a direct database query.">
+        <code title="Invalid: Write query without cache invalidation.">
         <![CDATA[
-function foo() {
+function update_post_title() {
     global $wpdb;
-    $results = $wpdb->query(
-        'SELECT * from foo'
-    );
 
-    wp_cache_set( 'foo', $results );
-    return $results;
+    $wpdb->update(
+        $wpdb->posts,
+        array( 'post_title' => $title ),
+        array( 'ID' => $post_id )
+    );
 }
         ]]>
         </code>
     </code_comparison>
-
     <standard>
     <![CDATA[
-    You should not make direct database queries to alter the database schema.
+    Altering the database schema is discouraged, as it can break WordPress core, plugins, or themes that depend on the existing schema.
     ]]>
     </standard>
-    <code_comparison>
-        <code title="Valid: Altering database schema using the dbDelta function.">
-        <![CDATA[
-dbDelta( 'CREATE TABLE foo' );
-        ]]>
-        </code>
-        <code title="Invalid: Altering database schema using a direct database query.">
-        <![CDATA[
-$wpdb->query( 'CREATE TABLE foo' );
-        ]]>
-        </code>
-    </code_comparison>
 </documentation>

From 2a8fc578cc114392ef198b37671ea75656f7e3bb Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Thu, 26 Feb 2026 09:01:13 -0300
Subject: [PATCH 3/3] Apply suggestions from code review

Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 .../Docs/DB/DirectDatabaseQueryStandard.xml   | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
index 7b9c12b700..d727c064e8 100644
--- a/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
+++ b/WordPress/Docs/DB/DirectDatabaseQueryStandard.xml
@@ -5,7 +5,7 @@
     >
     <standard>
     <![CDATA[
-    Direct database queries using $wpdb methods should be avoided. WordPress database abstraction layers handle caching, data integrity, and firing of hooks, which direct queries bypass.
+    Direct database queries using WPDB class methods should be avoided. WordPress database abstraction layers handle caching, data integrity, and firing of hooks, which direct queries bypass.
     ]]>
     </standard>
     <code_comparison>
@@ -103,7 +103,22 @@ function update_post_title() {
     </code_comparison>
     <standard>
     <![CDATA[
-    Altering the database schema is discouraged, as it can break WordPress core, plugins, or themes that depend on the existing schema.
+    Altering the database schema using ALTER, CREATE, or DROP statements is discouraged, as it can break WordPress core, plugins, or themes that depend on the existing schema.
     ]]>
     </standard>
+    <code_comparison>
+        <code title="Valid: Not altering the database schema.">
+        <![CDATA[
+// Do not use ALTER, CREATE, or DROP.
+        ]]>
+        </code>
+        <code title="Invalid: Altering the database schema.">
+        <![CDATA[
+$wpdb->query(
+    "<em>ALTER</em> TABLE {$wpdb->posts}
+        ADD COLUMN rating int"
+);
+        ]]>
+        </code>
+    </code_comparison>
 </documentation>