From 4df065499805ffbbc8c3740bb03ddd6eb51aa9cb Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Fri, 5 Jun 2026 15:22:37 -0500
Subject: [PATCH] docs: add how-to for Query Identifier

---
 ...ng-performance-with-pg-stat-statements.rst | 62 +++++++++++++++++++
 docs/references/observability.rst             |  2 +
 2 files changed, 64 insertions(+)
 create mode 100644 docs/how-tos/debugging-performance-with-pg-stat-statements.rst

diff --git a/docs/how-tos/debugging-performance-with-pg-stat-statements.rst b/docs/how-tos/debugging-performance-with-pg-stat-statements.rst
new file mode 100644
index 000000000..5107366aa
--- /dev/null
+++ b/docs/how-tos/debugging-performance-with-pg-stat-statements.rst
@@ -0,0 +1,62 @@
+.. _debugging_performance_pg_stat_statements:
+
+Debugging Performance with pg_stat_statements
+=============================================
+
+This how-to shows how to get a query identifier through PostgREST and then use it to inspect the same query in ``pg_stat_statements``.
+
+.. important::
+
+  - :ref:`db-plan-enabled` must be enabled in PostgREST.
+  - PostgreSQL 14 or newer with ``pg_stat_statements`` available.
+
+Get the Query Identifier from PostgREST
+---------------------------------------
+
+Request the plan in JSON format with the ``verbose`` option:
+
+.. code-block:: bash
+
+   curl "http://localhost:3000/projects?select=id,name&order=id" \
+     -H "Accept: application/vnd.pgrst.plan+json; options=verbose"
+
+The response will contain a top-level ``Query Identifier`` field:
+
+.. code-block:: json
+
+   [
+     {
+       "Plan": {
+         "Node Type": "Aggregate"
+       },
+       "Query Identifier": -432192689578025496
+     }
+   ]
+
+Look up the query in pg_stat_statements
+---------------------------------------
+
+Use that identifier against ``pg_stat_statements``:
+
+.. code-block:: postgres
+
+   select
+     calls,
+     total_exec_time,
+     mean_exec_time,
+     rows,
+     query
+   from pg_stat_statements
+   where queryid = -432192689578025496;
+
+.. csv-table::
+   :header: "calls", "total_exec_time", "mean_exec_time", "rows", "query"
+
+   "13", "0.6355850000000001", "0.04889115384615385", "13", "WITH pgrst_source AS (...)"
+
+This lets you correlate a PostgREST request with PostgreSQL runtime statistics such as:
+
+- how often the query ran
+- total and average execution time
+- how many rows it produced
+- the normalized SQL text recorded by PostgreSQL
diff --git a/docs/references/observability.rst b/docs/references/observability.rst
index 605687aeb..1000ea6e1 100644
--- a/docs/references/observability.rst
+++ b/docs/references/observability.rst
@@ -430,6 +430,8 @@ By default the plan is assumed to generate the JSON representation of a resource
 
 The other available parameters are ``analyze``, ``verbose``, ``settings``, ``buffers`` and ``wal``, which correspond to the `EXPLAIN command options <https://www.postgresql.org/docs/current/sql-explain.html>`_. To use the ``analyze`` and ``wal`` parameters for example, you would add them like ``Accept: application/vnd.pgrst.plan; options=analyze|wal``.
 
+For a workflow that takes the ``Query Identifier`` from a verbose PostgREST plan and uses it to inspect the same query in ``pg_stat_statements``, see :ref:`debugging_performance_pg_stat_statements`.
+
 Note that akin to the EXPLAIN command, the changes will be committed when using the ``analyze`` option. To avoid this, you can use the :ref:`db-tx-end` and the ``Prefer: tx=rollback`` header.
 
 Securing the Execution Plan