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
This commit is contained in:
Laurence Isla
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
+3
-3
@@ -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:
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -1,56 +0,0 @@
|
||||
.. |br| raw:: html
|
||||
|
||||
<br />
|
||||
|
||||
Upcoming
|
||||
========
|
||||
|
||||
These are changes yet unreleased. If you'd like to try them out before a new official release, access `the list of CI runs <https://github.com/PostgREST/postgrest/actions/workflows/ci.yaml?query=branch%3Amain>`_
|
||||
and select the newest commit, then download the build from the Artifacts section at the bottom of the page (you'll need a GitHub account to download it).
|
||||
|
||||
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>`_
|
||||
|
||||
* Allow filtering top-level resource based on embedded resources filters. This is enabled by adding ``!inner`` to the embedded resource. See :ref:`embedding_top_level_filter`.
|
||||
|br| -- `@steve-chavez <https://github.com/steve-chavez>`_
|
||||
|
||||
* 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>`_
|
||||
|
||||
* Allow escaping inside double quotes with a backslash, e.g. ``?col=in.("Double\"Quote")``, ``?col=in.("Back\\slash")``. See :ref:`reserved-chars`.
|
||||
|br| -- `@steve-chavez <https://github.com/steve-chavez>`_
|
||||
|
||||
* Add ``Retry-After`` header when recovering the connection. See :ref:`automatic_recovery`.
|
||||
|br| -- `@gautam1168 <https://github.com/gautam1168>`_
|
||||
|
||||
* Allow calling a function with a :ref:`single unnamed parameter <s_proc_single_unnamed>` to POST raw ``json/jsonb``, ``bytea`` or ``text``.
|
||||
|br| -- `@steve-chavez <https://github.com/steve-chavez>`_
|
||||
|
||||
* Allow specifying ``unknown`` for the ``is`` :ref:`operator <operators>`.
|
||||
|br| -- `@steve-chavez <https://github.com/steve-chavez>`_
|
||||
|
||||
* Documentation improvements
|
||||
|
||||
+ Added :ref:`nested_embedding` to the :ref:`resource_embedding` section.
|
||||
+ Added the :ref:`templates` section to the :doc:`Ecosystem </ecosystem>`.
|
||||
+ Added the :ref:`logical_operators` section
|
||||
|
||||
Fixed
|
||||
-----
|
||||
|
||||
* Fix using single double quotes (``"``) and backslashes (``/``) as values on the "in" operator
|
||||
|br| -- `@steve-chavez <https://github.com/steve-chavez>`_
|
||||
|
||||
Changed
|
||||
-------
|
||||
|
||||
* Partitions (created using ``PARTITION OF``) are no longer included in the :ref:`schema_cache`.
|
||||
|br| -- `@laurenceisla <https://github.com/laurenceisla>`_
|
||||
@@ -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>`_.
|
||||
Reference in New Issue
Block a user