Bump to PostgREST v9 (#468)

* Add highlights and modify changelog structure * Rename upcoming page to v9.0.0 * Classify features, edit breaking changes and fixes * Highlight top-level filtering * Clarify PostgreSQL 14 breaking change * Add devops to doc improvements * Add curl snippets to doc improvements

Author: laurenceisla

admin.rst

@@ -207,7 +207,7 @@ Automatic Connection Recovery
 
 When PostgREST loses the connection to the database, it retries the connection using capped exponential backoff, with 32 seconds being the maximum backoff time.
 
-This retry behavior is triggered immediately after the connection is lost if :ref:`db-channel-enabled` is set to true (this is the default behavior), otherwise it will be activated once a request is made.
+This retry behavior is triggered immediately after the connection is lost if :ref:`db-channel-enabled` is set to true(the default), otherwise it will be activated once a request is made.
 
 To notify the client when the next reconnection attempt will be, PostgREST responds with ``503 Service Unavailable`` and the ``Retry-After: x`` header, where ``x`` is the number of seconds programmed for the next retry.
 

api.rst

@@ -910,6 +910,8 @@ If you want to embed through join tables but need more control on the intermedia
 
  curl "http://localhost:3000/actors?select=roles(character,films(title,year))"
 
+.. _embed_filters:
+
 Embedded Filters
 ----------------
 
@@ -991,10 +993,10 @@ The result will show the nested actors named Tom and order them by last name. Al
 
 .. _embedding_top_level_filter:
 
-Top Level Filtering
-~~~~~~~~~~~~~~~~~~~
+Embedding with Top-level Filtering
+----------------------------------
 
-By default, embedded filters don't change the top level resource rows at all:
+By default, :ref:`embed_filters` don't change the top-level resource(``films``) rows at all:
 
 .. tabs::
 
@@ -1095,8 +1097,9 @@ Since it contains the ``films_id`` foreign key, it is possible to embed ``box_of
  curl "http://localhost:3000/box_office?select=bo_date,gross_revenue,films(title)&gross_revenue=gte.1000000"
 
 .. note::
+ * Embedding on partitions is not allowed because it leads to ambiguity errors (see :ref:`embed_disamb`) between them and their parent partitioned table(more details at `#1783(comment) <https://github.com/PostgREST/postgrest/issues/1783#issuecomment-959823827>`_). :ref:`custom_queries` can be used if this is needed.
+
  * Partitioned tables can reference other tables since PostgreSQL 11 but can only be referenced from any other table since PostgreSQL 12.
- * Embedding on partitions is not allowed because it leads to ambiguity errors (see :ref:`embed_disamb`) between them and their parent partitioned table. :ref:`custom_queries` can be used if this is needed.
 
 .. _embedding_views:
 
@@ -1255,6 +1258,8 @@ For doing resource embedding, PostgREST infers the relationship between two tabl
 However, in cases where there's more than one foreign key between two tables, it's not possible to infer the relationship unambiguously
 by just specifying the tables names.
 
+.. _target_disamb:
+
 Target Disambiguation
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -1281,6 +1286,8 @@ the request is ambiguous and PostgREST will respond with an error:
 
  HTTP/1.1 300 Multiple Choices
 
+ {..}
+
 If this happens, you need to disambiguate the request by adding precision to the **target**.
 Instead of the **table name**, you can specify the **foreign key constraint name** or the **column name** that is part of the foreign key.
 
@@ -1344,6 +1351,8 @@ the result more clear.
  }
  ]
 
+.. _hint_disamb:
+
 Hint Disambiguation
 ~~~~~~~~~~~~~~~~~~~
 
@@ -2430,8 +2439,10 @@ You can also select the schema for :ref:`s_procs` and :ref:`open-api`.
 
  These headers are based on the nascent "Content Negotiation by Profile" spec: https://www.w3.org/TR/dx-prof-conneg
 
-HTTP Logic
-==========
+.. _http_context:
+
+HTTP Context
+============
 
 .. _guc_req_headers_cookies_claims:
 

ecosystem.rst

@@ -28,7 +28,6 @@ Example Apps
 ------------
 
 * `chronicle <https://github.com/srid/chronicle>`_ - tracking a tree of personal memories
