bump version to 13.0.2

The repository has been moved from a dedicated organisation to my personal profile, so this old link will no longer work after 90 days.

CHANGELOG.md

@@ -5,6 +5,21 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+## [13.0.2] - 2025-06-02
+
+### Fixed
+
+- Fix regression that makes `ORDER BY` with nulls-order not work alongside limits by @laurenceisla in #4109
+
+## [13.0.1] - 2025-06-01
+
+### Fixed
+
+- Fix jwt error returning HTTP status `400` for invalid role by @taimoorzaeem in #3601
+- Fix `db-extra-search-path` cannot be set to nothing by @taimoorzaeem in #4074
+  + It can now be disabled by setting it to empty string.
+  + Schema Cache load error is now logged including `db-schemas` and `db-extra-search-path` config values.
+
 ## [13.0.0] - 2025-05-08
 
 ### Added
@@ -47,8 +62,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
  - #2052, Dropped support for PostgreSQL 11 - @wolfgangwalther
  - #3508, PostgREST now fails to start when `server-port` and `admin-server-port` config options are the same - @develop7
  - #3607, PostgREST now fails to start when the JWT secret is less than 32 characters long - @laurenceisla
- - #3644, Fail schema cache lookup with invalid db-schemas config - @wolfgangwalther
+ - #3644, Fail schema cache lookup with invalid `db-schemas` or `db-extra-search-path` config - @wolfgangwalther
    - Previously, this would silently return 200 - OK on the root endpoint, but don't provide any usable endpoints.
+   - Note: This also applies when deleting the `public` schema - both config options default to that.
  - #3757, Remove support for `Prefer: params=single-object` - @joelonsql
    + This preference was deprecated in favor of Functions with an array of JSON objects
  - #3013, Drop support for Limited updates/deletes

docs/_diagrams/uml/arch.uml

