MDL-87703 dml: Introduce mark_tables_for_primary method

Author: cameron1729

public/lib/dml/moodle_database.php

@@ -2919,6 +2919,18 @@ public function perf_get_reads_replica(): int {
         return 0;
     }
 
+    /**
+     * Mark one or more tables as requiring reads from the primary (writer) connection.
+     *
+     * This is useful in a read replica setup, where code wants to avoid subtle race
+     * conditions by ensuring reads are routed to the writer before an imminent write.
+     *
+     * @param string ...$tables Unprefixed table names (e.g., 'user', 'task_adhoc').
+     */
+    public function mark_tables_for_primary(string ...$tables): void {
+        // No-op by default. Drivers supporting read replicas override this.
+    }
+
     /**
      * Returns the number of writes done by this database.
      * @return int Number of writes.

public/lib/dml/moodle_read_replica_trait.php

@@ -14,6 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+use core\exception\coding_exception;
+
 /**
  * Trait that adds read-only replica connection capability.
  *
@@ -305,6 +307,35 @@ public function perf_get_reads_replica(): int {
         return $this->readsreplica;
     }
 
+    /**
+     * Mark one or more tables as requiring reads from the primary (writer) connection.
+     *
+     * This marks the provided table(s) as having been recently written which forces
+     * SELECT queries on those tables to be routed to the writer until the configured
+     * replica latency has elapsed.
+     *
+     * @param string ...$tables Unprefixed table names (e.g., 'user', 'task_adhoc').
+     * @throws coding_exception If an invalid table name is provided.
+     */
+    public function mark_tables_for_primary(string ...$tables): void {
+        if (!$this->wantreadreplica || empty($tables)) {
+            return;
+        }
+
+        $now = microtime(true);
+        foreach ($tables as $tablename) {
+            if (empty($tablename)) {
+                throw new coding_exception('Table name must not be empty');
+            }
+
+            if (!preg_match('/^[a-z][a-z0-9_]*$/', $tablename)) {
+                throw new coding_exception('Invalid table name: '.$tablename);
+            }
+
+            $this->written[$tablename] = $now;
+        }
+    }
+
     /**
      * On DBs that support it, switch to transaction mode and begin a transaction.
      *

public/lib/dml/tests/dml_read_replica_test.php

@@ -51,6 +51,7 @@ final class dml_read_replica_test extends \database_driver_testcase {
      * @param bool $wantlatency
      * @param mixed $readonly
      * @param mixed $dbclass
+     * @param float|null $latency Override replica latency seconds.
      * @return read_replica_moodle_database $db
      */
     public function new_db(
@@ -60,16 +61,18 @@ public function new_db(
             ['dbhost' => 'test_ro2', 'dbport' => 2, 'dbuser' => 'test2', 'dbpass' => 'test2'],
             ['dbhost' => 'test_ro3', 'dbport' => 3, 'dbuser' => 'test3', 'dbpass' => 'test3'],
         ],
-        $dbclass = read_replica_moodle_database::class
+        $dbclass = read_replica_moodle_database::class,
+        ?float $latency = null
     ): read_replica_moodle_database {
         $dbhost = 'test_rw';
         $dbname = 'test';
         $dbuser = 'test';
         $dbpass = 'test';
         $prefix = 'test_';
         $dboptions = ['readonly' => ['instance' => $readonly, 'exclude_tables' => ['exclude']]];
-        if ($wantlatency) {
-            $dboptions['readonly']['latency'] = self::$dbreadonlylatency;
+        $effectivelatency = $latency ?? ($wantlatency ? self::$dbreadonlylatency : null);
+        if ($effectivelatency !== null) {
+            $dboptions['readonly']['latency'] = $effectivelatency;
         }
 
         $db = new $dbclass();
@@ -373,6 +376,34 @@ public function test_long_update(): void {
         }
     }
 
+    /**
+     * Test mark_tables_for_primary() routes reads to the writer until latency expires.
+     */
+    public function test_mark_tables_for_primary(): void {
+        $latency = 2;
+        $DB = $this->new_db(latency: $latency);
+
+        // Check reads are going to the reader.
+        $handle = $DB->get_records('table');
+        $this->assert_readonly_handle($handle);
+        $readsreplica = $DB->perf_get_reads_replica();
+        $this->assertGreaterThan(0, $readsreplica);
+
+        $DB->mark_tables_for_primary('table');
+
+        // Verify reads are now routed to the writer.
+        $handle = $DB->get_records('table');
+        $this->assertEquals('test_rw::test:test', $handle);
+        $this->assertEquals($readsreplica, $DB->perf_get_reads_replica());
+
+        sleep($latency + 1);
+
+        // Past latency, reads should be routed back to the reader.
+        $handle = $DB->get_records('table');
+        $this->assert_readonly_handle($handle);
+        $this->assertEquals($readsreplica + 1, $DB->perf_get_reads_replica());
+    }
+
     /**
      * Test readonly handle is not used with events
      * when the latency parameter is applied properly.