Add compatibility with PostgreSQL v14

api.rst

@@ -1584,20 +1584,32 @@ HTTP Logic
 Accessing Request Headers, Cookies and JWT claims
 -------------------------------------------------
 
-You can access request headers, cookies and JWT claims by reading GUC variables set by PostgREST per request. They are named :code:`request.header.XYZ`, :code:`request.cookie.XYZ` and :code:`request.jwt.claim.XYZ`.
+You can access request headers, cookies and JWT claims by reading GUC variables set by PostgREST per request. They are named :code:`request.headers`, :code:`request.cookies` and :code:`request.jwt.claims`.
 
 .. code-block:: postgresql
 
-  -- To read the value of the Origin request header:
+  -- To read the value of the User-Agent request header:
-  SELECT current_setting('request.header.origin', true);
+  SELECT current_setting('request.headers', true)::json->>'user-agent';
+
   -- To read the value of sessionId in a cookie:
-  SELECT current_setting('request.cookie.sessionId', true);
+  SELECT current_setting('request.cookies', true)::json->>'sessionId';
+
   -- To read the value of the email claim in a jwt:
-  SELECT current_setting('request.jwt.claim.email', true);
+  SELECT current_setting('request.jwt.claims', true)::json->>'email';
+
+  -- To get all the headers sent in the request
+  SELECT current_setting('request.headers', true)::json;
 
 .. note::
 
-  ``request.jwt.claim.role`` defaults to the value of :ref:`db-anon-role`.
+  The ``role`` in ``request.jwt.claims`` defaults to the value of :ref:`db-anon-role`.
+
+.. _guc_legacy_names:
+
+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.
 
 .. _guc_req_path_method:
 

auth.rst

@@ -165,7 +165,7 @@ You can create a valid JWT either from inside your database or via an external s
 JWT from SQL
 ~~~~~~~~~~~~
 
-You can create JWT tokens in SQL using the `pgjwt extension <https://github.com/michelp/pgjwt>`_. It's simple and requires only pgcrypto. If you're on an environment like Amazon RDS which doesn't support installing new extensions, you can still manually run the `SQL inside pgjwt <https://github.com/michelp/pgjwt/blob/master/pgjwt--0.1.0.sql>`_ (you'll need to replace ``@extschema@`` with another schema or just delete it) which creates the functions you will need.
+You can create JWT tokens in SQL using the `pgjwt extension <https://github.com/michelp/pgjwt>`_. It's simple and requires only pgcrypto. If you're on an environment like Amazon RDS which doesn't support installing new extensions, you can still manually run the `SQL inside pgjwt <https://github.com/michelp/pgjwt/blob/master/pgjwt--0.1.1.sql>`_ (you'll need to replace ``@extschema@`` with another schema or just delete it) which creates the functions you will need.
 
 Next write a stored procedure that returns the token. The one below returns a token with a hard-coded role, which expires five minutes after it was issued. Note this function has a hard-coded secret as well.
 

configuration.rst

@@ -50,6 +50,7 @@ db-channel-enabled       Boolean True
 db-prepared-statements   Boolean True
 db-tx-end                String  commit
 db-config                Boolean True
+db-use-legacy-gucs       Boolean True
 server-host              String  !4
 server-port              Int     3000
 server-unix-socket       String
@@ -199,6 +200,15 @@ db-config
 
    Enables the in-database configuration.
 
+.. _db-use-legacy-gucs:
+
+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.
+
+  On PostgreSQL versions 14 and above, this parameter is ignored.
+
 .. _server-host:
 
 server-host

postgrest.dict

@@ -45,6 +45,7 @@ grantor
 GraphQL
 gte
 GUC
+gucs
 Gumbs
 Haskell
 Heroku

releases/upcoming.rst

@@ -13,3 +13,11 @@ Added
 
 * Allow :ref:`embedding <embedding_partitioned_tables>`, UPSERT, INSERT with Location response, OPTIONS request and OpenAPI support for partitioned tables.
   |br| -- `@laurenceisla <https://github.com/laurenceisla>`_
+
+* Make GUC names for headers, cookies and jwt claims compatible with PostgreSQL v14.
+
+  + The GUC names on PostgreSQL 14 are changed to the ones :ref:`mentioned in this section <guc_req_headers_cookies_claims>`, while older versions still use the :ref:`guc_legacy_names`.
+  + PostgreSQL versions below 14 can opt in to the new JSON GUCs by setting the :ref:`db-use-legacy-gucs` config option to false (true by default).
+  + Managed to avoid a breaking change thanks to `@robertsosinski <https://github.com/robertsosinski>`_ who reported the bug that only one ``.`` character was allowed in GUC keys to the PostgreSQL team. See the `full discussion <https://www.postgresql.org/message-id/17045-6a4a9f0d1513f72b%40postgresql.org>`_.
+
+  -- `@laurenceisla <https://github.com/laurenceisla>`_