Refine docs for v10
* shorten release page * shorten explain docs * add limited update/delete to release page * refine relationships * refine disambiguation * refine release page * remove migration guide * add author to WWT how-to
This commit is contained in:
Steve Chavez
+67
-177
@@ -5,79 +5,65 @@ PostgREST 10.0.0
|
||||
Features
|
||||
--------
|
||||
|
||||
API
|
||||
~~~
|
||||
|
||||
XML/SOAP support for RPC
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
RPC now understands the ``text/xml`` media type, allowing SQL functions to send XML output(``Accept: text/xml``) and receive XML input(``Content-Type: text/xml``). This makes SOAP endpoints possible, check the :ref:`create_soap_endpoint` how-to for more details.
|
||||
RPC now understands the ``text/xml`` media type, allowing SQL functions to send XML output(``Accept: text/xml``) and receive XML input(``Content-Type: text/xml``). This makes SOAP endpoints possible, check the :ref:`create_soap_endpoint` how-to and the :ref:`scalar_return_formats` reference for more details.
|
||||
|
||||
GeoJSON support
|
||||
^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
GeoJSON is supported across the board(reads, writes, RPC) with the ``Accept: application/geo+json`` header, this depends on PostGIS from the versions 3.0.0 and up. The :ref:`working with PostGIS section <ww_postgis>` has an example to get you started.
|
||||
|
||||
One-to-one relationships
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Execution Plan
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
A :ref:`one-to-one relationship <one-to-one>` is now detected when a table's foreign key is also its primary key or when the foreign key has a ``UNIQUE`` constraint.
|
||||
The :ref:`execution plan <explain_plan>` of a request is now obtainable with the ``Accept: application/vnd.pgrst.plan`` header. The result can be in ``text`` or ``json`` formats and is compatible with EXPLAIN vizualizers like `explain.depesz.com <https://explain.depesz.com>`_ or `explain.dalibo.com <https://explain.dalibo.com>`_.
|
||||
|
||||
Customizable Relationships for Resource Embedding
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Resource Embedding
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Using :ref:`computed_relationships`, you can add custom relationships or override automatically detected ones. This makes :ref:`resource_embedding` possible on Foreign Data Wrappers and complex SQL views.
|
||||
- A :ref:`one-to-one relationship <one-to-one>` is now detected when a foreign key is unique.
|
||||
|
||||
EXPLAIN Execution Plan
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
- Using :ref:`computed_relationships`, you can add custom relationships or override automatically detected ones. This makes :ref:`resource_embedding` possible on Foreign Data Wrappers and complex SQL views.
|
||||
|
||||
The :ref:`EXPLAIN execution plan of a request <explain_plan>` is now obtainable with the ``Accept: application/vnd.pgrst.plan`` header. The result can be in ``text`` or ``json`` formats and is compatible with EXPLAIN vizualizers like `explain.depesz.com <https://explain.depesz.com>`_ or `explain.dalibo.com <https://explain.dalibo.com>`_.
|
||||
Horizontal/Vertical Filtering
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
POSIX Regular Expressions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
- :ref:`Accessing fields of a Composite type or elements of an Array type <composite_array_columns>` is now possible with the arrow operators(``->``, ``->>``) in the same way you would access a JSON type fields.
|
||||
|
||||
You can now use two :ref:`pattern matching <pattern_matching>` operators for `POSIX regular expressions <https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-POSIX-REGEXP>`_: ``match`` and ``imatch``, equivalent in PostgreSQL to ``~`` and ``~*`` respectively.
|
||||
- :ref:`pattern_matching` operators for `POSIX regular expressions <https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-POSIX-REGEXP>`_ are now available: ``match`` and ``imatch``, equivalent in PostgreSQL to ``~`` and ``~*`` respectively.
|
||||
|
||||
Access composite type fields and array elements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Insertions/Updates
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:ref:`Accessing fields of a Composite type or elements of an Array type <composite_array_columns>` is now possible with the arrow operators(``->``, ``->>``) in the same way you would access a JSON type fields.
|
||||
- ``limit`` can now affect the number of updated/deleted rows. See :ref:`limited_update_delete`.
|
||||
|
||||
Authorize button for SwaggerUI
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
OpenAPI
|
||||
~~~~~~~
|
||||
|
||||
You can now activate the "Authorize" button in SwaggerUI by enabling the :ref:`openapi-security-active` configuration. Add your JWT token prepending :code:`Bearer` to it and you'll be able to request protected resources.
|
||||
|
||||
Improved error messages
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To increase consistency, all the errors messages are now normalized. The ``hint``, ``details``, ``code`` and ``message`` fields will always be present in the body, each one defaulting to a
|
||||
``null`` value. In the same way, the :ref:`errors that were raised <raise_error>` with ``SQLSTATE`` now include the ``message`` and ``code`` in the body.
|
||||
|
||||
To further clarify the source of an error, we now add a ``PGRST`` prefix to the error code of all the errors that are PostgREST-specific and don't come from the database. These errors have unique codes that identifies them and are documented in the :ref:`pgrst_errors` section.
|
||||
|
||||
Administration
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Health checks
|
||||
^^^^^^^^^^^^^
|
||||
- Two :ref:`health check endpoints <health_check>` are now exposed in a secondary port.
|
||||
|
||||
Admins can now benefit from two :ref:`health check endpoints <health_check>` exposed in a different port than the main app. When activated, the ``live`` and ``ready`` endpoints are available to verify if PostgREST is alive and running or if the database connection and the :ref:`schema cache <schema_cache>` are ready for querying.
|
||||
- :ref:`pgrst_logging` now shows the database user.
|
||||
|
||||
Logging users
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
You can now see the :ref:`request database user in the logs <pgrst_logging>`.
|
||||
|
||||
Run without configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It is now possible to execute PostgREST without specifying any configuration variable. The three that were mandatory on the previous versions, are no longer so.
|
||||
- It is now possible to execute PostgREST without specifying any configuration variable. The three that were mandatory on the previous versions, are no longer so.
|
||||
|
||||
- If :ref:`db-uri` is not set, PostgREST will use the `libpq environment variables <https://www.postgresql.org/docs/current/libpq-envars.html>`_ for the database connection.
|
||||
- If :ref:`db-schemas` is not set, it will use the database ``public`` schema.
|
||||
- If :ref:`db-anon-role` is not set, it will not allow anonymous requests.
|
||||
|
||||
Error messages
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
- To increase consistency, all the errors messages are now normalized. The ``hint``, ``details``, ``code`` and ``message`` fields will always be present in the body, each one defaulting to a ``null`` value. In the same way, the :ref:`errors that were raised <raise_error>` with ``SQLSTATE`` now include the ``message`` and ``code`` in the body.
|
||||
|
||||
- To further clarify the source of an error, we now add a ``PGRST`` prefix to the error code of all the errors that are PostgREST-specific and don't come from the database. These errors have unique codes that identify them and are documented in the :ref:`pgrst_errors` section.
|
||||
|
||||
Documentation improvements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -95,7 +81,7 @@ Documentation improvements
|
||||
|
||||
* Removed direct links for PostgREST versions older than 8.0 from the versions menu.
|
||||
|
||||
* Removed the deprecated *Embedding table from another schema* how-to.
|
||||
* Removed the *Embedding table from another schema* how-to.
|
||||
|
||||
* Restructured the :ref:`resource_embedding` section:
|
||||
|
||||
@@ -103,6 +89,43 @@ Documentation improvements
|
||||
|
||||
- Renamed the *Embedding through join tables* subsection to :ref:`many-to-many`.
|
||||
|
||||
* Split up the *Insertions/Updates* section into :ref:`insert` and :ref:`update`.
|
||||
|
||||
Breaking changes
|
||||
----------------
|
||||
|
||||
* Many-to-many relationships now require that foreign key columns be part of the join table composite key
|
||||
|
||||
- This was needed to reduce :ref:`embed_disamb` errors in complex schemas(`#2070 <https://github.com/PostgREST/postgrest/issues/2070>`_).
|
||||
|
||||
- For migrating to this version, the less invasive method is to use :ref:`computed_relationships` to replace the previous many-to-many relationships.
|
||||
|
||||
- Otherwise you can change your join table primary key. For example with ``alter table permission_user drop constraint permission_user_pkey, add primary key (id, user_id, permission_id);``
|
||||
|
||||
* Views now are not detected when embedding using :ref:`target_disamb`.
|
||||
|
||||
- This embedding form was easily made ambiguous whenever a new view was added(`#2277 <https://github.com/PostgREST/postgrest/issues/2277>`_).
|
||||
|
||||
- For migrating to this version, you can use :ref:`computed_relationships` to replace the previous view relationships.
|
||||
|
||||
- :ref:`hint_disamb` works as usual on views.
|
||||
|
||||
* ``limit/offset`` now limits the affected rows on ``UPDATE``/``DELETE``
|
||||
|
||||
- Previously, ``limit``/``offset`` only limited the returned rows but not the actual updated rows(`#2156 <https://github.com/PostgREST/postgrest/issues/2156>`_)
|
||||
|
||||
* ``max-rows`` is no longer applied on ``POST``, ``PATCH``, ``PUT`` and ``DELETE`` returned rows
|
||||
|
||||
- This was misleading because the affected rows were not really affected by ``max-rows``, only the returned rows were limited(`#2155 <https://github.com/PostgREST/postgrest/issues/2155>`_)
|
||||
|
||||
* Return ``204 No Content`` without ``Content-Type`` for RPCs returning ``VOID``
|
||||
|
||||
- Previously, those RPCs would return ``null`` as a body with ``Content-Type: application/json`` (`#2001 <https://github.com/PostgREST/postgrest/issues/2001>`_).
|
||||
|
||||
* Using ``Prefer: return=representation`` no longer returns a ``Location`` header
|
||||
|
||||
- This reduces unnecessary computing for all insertions (`#2312 <https://github.com/PostgREST/postgrest/issues/2312>`_)
|
||||
|
||||
Bug fixes
|
||||
---------
|
||||
|
||||
@@ -152,139 +175,6 @@ Bug fixes
|
||||
|
||||
* Allow ``limit=0`` in the request query to return an empty array (`#2269 <https://github.com/PostgREST/postgrest/issues/2269>`_)
|
||||
|
||||
Breaking changes
|
||||
----------------
|
||||
|
||||
* Return ``204 No Content`` without ``Content-Type`` for RPCs returning ``VOID`` (`#2001 <https://github.com/PostgREST/postgrest/issues/2001>`_)
|
||||
|
||||
- Previously, those RPCs would return ``null`` as a body with ``Content-Type: application/json``.
|
||||
|
||||
* ``limit/offset`` now limits the affected rows on ``UPDATE``/``DELETE`` (`#2156 <https://github.com/PostgREST/postgrest/issues/2156>`_)
|
||||
|
||||
- Previously, ``limit``/``offset`` only limited the returned rows but not the actual updated rows
|
||||
|
||||
* ``max-rows`` is no longer applied on ``POST``, ``PATCH``, ``PUT`` and ``DELETE`` returned rows (`#2155 <https://github.com/PostgREST/postgrest/issues/2155>`_)
|
||||
|
||||
- This was misleading because the affected rows were not really affected by ``max-rows``, only the returned rows were limited
|
||||
|
||||
* Restrict generated many-to-many relationships (`#2070 <https://github.com/PostgREST/postgrest/issues/2070>`_)
|
||||
|
||||
- A primary key that contains the foreign key columns is now needed for generating many-to-many relationships.
|
||||
|
||||
* Views now are not detected when embedding using the column or foreign key as target (``/view?select=*,column(*)``) (`#2277 <https://github.com/PostgREST/postgrest/issues/2277>`_)
|
||||
|
||||
- This embedding form was easily made ambiguous whenever a new view was added.
|
||||
|
||||
- For migrating, clients must be updated to the embedding form of ``/view?select=*,other_view!column(*)``.
|
||||
|
||||
* Using ``Prefer: return=representation`` no longer returns a ``Location`` header (`#2312 <https://github.com/PostgREST/postgrest/issues/2312>`_)
|
||||
|
||||
Migration Guide
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Many-to-may relationships
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The way PostgREST infers many-to-many relationships is now restricted. Before this change, a table could work as an intermediate join between two tables just by having foreign keys referencing each one of them. Consider the following:
|
||||
|
||||
.. code-block:: postgresql
|
||||
|
||||
CREATE TABLE users (
|
||||
id INT PRIMARY KEY,
|
||||
name TEXT
|
||||
);
|
||||
|
||||
CREATE TABLE permissions (
|
||||
id INT PRIMARY KEY,
|
||||
name TEXT
|
||||
);
|
||||
|
||||
CREATE TABLE permission_user (
|
||||
id INT PRIMARY KEY,
|
||||
user_id INT REFERENCES users(id),
|
||||
permission_id INT REFERENCES permissions(id)
|
||||
);
|
||||
|
||||
Before, PostgREST could infer a relationship between ``users`` and ``permissions`` through ``permission_user``.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
GET /users?select=permissions(*) HTTP/1.1
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl "http://localhost:3000/users?select=permissions(*)"
|
||||
|
||||
But now this is not allowed. In order for it to work, the intermediate table must also have the foreign keys included in its primary key. So, in this case we need to do the following:
|
||||
|
||||
.. code-block:: postgresql
|
||||
|
||||
-- This table has a pk defined already so we drop it first
|
||||
alter table permission_user
|
||||
drop constraint permission_user_pkey;
|
||||
|
||||
-- Then we add all the foreign keys to the primary key
|
||||
alter table permission_user
|
||||
add primary key (id, user_id, permission_id);
|
||||
|
||||
With this, PostgREST 10 will infer successfully a relationship between ``users`` and ``permissions``.
|
||||
|
||||
If you want an alternative to the previous method or need a more customized relationship, you could use :ref:`computed_relationships` to get a similar result.
|
||||
|
||||
Embedding views
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Using column names or foreign key constraint names as :ref:`embedding targets <target_disamb>` will not detect views anymore. Consider this as an example:
|
||||
|
||||
.. code-block:: postgresql
|
||||
|
||||
CREATE TABLE users (
|
||||
id INT PRIMARY KEY,
|
||||
name TEXT,
|
||||
is_active BOOL
|
||||
);
|
||||
|
||||
CREATE TABLE messages (
|
||||
id INT PRIMARY KEY,
|
||||
body TEXT,
|
||||
user_id INT REFERENCES users(id)
|
||||
);
|
||||
|
||||
CREATE VIEW active_users AS
|
||||
SELECT *
|
||||
FROM users
|
||||
WHERE is_active;
|
||||
|
||||
Previously, the following request returned a ``300 Multiple Choices`` error, because the ``active_users`` view was also detected:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
GET /messages?select=body,user_id(name) HTTP/1.1
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl "http://localhost:3000/messages?select=body,user_id(name)"
|
||||
|
||||
But in this version, this will not fail and will embed the table ``users`` instead. You need to use the view name as target in order to embed it, like this:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
GET /messages?select=body,active_users(name) HTTP/1.1
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl "http://localhost:3000messages?select=body,active_users(name)"
|
||||
|
||||
For other cases, adding a column or foreign key as :ref:`hint <hint_disamb>` may be needed.
|
||||
|
||||
You could also use :ref:`computed_relationships` to get a similar result or if you want a more customized relationship.
|
||||
|
||||
Thanks
|
||||
------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user