diff --git a/docs/postgrest.dict b/docs/postgrest.dict index f4aa4dd428..d4bafe7166 100644 --- a/docs/postgrest.dict +++ b/docs/postgrest.dict @@ -48,6 +48,7 @@ GraphQL Greenplum gte GUC +GUCs gucs Haskell Heroku diff --git a/docs/references/configuration.rst b/docs/references/configuration.rst index 5da6db953a..43214b158a 100644 --- a/docs/references/configuration.rst +++ b/docs/references/configuration.rst @@ -529,7 +529,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/references/transactions.rst b/docs/references/transactions.rst index 1e732cd7ad..bd7eb09c88 100644 --- a/docs/references/transactions.rst +++ b/docs/references/transactions.rst @@ -140,7 +140,36 @@ PostgREST stores the headers, cookies and headers as JSON. To get them: Legacy settings ^^^^^^^^^^^^^^^ -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/releases/v09.0.0.rst b/docs/releases/v09.0.0.rst index 5827f542a4..1dde06cfaa 100644 --- a/docs/releases/v09.0.0.rst +++ b/docs/releases/v09.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 settings 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.