Add query EXPLAIN capture to the database adapters

src/Database/Adapter.php

@@ -40,6 +40,22 @@ abstract class Adapter
      */
     protected array $debug = [];
 
+    /**
+     * @var ?array<int, array<string, mixed>>
+     */
+    protected ?array $explainBuffer = null;
+
+    /**
+     * @var array<string, string>
+     */
+    protected const EXPLAIN_COLUMN_RENAMES = [
+        '_uid'         => '$id',
+        '_createdAt'   => '$createdAt',
+        '_updatedAt'   => '$updatedAt',
+        '_permissions' => '$permissions',
+        '_tenant'      => '$tenant',
+    ];
+
     /**
      * @var array<string, array<callable>>
      */
@@ -104,6 +120,171 @@ public function resetDebug(): static
         return $this;
     }
 
+    /**
+     * @throws DatabaseException when called inside an already-active scope —
+     * the buffer is a single shared array, so silently clobbering the outer
+     * scope would lose every previously-captured entry.
+     */
+    public function startExplainCapture(): void
+    {
+        if ($this->explainBuffer !== null) {
+            throw new DatabaseException('withExplain cannot be nested — finish the outer scope first.');
+        }
+        $this->explainBuffer = [];
+    }
+
+    /**
+     * @return array<int, array<string, mixed>>
+     */
+    public function stopExplainCapture(): array
+    {
+        $captured = $this->explainBuffer ?? [];
+        $this->explainBuffer = null;
+        return $captured;
+    }
+
+    public function isExplainCapturing(): bool
+    {
+        return $this->explainBuffer !== null;
+    }
+
+    /**
+     * @param string $sql
+     * @param array<string, mixed> $binds
+     * @param string $purpose
+     * @param array<string, mixed> $context
+     */
+    protected function capturePlan(string $sql, array $binds = [], string $purpose = 'find', array $context = []): void
+    {
+        try {
+            $plan = $this->explainSQL($sql, $binds);
+            $plan = $this->sanitizePlan($plan);
+        } catch (\Throwable $e) {
+            $plan = ['error' => $e->getMessage()];
+        }
+
+        $this->explainBuffer[] = [
+            'purpose' => $purpose,
+            'context' => $context,
+            'plan'    => $plan,
+        ];
+    }
+
+    /**
+     * Attach the REAL execution stats to the most recently captured plan entry.
+     *
+     * The explain endpoint runs the same query listRows runs, so instead of
+     * paying for a second EXPLAIN ANALYZE pass we just measure the read that
+     * already happens: callers time their actual statement and report the
+     * actual rows it produced. No-op when not capturing, so the normal read
+     * path is untouched.
+     *
+     * @param int|null $rowsReturned actual rows the statement returned (null when not meaningful, e.g. an aggregate)
+     * @param float|null $executionTime actual wall time of the statement in milliseconds
+     */
+    protected function recordPlanActuals(?int $rowsReturned, ?float $executionTime): void
+    {
+        if ($this->explainBuffer === null || $this->explainBuffer === []) {
+            return;
+        }
+        $last = \array_key_last($this->explainBuffer);
+        $plan = $this->explainBuffer[$last]['plan'] ?? null;
+        // capturePlan() stores the entry just before the real statement runs;
+        // only fill actuals when the captured plan is a well-formed array. A
+        // failed EXPLAIN is stored as ['error' => ...] — leave it untouched so
+        // an error entry never masquerades as a real plan with stats.
+        if (! \is_array($plan) || isset($plan['error'])) {
+            return;
+        }
+        $this->explainBuffer[$last]['plan']['rowsReturned'] = $rowsReturned;
+        $this->explainBuffer[$last]['plan']['executionTime'] = $executionTime;
+    }
+
+    /**
+     * @param array<int|string, mixed> $plan
+     * @return array<int|string, mixed>
+     */
+    protected function sanitizePlan(array $plan): array
+    {
+        return $this->sanitizePlanNode($plan);
+    }
+
+    private function sanitizePlanNode(mixed $node): mixed
+    {
+        if (\is_array($node)) {
+            $result = [];
+            foreach ($node as $key => $value) {
+                $newKey = \is_string($key) ? $this->renameInternalIdentifier($key) : $key;
+                $result[$newKey] = $this->sanitizePlanNode($value);
+            }
+            return $result;
+        }
+
+        if (\is_string($node)) {
+            return $this->renameInternalIdentifier($node);
+        }
+
+        return $node;
+    }
+
+    private function renameInternalIdentifier(string $name): string
+    {
+        if (\str_ends_with($name, '__metadata')) {
+            return '<metadata>';
+        }
+        if (\str_ends_with($name, '_perms')) {
+            return '<permissionCheck>';
+        }
+        if (isset(self::EXPLAIN_COLUMN_RENAMES[$name])) {
+            return self::EXPLAIN_COLUMN_RENAMES[$name];
+        }
+        // EXPLAIN tree string-values can embed internal identifiers (e.g.
+        // index_condition: "main.`_uid` = '...'"). Substring-rewrite each.
+        // NOTE: this is a best-effort, display-only substring replace — a user
+        // column whose name happens to contain "_uid"/"_tenant"/etc. would be
+        // rewritten too. Acceptable because the output is for human reading of
+        // the plan, not for round-tripping back to a real column name; the raw
+        // `tree` is the same string pre-rename if an exact value is ever needed.
+        if (\str_contains($name, '_')) {
+            foreach (self::EXPLAIN_COLUMN_RENAMES as $internal => $public) {
+                if (\str_contains($name, $internal)) {
+                    $name = \str_replace($internal, $public, $name);
+                }
+            }
+        }
+        return $name;
+    }
+
+    /**
+     * Produce a normalized query plan for a single statement.
+     *
+     * Every adapter returns the same fixed shape so the public DTO can stay
+     * typed regardless of engine:
+     *   engine        precise backend label (mysql|mariadb|postgres|mongo|...)
+     *   rowsScanned   estimated rows the planner expects to examine (null if N/A)
+     *   indexUsed     index the chosen access path uses, user-facing name (null if none)
+     *   estimatedCost planner cost estimate (null if the engine has none)
+     *   rowsReturned  ACTUAL rows produced when the plan was run with ANALYZE (null if not analyzed)
+     *   executionTime ACTUAL wall time in milliseconds under ANALYZE (null if not analyzed)
+     *   tree          raw engine plan for maximum detail
+     *
+     * @param string $sql
+     * @param array<string, mixed> $binds
+     * @return array<string, mixed>
+     */
+    protected function explainSQL(string $sql, array $binds = []): array
+    {
+        return [
+            'engine'        => 'unsupported',
+            'rowsScanned'   => null,
+            'indexUsed'     => null,
+            'estimatedCost' => null,
+            'rowsReturned'  => null,
+            'executionTime' => null,
+            'tree'          => null,
+        ];
+    }
+
     /**
      * Set Namespace.
      *

src/Database/Adapter/MariaDB.php

@@ -1957,6 +1957,24 @@ public function getConnectionId(): string
         return $stmt->fetchColumn();
     }
 
+    /**
+     * @param string $sql
+     * @param array<string, mixed> $binds
+     * @return array<string, mixed>
+     */
+    protected function explainSQL(string $sql, array $binds = []): array
+    {
+        // setTimeout() wraps statements with `SET STATEMENT ... FOR <SQL>`,
+        // which is illegal inside EXPLAIN. Strip the wrapper before delegating.
+        $stripped = \preg_replace('/^\s*SET\s+STATEMENT\s+[^;]*?\s+FOR\s+/is', '', $sql, 1);
+        return parent::explainSQL($stripped ?? $sql, $binds);
+    }
+
+    protected function getExplainEngine(): string
+    {
+        return 'mariadb';
+    }
+
     public function getInternalIndexesKeys(): array
     {
         return ['primary', '_created_at', '_updated_at', '_tenant_id'];