diff --git a/api.rst b/api.rst index 6ac6001ed..2a56d9aad 100644 --- a/api.rst +++ b/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: - SELECT current_setting('request.header.origin', true); + -- To read the value of the User-Agent request header: + 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 `_. You can opt in to use the JSON GUCs mentioned above by setting the ``db-use-legacy-gucs`` to false. .. _guc_req_path_method: diff --git a/auth.rst b/auth.rst index d00f67368..748a9fe29 100644 --- a/auth.rst +++ b/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 `_. 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 `_ (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 `_. 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 `_ (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. diff --git a/configuration.rst b/configuration.rst index 2da88d208..2826e2d5d 100644 --- a/configuration.rst +++ b/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 `_ (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. + .. _server-host: server-host diff --git a/postgrest.dict b/postgrest.dict index cfe0e3bea..396e67b5e 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -45,6 +45,7 @@ grantor GraphQL gte GUC +gucs Gumbs Haskell Heroku diff --git a/releases/upcoming.rst b/releases/upcoming.rst index 120b69eaa..060d528b0 100644 --- a/releases/upcoming.rst +++ b/releases/upcoming.rst @@ -13,3 +13,11 @@ Added * Allow :ref:`embedding `, UPSERT, INSERT with Location response, OPTIONS request and OpenAPI support for partitioned tables. |br| -- `@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 `, 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 `_ who reported the bug that only one ``.`` character was allowed in GUC keys to the PostgreSQL team. See the `full discussion `_. + + -- `@laurenceisla `_