From 598fee7badfb2a5d3dae083f511234ca3253c264 Mon Sep 17 00:00:00 2001 From: Laurence Isla Date: Tue, 24 Dec 2024 15:54:43 -0500 Subject: [PATCH] docs: fix broken links for old GUC settings No longer links but embeds the old settings in a details html element. --- docs/api.rst | 30 +++++++++++++++++++++++++++++- docs/configuration.rst | 2 +- docs/postgrest.dict | 1 + docs/releases/v9.0.0.rst | 2 +- 4 files changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index a9483635e7..7a500ab2e2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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 `_. 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 + +

+

+ Old GUCs + +.. 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 + +
+

.. _guc_req_path_method: diff --git a/docs/configuration.rst b/docs/configuration.rst index a2b41a303d..9385d10d93 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -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 `_ (string with dashes, invalid starting from PostgreSQL v14) with text values instead of the :ref:`new names ` (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 ` (string with dashes, invalid starting from PostgreSQL v14) with text values instead of the :ref:`new names ` (string without dashes, valid on all PostgreSQL versions) with json values. On PostgreSQL versions 14 and above, this parameter is ignored. diff --git a/docs/postgrest.dict b/docs/postgrest.dict index 789cdcdf4c..efe34c699f 100644 --- a/docs/postgrest.dict +++ b/docs/postgrest.dict @@ -50,6 +50,7 @@ grantor GraphQL gte GUC +GUCs gucs Gumbs Haskell diff --git a/docs/releases/v9.0.0.rst b/docs/releases/v9.0.0.rst index d451bba7eb..2746d32213 100644 --- a/docs/releases/v9.0.0.rst +++ b/docs/releases/v9.0.0.rst @@ -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 `_ to fail across all requests. Thankfully, `@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 `_. +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 ` to fail across all requests. Thankfully, `@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 `_. 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 `. 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.