@@ -82,8 +82,8 @@ url of Authorization is [[../explanations/db_authz.html]]
 url of CLI is [[../references/cli.html#cli]]
 url of "Connection Pool" is [[../references/connection_pool.html]]
 url of Config is [[../references/configuration.html#configuration]]
-url of HTTPADMIN is [[https://aosabook.org/en/posa/warp.html]]
-url of HTTPAPI is [[https://aosabook.org/en/posa/warp.html]]
+url of HTTPADMIN is [[../explanations/architecture.html#http]]
+url of HTTPAPI is [[../explanations/architecture.html#http]]
 url of Listener is [[../references/listener.html#listener]]
 url of Proxy is [[../explanations/nginx.html]]
 url of "Schema Cache" is [[../references/schema_cache.html#schema-cache]]

docs/conf.py

@@ -114,7 +114,7 @@ html_theme = "sphinx_rtd_theme"
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"display_version": False}
+html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/ecosystem.rst

@@ -34,7 +34,7 @@ Templates
 Example Apps
 ------------
 
-* `archtika <https://github.com/archtika/archtika>`_ - self‑hosted CMS
+* `archtika <https://github.com/thiloho/archtika>`_ - self‑hosted CMS
 * `delibrium-postgrest <https://gitlab.com/delibrium/delibrium-postgrest/>`_ - example school API and front-end in Vue.js
 * `ETH-transactions-storage <https://github.com/Adamant-im/ETH-transactions-storage>`_ - indexer for Ethereum to get transaction list by ETH address
 * `general <https://github.com/PierreRochard/general>`_ - example auth back-end

docs/explanations/external_auth.rst

@@ -1,6 +1,6 @@
-.. _external_jwt:
+.. _external_auth:
 
-External JWT Generation
+External Authentication
 -----------------------
 
 JWT from Auth0
@@ -9,21 +9,3 @@ JWT from Auth0
 An external service like `Auth0 <https://auth0.com/>`_ can do the hard work transforming OAuth from Github, Twitter, Google etc into a JWT suitable for PostgREST. Auth0 can also handle email signup and password reset flows.
 
 To use Auth0, create `an application <https://auth0.com/docs/get-started/applications>`_ for your app and `an API <https://auth0.com/docs/get-started/apis>`_ for your PostgREST server. Auth0 supports both HS256 and RS256 scheme for the issued tokens for APIs. For simplicity, you may first try HS256 scheme while creating your API on Auth0. Your application should use your PostgREST API's `API identifier <https://auth0.com/docs/get-started/apis/api-settings>`_ by setting it with the `audience parameter <https://auth0.com/docs/secure/tokens/access-tokens/get-access-tokens#control-access-token-audience>`_  during the authorization request. This will ensure that Auth0 will issue an access token for your PostgREST API. For PostgREST to verify the access token, you will need to set ``jwt-secret`` on PostgREST config file with your API's signing secret.
-
-JWT using OpenSSL
-~~~~~~~~~~~~~~~~~
-
-To manually generate a JWT using ``openssl`` commands, you can use the following script. This may be useful for testing JWT related features of PostgREST.
-
-.. code:: bash
-
-  #!/bin/bash
-  set -e
-
-  TEST_JWT_SECRET='test_secret_that_is_at_least_32_characters_long'
-  _base64 () { openssl base64 -e -A | tr '+/' '-_' | tr -d '='; }
-  header=$(echo -n '{"alg":"HS256","typ":"JWT"}' | _base64)
-  exp=$(( EPOCHSECONDS + 60*60 ))  # 1 hour
-  payload=$(echo -n "{\"role\":\"test_role\",\"exp\":$exp}" | _base64)
-  signature=$(echo -n "$header.$payload" | openssl dgst -sha256 -hmac "$TEST_JWT_SECRET" -binary | _base64)
-  echo -n "$header.$payload.$signature"

docs/index.rst

@@ -61,7 +61,7 @@ Sponsors
   |
 
   .. image:: ../static/tembo.png
-    :target: https://tembo.io/?utm_source=sponsor&utm_campaign=postgrest
+    :target: https://www.tembo.io/?utm_source=sponsor&utm_campaign=postgrest
 
   .. container:: img-dark
 
@@ -212,17 +212,12 @@ Here are some companies that use PostgREST in production.
 * `Datrium <https://www.datrium.com>`_
 * `Drip Depot <https://www.dripdepot.com>`_
 * `Image-charts <https://www.image-charts.com>`_
-* `Moat <https://www.oracle.com/advertising/>`_
 * `Netwo <https://www.netwo.io>`_
 * `Nimbus <https://www.nimbusfacility.com/sg/home>`_
   - See how Nimbus uses PostgREST in `Paul Copplestone's blog post <https://paul.copplest.one/blog/nimbus-tech-2019-04.html>`_.
 * `OpenBooking <https://openbooking.ch>`_
 * `Supabase <https://supabase.com>`_
 
-.. Failing links
-  * `eGull <http://www.egull.co>`_
-  * `MotionDynamic - Fast highly dynamic video generation at scale <https://motiondynamic.tech>`_
-
 Testimonials
 ------------
 

docs/integrations/greenplum.rst

@@ -1,6 +0,0 @@
-Greenplum
-#########
-
-`Greenplum <https://blogs.vmware.com/tanzu/tanzu-greenplum/>`_ has been reported to work by adding ``LOGIN`` to the :ref:`anonymous and user roles <roles>`.
-
-For more details, see https://github.com/PostgREST/postgrest/issues/2021.

docs/postgrest.dict

@@ -46,7 +46,6 @@ Github
 Google
 grantor
 GraphQL
-Greenplum
 gte
 GUC
 Haskell
@@ -104,7 +103,6 @@ Observability
 Okta
 OpenAPI
 openapi
-OpenSSL
 ov
 parametrized
 passphrase

docs/references/api/preferences.rst

@@ -242,7 +242,7 @@ Will result in:
 Max Affected
 ============
 
-You can set a limit to the amount of resources affected in a request by sending ``max-affected`` preference. This feature works in combination with ``handling=strict`` preference. ``max-affected`` would be ignored with lenient handling. The "affected resources" are the number of rows returned by ``DELETE`` and ``PATCH`` requests. This is also supported through ``RPC`` calls.
+You can set a limit to the amount of resources affected in a request by sending ``max-affected`` preference. This feature works in combination with ``handling=strict`` preference. ``max-affected`` would be ignored with lenient handling. The "affected resources" are the number of rows returned by ``DELETE`` and ``PATCH`` requests.
 
 To illustrate the use of this preference, consider the following scenario where the ``items`` table contains 14 rows.
 
@@ -264,3 +264,31 @@ To illustrate the use of this preference, consider the following scenario where
       "details": "The query affects 14 rows",
       "hint": null
   }
+
+With :ref:`RPC <functions>`, the preference is honored completely on the basis of the number of rows returned in the result set of the function. This can be useful for complex mutation queries using `data-modifying statements <https://www.postgresql.org/docs/current/queries-with.html#QUERIES-WITH-MODIFYING>`_. A simple example:
+
+.. code-block:: postgres
+
+  CREATE FUNCTION test.delete_items()
+  RETURNS SETOF items AS $$
+    DELETE FROM items WHERE id < 15 RETURNING *;
+  $$ LANGUAGE SQL;
+
+.. code-block:: bash
+
+  curl -i "http://localhost:3000/rpc/delete_items" \
+    -H "Content-Type: application/json" \
+    -H "Prefer: handling=strict, max-affected=10"
+
+.. code-block:: http
+
+  HTTP/1.1 400 Bad Request
+
+.. code-block:: json
+
+  {
+      "code": "PGRST124",
+      "message": "Query result exceeds max-affected preference constraint",
+      "details": "The query affects 14 rows",
+      "hint": null
+  }

docs/references/api/resource_embedding.rst

@@ -1150,27 +1150,19 @@ For example, to arrange the films in descending order using the director's last
 Spread embedded resource
 ========================
 
-The ``...`` operator lets you "spread" an embedded resource.
-That is, it removes the surrounding JSON object for the embedded resource columns.
-
-.. note::
-
-  The spread operator ``...`` is borrowed from the Javascript `spread syntax <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax>`_.
+You can modify the shape of the embedded resources by using the spread syntax (``...``).
 
 .. _spread_to_one_embed:
 
 Spread To-One relationships
 ---------------------------
 
-This applies to :ref:`one-to-one <one-to-one>` and :ref:`many-to-one <many-to-one>` relationships.
-Take the following example:
+Spread on resources forming :ref:`one-to-one <one-to-one>` and :ref:`many-to-one <many-to-one>` relationships, will lift the embedded columns to the top object.
 
 .. code-block:: bash
 
-   # curl "http://localhost:3000/films?select=title,...directors(director_last_name:last_name)&title=like.*Workers*"
-
   curl --get "http://localhost:3000/films" \
-    -d "select=title,...directors(director_last_name:last_name)" \
+    -d "select=title,...directors(director_first_name:first_name, director_last_name:last_name)" \
     -d "title=like.*Workers*"
 
 .. code-block:: json
@@ -1178,48 +1170,22 @@ Take the following example:
    [
      {
        "title": "Workers Leaving The Lumière Factory In Lyon",
+       "director_first_name": "Louis",
        "director_last_name": "Lumière"
      }
    ]
 
-Note that there is no ``"directors"`` object. Also the embed columns can be aliased normally.
-
-You can use this to get the columns of a join table in a many-to-many relationship. For instance, to get films and its actors, but including the ``character`` column from the roles table:
-
-.. code-block:: bash
-
-   # curl "http://localhost:3000/films?select=title,actors:roles(character,...actors(first_name,last_name))&title=like.*Lighthouse*"
-
-  curl --get "http://localhost:3000/films" \
-    -d "select=title,actors:roles(character,...actors(first_name,last_name))" \
-    -d "title=like.*Lighthouse*"
-
-.. code-block:: json
-
-   [
-     {
-       "title": "The Lighthouse",
-       "actors": [
-          {
-            "character": "Thomas Wake",
-            "first_name": "Willem",
-            "last_name": "Dafoe"
-          }
-       ]
-     }
-   ]
+Note that there is no wrapping ``"directors"`` object, unlike regularly embedding :ref:`many-to-one <many-to-one>` relationships. Also note that embedded columns can be aliased normally.
 
 .. _spread_to_many_embed:
 
 Spread To-Many relationships
 ----------------------------
 
-The spread columns in :ref:`one-to-many <one-to-many>` or :ref:`many-to-many <many-to-many>` relationships will show the data in arrays.
+Spread on resources forming :ref:`one-to-many <one-to-many>` and :ref:`many-to-many <many-to-many>` relationships, will convert the embedded columns into correlated arrays.
 
 .. code-block:: bash
 
-   # curl -g "http://localhost:3000/directors?select=first_name,...films(film_titles:title,film_years:year)&first_name=like.Quentin*"
-
   curl --get "http://localhost:3000/directors" \
     -d "select=first_name,...films(film_titles:title,film_years:year)" \
     -d "first_name=like.Quentin*"
@@ -1240,16 +1206,17 @@ The spread columns in :ref:`one-to-many <one-to-many>` or :ref:`many-to-many <ma
      }
    ]
 
-Note that there is no ``films`` array of objects.
+Note that ``films`` is no longer an array of objects, unlike regularly embedding :ref:`one-to-many`. The embedded columns become arrays and they're correlated—in the above result, we can say that "Pulp Fiction" premiered in 1994 and "Reservoir Dogs" in 1992.
 
-By default, the order of the values inside the resulting array is unspecified but `it is safe to assume <https://www.postgresql.org/message-id/15950.1491843689%40sss.pgh.pa.us>`_ that all the columns return the values in the same unspecified order.
-From the previous result, we can say that "Pulp Fiction" premiered in 1994 and "Reservoir Dogs" in 1992.
-You can still order all the resulting arrays explicitly. For example, to order by the release year:
+Order in spread to-many
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In the above example, the order of the values inside the correlated arrays is unspecified, but all the values are guaranteed to be in the same unspecified order.
+
+You can order the correlated arrays explicitly. For example, to order by the film year:
 
 .. code-block:: bash
 
-  # curl -g "http://localhost:3000/directors?select=first_name,...films(film_titles:title,film_years:year)&first_name=like.Quentin*&films.order=year"
-
   curl --get "http://localhost:3000/directors" \
     -d "select=first_name,...films(film_titles:title,film_years:year)" \
     -d "first_name=like.Quentin*" \
@@ -1271,14 +1238,37 @@ You can still order all the resulting arrays explicitly. For example, to order b
      }
    ]
 
-Nesting Spreads
-~~~~~~~~~~~~~~~
+.. warning::
 
-For example, let's nest ``...technical_specs`` (one-to-one) and ``...roles`` (one-to-many) inside ``...films``:
+   Aliasing spreaded columns is recommended since JSON allows duplicate keys. Example:
 
    .. code-block:: bash
 
-  # curl -g "http://localhost:3000/directors?select=first_name,...films(film_titles:title,film_years:year,...technical_specs(film_runtimes:runtime),...roles(film_characters:character))&first_name=like.Quentin*&films.order=year&films.roles.order=character"
+     curl --get "localhost:3000/projects" \
+       -d "select=id,name,...clients(id,name)"
+
+   .. code-block:: json
+
+     [{"id":1,"name":"Windows 7","id":1,"name":"Microsoft"},
+      {"id":2,"name":"Windows 10","id":1,"name":"Microsoft"},
+      {"id":3,"name":"IOS","id":2,"name":"Apple"},
+      {"id":4,"name":"OSX","id":2,"name":"Apple"},
+      {"id":5,"name":"Orphan","id":null,"name":null}]
+
+   This can be a problem in Javascript objects, since only the last duplicated key will be considered. To solve it do:
+
+   .. code-block:: bash
+
+     curl --get "localhost:3000/projects" \
+       -d "select=id,name,...clients(client_id:id,client_name:name)"
+
+
+Multiple Spreads
+----------------
+
+You can use multiple spreads at any level. For example, let's spread ``technical_specs`` and ``roles`` into ``films`` and then spread ``films`` into ``directors``:
+
+.. code-block:: bash
 
   curl --get "http://localhost:3000/directors" \
     -d "select=first_name,...films(film_titles:title,film_years:year,...technical_specs(film_runtimes:runtime),...roles(film_characters:character))" \
@@ -1310,6 +1300,36 @@ For example, let's nest ``...technical_specs`` (one-to-one) and ``...roles`` (on
      }
    ]
 
-All the elements inside ``films`` are selected in the same order, including both nested resources.
-For example, we can say that "Reservoir Dogs" premiered in 1992, its runtime is 1:39:00 and it has the following characters: ``[ "Mr. Pink", "Mr. White" ]``.
-Note that the data inside to-many nested resources can also be ordered (``roles`` by the ``character`` name in our example).
+Note that:
+
+- All the ``film_*`` arrays are correlated—"Reservoir Dogs" premiered in 1992, its runtime is 1:39:00 and it has the following characters: ``[ "Mr. Pink", "Mr. White" ]``.
+- The ``film_*`` arrays are ordered by ``year`` (due to ``films.order=year``).
+- The bottom level array ``film_characters`` is ordered (due to ``films.roles.order=character``).
+
+Spread a join table
+-------------------
+
+Spread can be used to move the columns of a join table in a :ref:`many-to-many <many-to-many>` to the top object. For instance, to get the ``character`` column of the ``roles`` join table into ``actors``:
+
+.. code-block:: bash
+
+  curl --get "http://localhost:3000/films" \
+    -d "select=title,actors:roles(character,...actors(first_name,last_name))" \
+    -d "title=like.*Lighthouse*"
+
+.. code-block:: json
+
+   [
+     {
+       "title": "The Lighthouse",
+       "actors": [
+          {
+            "character": "Thomas Wake",
+            "first_name": "Willem",
+            "last_name": "Dafoe"
+          }
+       ]
+     }
+   ]
+
+

docs/references/api/tables_views.rst

@@ -175,23 +175,29 @@ To ensure best performance on larger data sets, an `appropriate index <https://w
 Full-Text Search
 ~~~~~~~~~~~~~~~~
 
-The :code:`fts` filter mentioned above has a number of options to support flexible textual queries, namely the choice of plain vs phrase search and the language used for stemming. Suppose that :code:`tsearch` is a table with column :code:`my_tsv`, of type `tsvector <https://www.postgresql.org/docs/current/datatype-textsearch.html>`_. The following examples illustrate the possibilities.
+The :code:`fts` operator has a number of options to support flexible textual queries, namely the choice of plain vs phrase search and the language used for stemming.
+
+The following examples illustrate the possibilities, assuming column :code:`my_tsv` is of type `tsvector <https://www.postgresql.org/docs/current/datatype-textsearch.html>`_.
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/tsearch?my_tsv=fts(french).amusant"
+  curl --get "http://localhost:3000/people" \
+    -d "my_tsv=fts(french).amusant"
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/tsearch?my_tsv=plfts.The%20Fat%20Cats"
+  curl --get "http://localhost:3000/people" \
+    -d "my_tsv=plfts.The%20Fat%20Cats"
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/tsearch?my_tsv=not.phfts(english).The%20Fat%20Cats"
+  curl --get "http://localhost:3000/people" \
+    -d "my_tsv=not.phfts(english).The%20Fat%20Cats"
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/tsearch?my_tsv=not.wfts(french).amusant"
+  curl --get "http://localhost:3000/people" \
+    -d "my_tsv=not.wfts(french).amusant"
 
 .. _fts_to_tsvector:
 
@@ -199,15 +205,17 @@ Automatic ``tsvector`` conversion
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If the filtered column is not of type ``tsvector``, then it will be automatically converted using `to_tsvector() <https://www.postgresql.org/docs/current/functions-textsearch.html#TEXTSEARCH-FUNCTIONS-TABLE>`_.
-This allows using ``fts`` on ``text`` and ``json`` types out of the box, for example.
+This allows using the ``fts`` operator on ``text`` and ``json`` types out of the box.
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/tsearch?my_text_column=fts(french).amusant"
+  curl --get "http://localhost:3000/people" \
+    -d "my_text_column=fts(french).amusant"
 
 .. code-block:: bash
 
-  curl "http://localhost:3000/tsearch?my_json_column=not.phfts(english).The%20Fat%20Cats"
+  curl --get "http://localhost:3000/people" \
+    -d "my_json_column=not.phfts(english).The%20Fat%20Cats"
 
 .. _v_filter:
 

docs/references/auth.rst

@@ -77,7 +77,7 @@ If the client included no JWT (or one without a role claim) then PostgREST switc
 JWT Generation
 ~~~~~~~~~~~~~~
 
-You can create a valid JWT either from inside your database (see :ref:`sql_user_management`) or via an external service (see :ref:`external_jwt`).
+You can create a valid JWT either from inside your database (see :ref:`sql_user_management`) or via an external service (see :ref:`external_auth`).
 
 .. _client_auth:
 
@@ -156,6 +156,19 @@ You can specify the literal value as we saw earlier, or reference a filename to
 
   jwt-secret = "@rsa.jwk.pub"
 
+JWK ``kid`` validation
+^^^^^^^^^^^^^^^^^^^^^^
+
+PostgREST has built-in validation of the `key ID parameter <https://www.rfc-editor.org/rfc/rfc7517#section-4.5>`_, useful when working with a JWK Set.
+It goes as follows:
+
+- If the JWT contains a ``kid`` parameter, then PostgREST will look for the JWK in the :ref:`jwt-secret`.
+
+  + If no JWK matches the same ``kid`` value (or if they do not have a ``kid``), then the token will be rejected with a :ref:`401 Unauthorized <pgrst301>` error.
+  + If a JWK matches the ``kid`` value then it will validate the token against that JWK accordingly.
+
+- If the JWT does not have a ``kid`` parameter, then PostgREST will validate the token against each JWK in the :ref:`jwt-secret`.
+
 .. _jwt_claims_validation:
 
 JWT Claims Validation
@@ -188,12 +201,12 @@ It works this way:
   + If the match fails or if the ``aud`` value is not a string or array of strings, then the token will be rejected with a :ref:`401 Unauthorized <pgrst303>` error.
   + If the ``aud`` key **is not present** or if its value is ``null`` or ``[]``, PostgREST will interpret this token as allowed for all audiences and will complete the request.
 
-.. _jwt_role_claim_key_extract:
+.. _jwt_role_extract:
 
-JWT Role Claim Key Extraction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+JWT Role Extraction
+~~~~~~~~~~~~~~~~~~~
 
-A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. This can be used to consume a JWT provided by a third party service like Auth0, Okta, Microsoft Entra or Keycloak.
+A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. It's configured by :ref:`jwt-role-claim-key`. This can be used to consume a JWT provided by a third party service like Auth0, Okta, Microsoft Entra or Keycloak.
 
 The DSL follows the `JSONPath <https://goessner.net/articles/JsonPath/>`_ expression grammar with extended string comparison operators. Supported operators are:
 
@@ -224,6 +237,9 @@ Usage examples:
     jwt-role-claim-key = ".postgrest.roles[?(@ ==^ \"hor\")]"
     jwt-role-claim-key = ".postgrest.roles[?(@ *== \"utho\")]"
 
+.. note::
+
+  The string comparison operators are implemented as a custom extension to the JSPath and does not strictly follow the `RFC 9535 <https://www.rfc-editor.org/rfc/rfc9535.html>`_.
 
 JWT Security
 ~~~~~~~~~~~~

docs/references/configuration.rst

@@ -315,6 +315,10 @@ db-extra-search-path
 
   Multiple schemas can be added in a comma-separated string, e.g. ``public, extensions``.
 
+.. important::
+  
+  We default this config to ``public`` because it is the most common schema used to install PostgreSQL extensions such as :ref:`PostGIS <ww_postgis>`. You can disable this by setting this config to ``""``.
+
 .. _db-hoisted-tx-settings:
 
 db-hoisted-tx-settings
@@ -616,7 +620,7 @@ jwt-role-claim-key
 
   *For backwards compatibility, this config parameter is also available without prefix as "role-claim-key".*
 
-  See :ref:`jwt_role_claim_key_extract` on how to specify key paths and usage examples.
+  See :ref:`jwt_role_extract` on how to specify key paths and usage examples.
 
 .. _jwt-secret:
 
@@ -718,7 +722,7 @@ log-query
   =============== =================================
 
   Logs the SQL query for the corresponding request at the current :ref:`log-level`.
-  See :ref:``sql_query_logs``.
+  See :ref:`sql_query_logs`.
 
     .. code:: bash
 
@@ -890,7 +894,7 @@ server-timing-enabled
   **In-Database** pgrst.server_timing_enabled
   =============== =================================
 
-  Enables the `Server-Timing <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing>`_ header.
+  Enables the `Server-Timing <https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Server-Timing>`_ header.
   See :ref:`server-timing_header`.
 
 .. _server-unix-socket:

docs/requirements.txt

@@ -2,6 +2,6 @@
 sphinx==7.4.7
 sphinx-copybutton==0.5.2
 sphinx-rtd-dark-mode==1.3.0
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==3.0.2
 sphinx-tabs==3.4.7
 sphinxext-opengraph==0.9.1

docs/tutorials/tut1.rst

@@ -52,17 +52,31 @@ Check that the :code:`tutorial.conf` (created in the previous tutorial) has the
 
 If the PostgREST server is still running from the previous tutorial, restart it to load the updated configuration file.
 
+.. _tut1_step3:
+
 Step 3. Sign a Token
 --------------------
 
-Ordinarily your own code in the database or in another server will create and sign authentication tokens, but for this tutorial we will make one "by hand." Go to `jwt.io <https://jwt.io/#debugger-io>`_ and fill in the fields like this:
+Ordinarily your own code in the database or in another server will create and sign authentication tokens, but for this tutorial we will make one "by hand" using ``bash`` and ``openssl``.
 
-.. figure:: ../_static/tuts/tut1-jwt-io.png
-   :alt: jwt.io interface
+.. code:: bash
 
-   How to create a token at https://jwt.io
+  #!/bin/bash
+  set -e
 
-**Remember to fill in the secret you generated rather than the word "secret".** After you have filled in the secret and payload, the encoded data on the left will update. Copy the encoded token.
+  JWT_SECRET='test_secret_that_is_at_least_32_characters_long'
+
+  _base64 () { openssl base64 -e -A | tr '+/' '-_' | tr -d '='; }
+
+  header=$(echo -n '{"alg":"HS256","typ":"JWT"}' | _base64)
+
+  payload=$(echo -n "{\"role\":\"todo_user\"}" | _base64)
+
+  signature=$(echo -n "$header.$payload" | openssl dgst -sha256 -hmac "$JWT_SECRET" -binary | _base64)
+
+  echo -n "$header.$payload.$signature"
+
+**Remember to fill in the secret you generated rather than keeping the "test_secret_that_is_at_least_32_characters_long".** After you have filled in the secret and payload, the encoded data on the left will update. Copy the encoded token.
 
 .. note::
 
@@ -145,14 +159,22 @@ To observe expiration in action, we'll add an :code:`exp` claim of five minutes
 
   select extract(epoch from now() + '5 minutes'::interval) :: integer;
 
-Go back to jwt.io and change the payload to
+Or in ``bash``:
 
-.. code-block:: json
 
-  {
-    "role": "todo_user",
-    "exp": 123456789
-  }
+.. code-block:: bash
+
+  exp=$(( EPOCHSECONDS + 5*60 ))  # five minutes
+
+  echo $exp
+
+Go back to :ref:`tut1_step3` and change the payload to
+
+.. code-block:: bash
+
+  payload=$(echo -n "{\"role\":\"todo_user\",\"exp\":\"123456789\"}" | _base64)
+
+  echo -n "$header.$payload.$signature"
 
 **NOTE**: Don't forget to change the dummy epoch value :code:`123456789` in the snippet above to the epoch value returned by the :code:`psql` command.
 

nix/tools/docs.nix

@@ -2,6 +2,7 @@
 , aspellDicts
 , buildToolbox
 , checkedShellScript
+, fetchPypi
 , lib
 , plantuml
 , python3
@@ -10,11 +11,23 @@
 , writers
 }:
 let
-  selectPythonPackages = ps: [
+  selectPythonPackages = ps:
+    let
+      # TODO: Remove with next nixpkgs update
+      sphinx-rtd-theme = assert ps.sphinx-rtd-theme.version == "2.0.0"; ps.sphinx-rtd-theme.overrideAttrs rec {
+        version = "3.0.2";
+        src = fetchPypi {
+          pname = "sphinx_rtd_theme";
+          inherit version;
+          hash = "sha256-t0V7wl3acjsgsIamcLmVPIWeq2CioD7o6yuyPhduX4U=";
+        };
+      };
+    in
+    [
       ps.sphinx
       ps.sphinx-copybutton
-    ps.sphinx-rtd-dark-mode
-    ps.sphinx-rtd-theme
+      (ps.sphinx-rtd-dark-mode.override { inherit sphinx-rtd-theme; })
+      sphinx-rtd-theme
       ps.sphinx-tabs
       ps.sphinxext-opengraph
     ];

postgrest.cabal

@@ -1,5 +1,5 @@
 name:               postgrest
-version:            13.0.0
+version:            13.0.2
 synopsis:           REST API for any Postgres database
 description:        Reads the schema of a PostgreSQL database and creates RESTful routes
                     for tables, views, and functions, supporting all HTTP methods that security

src/PostgREST/AppState.hs

@@ -407,7 +407,7 @@ retryingSchemaCacheLoad appState@AppState{stateObserver=observer, stateMainThrea
         Left e -> do
           putSCacheStatus appState SCPending
           putSchemaCache appState Nothing
-          observer $ SchemaCacheErrorObs e
+          observer $ SchemaCacheErrorObs configDbSchemas configDbExtraSearchPath e
           return Nothing
 
         Right sCache -> do

src/PostgREST/CLI.hs

@@ -60,7 +60,7 @@ dumpSchema appState = do
   case result of
     Left e -> do
       let observer = AppState.getObserver appState
-      observer $ SchemaCacheErrorObs e
+      observer $ SchemaCacheErrorObs configDbSchemas configDbExtraSearchPath e
       exitFailure
     Right sCache -> return $ JSON.encode sCache
 

src/PostgREST/Config.hs

@@ -256,8 +256,8 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     <*> (fmap encodeUtf8 <$> optString "db-anon-role")
     <*> (fromMaybe "pgrst" <$> optString "db-channel")
     <*> (fromMaybe True <$> optBool "db-channel-enabled")
-    <*> (maybe ["public"] splitOnCommas <$> optValue "db-extra-search-path")
-    <*> (maybe defaultHoistedAllowList splitOnCommas <$> optValue "db-hoisted-tx-settings")
+    <*> (maybe ["public"] splitOnCommasEmptyable <$> optStringEmptyable "db-extra-search-path")
+    <*> (maybe defaultHoistedAllowList splitOnCommas <$> optString "db-hoisted-tx-settings")
     <*> optWithAlias (optInt "db-max-rows")
                      (optInt "max-rows")
     <*> (fromMaybe False <$> optBool "db-plan-enabled")
@@ -272,8 +272,8 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     <*> (fromMaybe True <$> optBool "db-prepared-statements")
     <*> (fmap toQi <$> optWithAlias (optString "db-root-spec")
                                     (optString "root-spec"))
-    <*> (fromList . maybe ["public"] splitOnCommas <$> optWithAlias (optValue "db-schemas")
-                                                                    (optValue "db-schema"))
+    <*> (fromList . maybe ["public"] splitOnCommas <$> optWithAlias (optString "db-schemas")
+                                                                    (optString "db-schema"))
     <*> (fromMaybe True <$> optBool "db-config")
     <*> (fmap toQi <$> optString "db-pre-config")
     <*> parseTxEnd "db-tx-end" snd
@@ -404,8 +404,8 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     optString :: C.Key -> C.Parser C.Config (Maybe Text)
     optString k = mfilter (/= "") <$> overrideFromDbOrEnvironment C.optional k coerceText
 
-    optValue :: C.Key -> C.Parser C.Config (Maybe C.Value)
-    optValue k = overrideFromDbOrEnvironment C.optional k identity
+    optStringEmptyable :: C.Key -> C.Parser C.Config (Maybe Text)
+    optStringEmptyable k = overrideFromDbOrEnvironment C.optional k coerceText
 
     optInt :: (Read i, Integral i) => C.Key -> C.Parser C.Config (Maybe i)
     optInt k = join <$> overrideFromDbOrEnvironment C.optional k coerceInt
@@ -445,9 +445,12 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
         Nothing -> (> 0) <$> (readMaybe s :: Maybe Integer)
     coerceBool _            = Nothing
 
-    splitOnCommas :: C.Value -> [Text]
-    splitOnCommas (C.String s) = T.strip <$> T.splitOn "," s
-    splitOnCommas _            = []
+    splitOnCommas :: Text -> [Text]
+    splitOnCommas s = T.strip <$> T.splitOn "," s
+
+    splitOnCommasEmptyable :: Text -> [Text]
+    splitOnCommasEmptyable "" = []
+    splitOnCommasEmptyable s  = T.strip <$> T.splitOn "," s
 
     defaultHoistedAllowList = ["statement_timeout","plan_filter.statement_cost_limit","default_transaction_isolation"]
 

src/PostgREST/Error.hs

@@ -595,6 +595,10 @@ pgErrorStatus authed (SQL.SessionUsageError (SQL.QueryError _ _ (SQL.ResultError
           if BS.isSuffixOf "requires a WHERE clause" m
             then HTTP.status400 -- special case for pg-safeupdate, which we consider as client error
             else HTTP.status500 -- generic function or view server error, e.g. "more than one row returned by a subquery used as an expression"
+        "22023"   -> -- invalid_parameter_value. Catch nonexistent role error, see https://github.com/PostgREST/postgrest/issues/3601
+          if BS.isPrefixOf "role" m && BS.isSuffixOf "does not exist" m
+            then HTTP.status401 -- role in jwt does not exist
+            else HTTP.status400
         '2':'5':_ -> HTTP.status500 -- invalid tx state
         '2':'8':_ -> HTTP.status403 -- invalid auth specification
         '2':'D':_ -> HTTP.status500 -- invalid tx termination

src/PostgREST/Metrics.hs

@@ -52,7 +52,7 @@ observationMetrics (MetricsState poolTimeouts poolAvailable poolWaiting _ schema
   SchemaCacheLoadedObs resTime -> do
     withLabel schemaCacheLoads "SUCCESS" incCounter
     setGauge schemaCacheQueryTime resTime
-  SchemaCacheErrorObs _ -> do
+  SchemaCacheErrorObs{} -> do
     withLabel schemaCacheLoads "FAIL" incCounter
   _ ->
     pure ()

src/PostgREST/Observation.hs

@@ -14,6 +14,7 @@ module PostgREST.Observation
   ) where
 
 import qualified Data.ByteString.Lazy       as LBS
+import           Data.List.NonEmpty         (toList)
 import qualified Data.Text                  as T
 import qualified Data.Text.Encoding         as T
 import qualified Hasql.Connection           as SQL
@@ -25,7 +26,7 @@ import           Numeric                    (showFFloat)
 import           PostgREST.Config.PgVersion
 import qualified PostgREST.Error            as Error
 
-import Protolude
+import Protolude         hiding (toList)
 import Protolude.Partial (fromJust)
 
 data Observation
@@ -37,7 +38,7 @@ data Observation
   | ExitDBNoRecoveryObs
   | ExitDBFatalError ObsFatalError SQL.UsageError
   | DBConnectedObs Text
-  | SchemaCacheErrorObs SQL.UsageError
+  | SchemaCacheErrorObs (NonEmpty Text) [Text] SQL.UsageError
   | SchemaCacheQueriedObs Double
   | SchemaCacheSummaryObs Text
   | SchemaCacheLoadedObs Double
@@ -88,8 +89,12 @@ observationMessage = \case
     "If you are using connection poolers in transaction mode, try setting db-prepared-statements to false. " <> jsonMessage usageErr
   ExitDBFatalError ServerError08P01 usageErr ->
     "Connection poolers in statement mode are not supported." <> jsonMessage usageErr
-  SchemaCacheErrorObs usageErr ->
-    "Failed to load the schema cache. " <> jsonMessage usageErr
+  SchemaCacheErrorObs dbSchemas extraPaths usageErr ->
+    "Failed to load the schema cache using "
+      <> "db-schemas=" <> T.intercalate "," (toList dbSchemas)
+      <> " and "
+      <> "db-extra-search-path=" <> T.intercalate "," extraPaths
+      <> ". " <> jsonMessage usageErr
   SchemaCacheQueriedObs resultTime ->
     "Schema cache queried in " <> showMillis resultTime  <> " milliseconds"
   SchemaCacheSummaryObs summary ->

src/PostgREST/Query/QueryBuilder.hs

@@ -53,8 +53,8 @@ readPlanToQuery node@(Node ReadPlan{select,from=mainQi,fromAlias,where_=logicFor
   (if null logicForest && null relJoinConds
     then mempty
     else " WHERE " <> intercalateSnippet " AND " (map (pgFmtLogicTree qi) logicForest ++ map pgFmtJoinCondition relJoinConds)) <> " " <>
-  groupF qi select relSelect <>
-  orderF qi order <>
+  groupF qi select relSelect <> " " <>
+  orderF qi order <> " " <>
   limitOffsetF readRange
   where
     fromFrag = fromF relToParent mainQi fromAlias

test/io/fixtures.yaml

@@ -196,6 +196,24 @@ roleclaims:
           - obj_key: obj_value
     expected_status: 401 # fails because it compares an object with a string
 
+jwtaudroleclaims:
+  - key: '.aud'
+    data:
+      aud: postgrest_test_author
+    expected_status: 200
+  - key: '.aud'
+    data:
+      aud: postgrest_test_invalid
+    expected_status: 401
+  - key: '.aud[0]'
+    data:
+      aud: [postgrest_test_author]
+    expected_status: 200
+  - key: '.aud[1]' # succeeds the aud claims check, but fail when hits the db
+    data:
+      aud: [postgrest_test_author, postgrest_test_invalid]
+    expected_status: 401
+
 invalidroleclaimkeys:
   - 'role.other'
   - '.role##'

test/io/test_io.py

@@ -96,8 +96,7 @@ def test_jwt_errors(defaultenv):
 
         headers = jwtauthheader({"role": "not_existing"}, SECRET)
         response = postgrest.session.get("/", headers=headers)
-        # TODO: Should this return 401?
-        assert response.status_code == 400
+        assert response.status_code == 401
         assert response.json()["message"] == 'role "not_existing" does not exist'
 
         # -31 seconds, because we allow clock skew of 30 seconds
@@ -234,6 +233,28 @@ def test_role_claim_key(roleclaim, defaultenv):
         assert response.status_code == roleclaim["expected_status"]
 
 
+@pytest.mark.parametrize(
+    "jwtaudroleclaim",
+    FIXTURES["jwtaudroleclaims"],
+    ids=lambda claim: claim["key"] + "_" + str(claim["expected_status"]),
+)
+def test_jwt_aud_in_role_claim_key(jwtaudroleclaim, defaultenv):
+    "Allows authorization with JWT aud claim in role-claim-key"
+
+    env = {
+        **defaultenv,
+        "PGRST_JWT_AUD": "postgrest_test_author",
+        "PGRST_JWT_ROLE_CLAIM_KEY": jwtaudroleclaim["key"],
+        "PGRST_JWT_SECRET": SECRET,
+    }
+
+    headers = jwtauthheader(jwtaudroleclaim["data"], SECRET)
+
+    with run(env=env) as postgrest:
+        response = postgrest.session.get("/authors_only", headers=headers)
+        assert response.status_code == jwtaudroleclaim["expected_status"]
+
+
 def test_iat_claim(defaultenv):
     """
     A claim with an 'iat' (issued at) attribute should be successful.
@@ -1875,3 +1896,36 @@ def test_invalidate_jwt_cache_when_secret_changes(tmp_path, defaultenv):
         # now the request should fail because the cached token is removed
         response = postgrest.session.get("/authors_only", headers=headers)
         assert response.status_code == 401
+
+
+def test_allow_configs_to_be_set_to_empty(defaultenv):
+    'configs that are explicitly set to empty (= "<empty>") should not throw parse error'
+
+    env = {
+        **defaultenv,
+        "PGRST_DB_EXTRA_SEARCH_PATH": "",
+    }
+
+    with run(env=env) as postgrest:
+        response = postgrest.session.get("/projects")
+        assert response.status_code == 200
+
+
+def test_schema_cache_error_observation(defaultenv):
+    "schema cache error observation should be logged with invalid db-schemas or db-extra-search-path"
+
+    env = {
+        **defaultenv,
+        "PGRST_DB_EXTRA_SEARCH_PATH": "x",
+    }
+
+    with run(env=env, no_startup_stdout=False, wait_for_readiness=False) as postgrest:
+        # TODO: postgrest should exit here, instead it keeps retrying
+        # exitCode = wait_until_exit(postgrest)
+        # assert exitCode == 1
+
+        output = postgrest.read_stdout(nlines=9)
+        assert (
+            "Failed to load the schema cache using db-schemas=public and db-extra-search-path=x"
+            in output[7]
+        )

test/spec/Feature/Query/ErrorSpec.hs

@@ -42,10 +42,10 @@ pgErrorCodeMapping = do
       it "works with SchemaCache error" $
         get "/non_existent_table"
           `shouldRespondWith`
-          [json| {"code":"PGRST205","details":null,"hint":"Perhaps you meant the table 'test.json_table'","message":"Could not find the table 'test.non_existent_table' in the schema cache"} |]
+          [json| {"code":"PGRST205","details":null,"hint":"Perhaps you meant the table 'test.collision_test_table'","message":"Could not find the table 'test.non_existent_table' in the schema cache"} |]
           { matchStatus  = 404
           , matchHeaders = [ "Proxy-Status" <:> "PostgREST; error=PGRST205"
-                           , "Content-Length" <:> "172" ]
+                           , "Content-Length" <:> "182" ]
           }
 
       it "works with Jwt error" $ do

test/spec/Feature/Query/RangeSpec.hs

@@ -223,6 +223,14 @@ spec = do
                              , "Content-Range" <:> "2-4/*" ]
             }
 
+      it "works alongside order by with nulls order" $
+         get "/clients?select=id,projects(id,tasks(id))&order=id.asc.nullslast&limit=1&projects.order=id.asc.nullsfirst&projects.limit=2"
+           `shouldRespondWith`
+           [json|[{"id":1,"projects":[{"id": 1, "tasks": [{"id": 1}, {"id": 2}]}, {"id": 2, "tasks": [{"id": 3}, {"id": 4}]}]}]|]
+           { matchStatus  = 200
+           , matchHeaders = ["Content-Range" <:> "0-0/*"]
+           }
+
       context "succeeds if offset equals 0 as a no-op" $ do
         it  "no items" $ do
           get "/items?offset=0&id=eq.0"

test/spec/Feature/Query/RpcSpec.hs

@@ -1450,3 +1450,11 @@ spec =
           { matchStatus = 200
           , matchHeaders = [matchContentTypeJson]
           }
+
+    context "schema cache duplicate definitions when two entries in pg_description have the same OID" $
+      it "doesn't err with 300 Multiple Choices" $
+        request methodGet "/rpc/collision_test_func?id=1"
+          [] ""
+          `shouldRespondWith`
+          [json| 1 |]
+          { matchStatus = 200 }

test/spec/fixtures/schema.sql

@@ -3800,3 +3800,18 @@ create table factory_buildings (
   factory_id int references factories(id),
   inspections jsonb
 );
+
+-- collision test as occured in https://github.com/PostgREST/postgrest/issues/4052
+create table test.collision_test_table (id integer);
+comment on table collision_test_table is 'foobarbaz';
+
+create function test.collision_test_func(id integer)
+returns int language sql as $$
+  select 1;
+$$;
+
+update pg_proc
+set oid = 'test.collision_test_table'::regclass::oid
+where oid = 'test.collision_test_func'::regproc::oid;
+
+comment on function test.collision_test_func(id integer) is 'fizzbuzz';