feat: add explain transform

Author: steve-chavez

src/lib/PostgrestTransformBuilder.ts

@@ -1,4 +1,4 @@
-import { PostgrestBuilder, PostgrestMaybeSingleResponse, PostgrestSingleResponse } from './types'
+import { PostgrestBuilder, PostgrestMaybeSingleResponse, PostgrestResponse, PostgrestSingleResponse } from './types'
 
 /**
  * Post-filters (transforms)
@@ -128,4 +128,43 @@ export default class PostgrestTransformBuilder<T> extends PostgrestBuilder<T> {
     this.headers['Accept'] = 'application/geo+json'
     return this as PromiseLike<PostgrestSingleResponse<Record<string, unknown>>>
   }
+
+  /**
+   * Obtains the EXPLAIN plan for this request.
+   *
+   * @param analyze  If `true`, the query will be executed and the actual run time will be displayed.
+   * @param verbose  If `true`, the query identifier will be displayed and the result will include the output columns of the query.
+   * @param settings  If `true`, include information on configuration parameters that affect query planning.
+   * @param buffers  If `true`, include information on buffer usage.
+   * @param wal     If `true`, include information on WAL record generation
+   */
+  explain({
+    analyze = false,
+    verbose = false,
+    settings = false,
+    buffers = false,
+    wal = false,
+  }: {
+    analyze?: boolean
+    verbose?: boolean
+    settings?: boolean
+    buffers?: boolean
+    wal?: boolean
+  } = {}): PromiseLike<PostgrestResponse<Record<string, unknown>>> {
+    const options = [
+      analyze ? 'analyze' : null,
+      verbose ? 'verbose' : null,
+      settings ? 'settings' : null,
+      buffers ? 'buffers' : null,
+      wal ? 'wal' : null,
+    ]
+      .filter(Boolean)
+      .join('|')
+    // An Accept header can carry multiple media types but postgrest-js always sends one
+    const forMediatype = this.headers['Accept']
+    this.headers[
+      'Accept'
+    ] = `application/vnd.pgrst.plan+json; for="${forMediatype}"; options=${options};`
+    return this as PromiseLike<PostgrestResponse<Record<string, unknown>>>
+  }
 }

test/db/docker-compose.yml

@@ -10,6 +10,7 @@ services:
       PGRST_DB_URI: postgres://postgres:postgres@db:5432/postgres
       PGRST_DB_SCHEMAS: public,personal
       PGRST_DB_ANON_ROLE: postgres
+      PGRST_DB_PLAN_ENABLED: 1
     depends_on:
       - db
   db:

test/transforms.ts

@@ -130,3 +130,95 @@ test('geojson', async () => {
     }
   `)
 })
+
+test('explain', async () => {
+  const res = await postgrest
+    .from('users')
+    .select()
+    .explain()
+    .then((res) => res.data)
+  expect(res).toMatchInlineSnapshot(`
+    Array [
+      Object {
+        "Plan": Object {
+          "Node Type": "Aggregate",
+          "Parallel Aware": false,
+          "Partial Mode": "Simple",
+          "Plan Rows": 1,
+          "Plan Width": 112,
+          "Plans": Array [
+            Object {
+              "Alias": "users",
+              "Node Type": "Seq Scan",
+              "Parallel Aware": false,
+              "Parent Relationship": "Outer",
+              "Plan Rows": 510,
+              "Plan Width": 132,
+              "Relation Name": "users",
+              "Startup Cost": 0,
+              "Total Cost": 15.1,
+            },
+          ],
+          "Startup Cost": 17.65,
+          "Strategy": "Plain",
+          "Total Cost": 17.68,
+        },
+      },
+    ]
+  `)
+})
+
+test('explain with options', async () => {
+  const res = await postgrest
+    .from('users')
+    .select()
+    .explain({ verbose: true, settings: true })
+    .then((res) => res.data)
+  expect(res).toMatchInlineSnapshot(`
+    Array [
+      Object {
+        "Plan": Object {
+          "Node Type": "Aggregate",
+          "Output": Array [
+            "NULL::bigint",
+            "count(ROW(users.username, users.data, users.age_range, users.status, users.catchphrase))",
+            "(COALESCE(json_agg(ROW(users.username, users.data, users.age_range, users.status, users.catchphrase)), '[]'::json))::character varying",
+            "NULLIF(current_setting('response.headers'::text, true), ''::text)",
+            "NULLIF(current_setting('response.status'::text, true), ''::text)",
+          ],
+          "Parallel Aware": false,
+          "Partial Mode": "Simple",
+          "Plan Rows": 1,
+          "Plan Width": 112,
+          "Plans": Array [
+            Object {
+              "Alias": "users",
+              "Node Type": "Seq Scan",
+              "Output": Array [
+                "users.username",
+                "users.data",
+                "users.age_range",
+                "users.status",
+                "users.catchphrase",
+              ],
+              "Parallel Aware": false,
+              "Parent Relationship": "Outer",
+              "Plan Rows": 510,
+              "Plan Width": 132,
+              "Relation Name": "users",
+              "Schema": "public",
+              "Startup Cost": 0,
+              "Total Cost": 15.1,
+            },
+          ],
+          "Startup Cost": 17.65,
+          "Strategy": "Plain",
+          "Total Cost": 17.68,
+        },
+        "Settings": Object {
+          "search_path": "\\\"public\\\", \\\"public\\\"",
+        },
+      },
+    ]
+  `)
+})