-* `cloudgov-demo-postgrest <https://github.com/GSA/cloudgov-demo-postgrest>`_ - demo for a federally-compliant REST API on cloud.gov
 * `code-du-travail-backoffice <https://github.com/SocialGouv/code-du-travail-backoffice>`_ - data administration portal for the official French Labor Code and Agreements
 * `delibrium-postgrest <https://gitlab.com/delibrium/delibrium-postgrest/>`_ - example school API and front-end in Vue.js
 * `elm-workshop <https://github.com/diogob/elm-workshop>`_ - building a simple database query UI
@@ -53,13 +52,14 @@ Example Apps
 * `PostGUI <https://github.com/priyank-purohit/PostGUI>`_ - React Material UI admin panel
 * `prospector <https://github.com/sfcta/prospector>`_ - data warehouse and visualization platform
 
-.. _dev_ops:
+.. _devops:
 
 DevOps
 ------
 
-* `jbkarle/postgrest <https://github.com/jbkarle/postgrest>`_ - helm chart with a demo database for development and test purposes
+* `cloudgov-demo-postgrest <https://github.com/GSA/cloudgov-demo-postgrest>`_ - demo for a federally-compliant REST API on cloud.gov
 * `cloudstark/helm-charts <https://github.com/cloudstark/helm-charts/tree/master/postgrest>`_ - helm chart to deploy PostgREST to a Kubernetes cluster via a Deployment and Service
+* `jbkarle/postgrest <https://github.com/jbkarle/postgrest>`_ - helm chart with a demo database for development and test purposes
 
 .. _eco_external_notification:
 

index.rst

@@ -94,12 +94,16 @@ The project has a friendly and growing community. Join our `chat room <https://g
 
 .. toctree::
  :glob:
- :reversed:
  :caption: Release Notes
  :titlesonly:
  :hidden:
 
- releases/*
+ v9.0.0 <releases/v9.0.0>
+ releases/v8.0.0
+ releases/v7.0.1
+ releases/v7.0.0
+ releases/v6.0.2
+ releases/v5.2.0
 
 Tutorials
 ---------
@@ -212,7 +216,7 @@ PostgREST has a growing ecosystem of examples, libraries, and experiments. Here
 * :ref:`community_tutorials`
 * :ref:`templates`
 * :ref:`eco_example_apps`
-* :ref:`dev_ops`
+* :ref:`devops`
 * :ref:`eco_external_notification`
 * :ref:`eco_extensions`
 * :ref:`clientside_libraries`
@@ -224,6 +228,7 @@ Release Notes
 Here we'll include the most relevant changes so you can migrate to newer versions easily.
 You can see the full changelog of each release in the `PostgREST repository <https://github.com/PostgREST/postgrest/releases>`_.
 
+- :doc:`releases/v9.0.0`
 - :doc:`releases/v8.0.0`
 - :doc:`releases/v7.0.0`
 - :doc:`releases/v6.0.2`

releases/upcoming.rst

