docs: fix broken links for old GUC settings

No longer links but embeds the old settings in a details html element.
2024-12-25 11:43:19 +01:00
parent 5a8f8c1d9c
commit bc594f4fbd
4 changed files with 32 additions and 3 deletions
@@ -2829,7 +2829,35 @@ You can access request headers, cookies and JWT claims by reading GUC variables
 Legacy GUC variable names
 ~~~~~~~~~~~~~~~~~~~~~~~~~

-For PostgreSQL versions below 14, PostgREST will take into consideration the :ref:`db-use-legacy-gucs` config, which is set to true by default. This means that the interface for accessing these GUCs is `the same as in older versions <https://postgrest.org/en/v8.0/api.html#accessing-request-headers-cookies-and-jwt-claims>`_. You can opt in to use the JSON GUCs mentioned above by setting the ``db-use-legacy-gucs`` to false.
+For PostgreSQL versions below 14, PostgREST will take into consideration the :ref:`db-use-legacy-gucs` config, which is set to true by default.
+This means that the interface for accessing these GUCs is the same as in older versions (see below).
+You can opt in to use the JSON GUCs mentioned above by setting the ``db-use-legacy-gucs`` to false.
+
+.. raw:: html
+
+  <p>
+    <details>
+      <summary>Old GUCs</summary>
+
+.. code-block:: postgresql
+
+  -- To read the value of the User-Agent request header:
+  SELECT current_setting('request.header.user-agent', true);
+
+  -- To read the value of sessionId in a cookie:
+  SELECT current_setting('request.cookie.sessionId', true);
+
+  -- To read the value of the email claim in a jwt:
+  SELECT current_setting('request.jwt.claim.email', true);
+
+.. note::
+
+  ``request.jwt.claim.role`` defaults to the value of :ref:`db-anon-role`.
+
+.. raw:: html
+
+    </details>
+  </p>

 .. _guc_req_path_method:

@@ -477,7 +477,7 @@ db-use-legacy-gucs
  **In-Database** pgrst.db_use_legacy_gucs
  =============== =================

-  Determine if GUC request settings for headers, cookies and jwt claims use the `legacy names <https://postgrest.org/en/v8.0/api.html#accessing-request-headers-cookies-and-jwt-claims>`_ (string with dashes, invalid starting from PostgreSQL v14) with text values instead of the :ref:`new names <guc_req_headers_cookies_claims>` (string without dashes, valid on all PostgreSQL versions) with json values.
+  Determine if GUC request settings for headers, cookies and jwt claims use the :ref:`legacy names <guc_legacy_names>` (string with dashes, invalid starting from PostgreSQL v14) with text values instead of the :ref:`new names <guc_req_headers_cookies_claims>` (string without dashes, valid on all PostgreSQL versions) with json values.

  On PostgreSQL versions 14 and above, this parameter is ignored.

@@ -50,6 +50,7 @@ grantor
 GraphQL
 gte
 GUC
+GUCs
 gucs
 Gumbs
 Haskell
@@ -10,7 +10,7 @@ Features
 PostgreSQL 14 compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

-PostgreSQL 14 Beta 1 tightened its GUC naming scheme making it impossible to use multiple dots (``.``) and dashes (``-``) on custom GUC parameters, this caused our `old HTTP Context <https://postgrest.org/en/v8.0/api.html#accessing-request-headers-cookies-and-jwt-claims>`_ to fail across all requests. Thankfully, `@robertsosinski <https://github.com/robertsosinski>`_ got the PostgreSQL team to reconsider allowing multiple dots in the GUC name, allowing us to avoid a major breaking change. You can see the full discussion `here <https://www.postgresql.org/message-id/17045-6a4a9f0d1513f72b%40postgresql.org>`_.
+PostgreSQL 14 Beta 1 tightened its GUC naming scheme making it impossible to use multiple dots (``.``) and dashes (``-``) on custom GUC parameters, this caused our :ref:`old HTTP Context <guc_legacy_names>` to fail across all requests. Thankfully, `@robertsosinski <https://github.com/robertsosinski>`_ got the PostgreSQL team to reconsider allowing multiple dots in the GUC name, allowing us to avoid a major breaking change. You can see the full discussion `here <https://www.postgresql.org/message-id/17045-6a4a9f0d1513f72b%40postgresql.org>`_.

 Still, dashes cannot be used on PostgreSQL 14 custom GUC parameters, so we changed our HTTP Context :ref:`to namespace using a mix of dots and JSON <guc_req_headers_cookies_claims>`. On older PostgreSQL versions we still use the :ref:`guc_legacy_names`. If you wish to use the new JSON GUCs on these versions, set the :ref:`db-use-legacy-gucs` config option to false.