@@ -0,0 +1,130 @@
+
+PostgREST 9.0.0
+===============
+
+This major version is released with PostgreSQL 14 compatibility and is accompanied with new features and bug fixes. You can look at the detailed changelog and download the pre-compiled binaries on the `GitHub release page <https://github.com/PostgREST/postgrest/releases/tag/v9.0.0>`_.
+
+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 <https://postgrest.org/en/v8.0/api.html#accessing-request-headers-cookies-and-jwt-claims>`_ to fail across all requests. Thankfully, `@robertsosinski <https://github.com/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 <https://www.postgresql.org/message-id/17045-6a4a9f0d1513f72b%40postgresql.org>`_.
+
+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 <guc_req_headers_cookies_claims>`. 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.
+
+Resource Embedding with Top-level Filtering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Historically, Resource Embedding was always done with a query that included the equivalent of a ``LEFT JOIN``, which meant you could not
+exclude any of the top-level resource rows. You can now use :ref:`embedding_top_level_filter` to do the equivalent of an ``INNER JOIN``, thus you can filter the top-level resource rows with any of the available operators.
+
+Partitioned Tables
+~~~~~~~~~~~~~~~~~~
+
+Partitioned tables now integrate with all the feature set. You can :ref:`embed partitioned tables <embedding_partitioned_tables>`, UPSERT, INSERT(with a correctly generated Location header) and make OPTIONS requests on them. They're also included in the generated OpenAPI.
+
+Functions(RPC)
+~~~~~~~~~~~~~~
+
+* Functions with a :ref:`single unnamed parameter <s_proc_single_unnamed>` can now be used to POST raw ``bytea``, ``text`` or ``json/jsonb``.
+
+Horizontal Filtering
+~~~~~~~~~~~~~~~~~~~~
+
+* The ``unknown`` value for three-valued logic can now be used on the ``is`` :ref:`operator <operators>`.
+
+* Escaping double quotes(``"``) in double-quoted surrounded strings is now possible by using backslashes, e.g. ``?col=in.("Double\"Quote")``. Backslashes can be escaped with a preceding backslash, e.g. ``?col=in.("Back\\slash")``. See :ref:`reserved-chars`.
+
+Administration
+~~~~~~~~~~~~~~
+
+* A ``Retry-After`` header is now added when PostgREST is doing :ref:`automatic_recovery`.
+
+Error messages
+~~~~~~~~~~~~~~
+
+* :ref:`embed_disamb` now shows an improved error message that includes relevant hints for clearing out the ambiguous embedding.
+
+Documentation improvements
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Added ``curl`` snippets to the :doc:`API <../api>` page.
+
+* Added the :ref:`automatic_recovery` section.
+
+* Added the :ref:`nested_embedding` section.
+
+* Added the :ref:`logical_operators` section.
+
+* Added the :ref:`templates` and :ref:`devops` sections to the :doc:`Ecosystem </ecosystem>`.
+
+Bug fixes
+---------
+
+* Correct RPC return type handling for RETURNS TABLE with a single column (`#1930 <https://github.com/PostgREST/postgrest/pull/1930>`_).
+
+* Schema Cache query failing with ``standard_conforming_strings = off`` (`#1992 <https://github.com/PostgREST/postgrest/issues/1992>`_).
+
+* OpenAPI missing default values for String types (`#1871 <https://github.com/PostgREST/postgrest/issues/1871>`_).
+
+Breaking changes
+----------------
+
+* Dropped support for PostgreSQL 9.5 as it already reached its end-of-life according to `PostgreSQL versioning policy <https://www.postgresql.org/support/versioning/>`_.
+
+* Partitions of a `partitioned table <https://www.postgresql.org/docs/current/ddl-partitioning.html#DDL-PARTITIONING-DECLARATIVE>`_ are no longer included in the :ref:`schema_cache`. This is so errors are not generated when doing resource embedding on partitioned tables.
+
+* Dropped support for doing :ref:`hint_disamb` using dots instead of exclamation marks, e.g. doing ``select=*,projects.client_id(*)`` instead of ``select=*,projects!client_id(*)``). Using dots was undocumented and deprecated back in `v6.0.2 <https://github.com/PostgREST/postgrest/releases/tag/v6.0.2>`_.
+
+Thanks
+------
+
+Big thanks from the `PostgREST team <https://github.com/orgs/PostgREST/people>`_ to our sponsors!
+
+.. container:: image-container
+
+ .. image:: ../_static/cybertec-new.png
+ :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest
+ :width: 13em
+
+ .. image:: ../_static/2ndquadrant.png
+ :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo
+ :width: 13em
+
+ .. image:: ../_static/retool.png
+ :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest
+ :width: 13em
+
+ .. image:: ../_static/gnuhost.png
+ :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest
+ :width: 13em
+
+ .. image:: ../_static/supabase.png
+ :target: https://supabase.io/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage
+ :width: 13em
+
+ .. image:: ../_static/oblivious.jpg
+ :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest
+ :width: 13em
+
+* Evans Fernandes
+* `Jan Sommer <https://github.com/nerfpops>`_
+* `Franz Gusenbauer <https://www.igutech.at/>`_
+* `Daniel Babiak <https://github.com/dbabiak>`_
+* Tsingson Qin
+* Michel Pelletier
+* Jay Hannah
+* Robert Stolarz
+* Nicholas DiBiase
+* Christopher Reid
+* Nathan Bouscal
+* Daniel Rafaj
+* David Fenko
+* Remo Rechkemmer
+* Severin Ibarluzea
+* Tom Saleeba
+* Pawel Tyll
+
+If you like to join them please consider `supporting PostgREST development <https://github.com/PostgREST/postgrest#user-content-supporting-development>`_.