diff --git a/docs/admin.rst b/docs/admin.rst index e7a7448f9..36b9e5e6f 100644 --- a/docs/admin.rst +++ b/docs/admin.rst @@ -331,6 +331,8 @@ After that, you can enable the service at boot time and start it with: ## For reloading the service ## systemctl restart postgrest +.. _file_descriptors: + File Descriptors ---------------- diff --git a/docs/api.rst b/docs/api.rst index 7acaafa36..d1503fd42 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -269,8 +269,8 @@ Casting the columns is possible by suffixing them with the double colon ``::`` p .. _json_columns: -Array / Composite / JSON Columns --------------------------------- +JSON Columns +------------ You can specify a path for a ``json`` or ``jsonb`` column using the arrow operators(``->`` or ``->>``) as per the `PostgreSQL docs `_. @@ -354,8 +354,12 @@ Note that ``->>`` is used to compare ``blood_type`` as ``text``. To compare with { "id": 12, "age": 30 }, { "id": 15, "age": 35 } ] +.. _composite_array_columns: -The arrow operators are also used for array and composite type columns. +Composite / Array Columns +------------------------- + +The arrow operators(``->``, ``->>``) can also be used for accessing composite fields and array elements. .. code-block:: postgres @@ -396,7 +400,7 @@ The arrow operators are also used for array and composite type columns. When using the ``->`` and ``->>`` operators, PostgREST uses a query like ``to_jsonb()->'field'``. To make filtering and ordering on those nested fields use an index, the index needs to be created on the same expression, including the ``to_jsonb(...)`` call: .. code-block:: postgres - + CREATE INDEX ON mytable ((to_jsonb(data) -> 'identification' ->> 'registration_number')); .. _computed_cols: diff --git a/docs/errors.rst b/docs/errors.rst index 39fa807a4..8024c1109 100644 --- a/docs/errors.rst +++ b/docs/errors.rst @@ -3,7 +3,7 @@ Error Source ============ -For the most part, error messages will come directly from the database with the same `format that PostgreSQL uses `_, in other words, PostgREST will convert the ``MESSAGE``, ``DETAIL``, ``HINT`` and ``ERRCODE`` from the PostgreSQL error to JSON format and add an HTTP status code to the response (see :ref:`status_codes`). For instance, this is the error you will get when querying a nonexistent table: +For the most part, error messages will come directly from the database with the same `structure that PostgreSQL uses `_, PostgREST will convert the ``MESSAGE``, ``DETAIL``, ``HINT`` and ``ERRCODE`` from the PostgreSQL error to JSON format and add an HTTP status code to the response (see :ref:`status_codes`). For instance, this is the error you will get when querying a nonexistent table: .. code-block:: http diff --git a/docs/index.rst b/docs/index.rst index 9448cd089..e2caa8096 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -98,6 +98,7 @@ The project has a friendly and growing community. Join our `chat room v9.0.0 releases/v8.0.0 releases/v7.0.1 @@ -230,14 +231,10 @@ PostgREST has a growing ecosystem of examples, libraries, and experiments. Here 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 `_. +Changes among versions. - :doc:`releases/v9.0.0` - :doc:`releases/v8.0.0` -- :doc:`releases/v7.0.0` -- :doc:`releases/v6.0.2` -- :doc:`releases/v5.2.0` In Production ------------- diff --git a/docs/releases/latest.rst b/docs/releases/latest.rst new file mode 100644 index 000000000..101d8fd77 --- /dev/null +++ b/docs/releases/latest.rst @@ -0,0 +1,158 @@ + +Latest +====== + +These are features/bugfixes not yet on a stable version. You can try them by downloading the latest pre-releases `on the GitHub release page `_. + +Features +-------- + +API +~~~ + +Access Composite Type fields and Array elements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can now :ref:`access fields of a Composite type or elements of an Array type ` with the arrow operators(``->``, ``->>``) in the same way you would access the JSON type fields. + +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 ` with ``SQLSTATE`` now include the ``message`` and ``code`` in the body. + +In addition to these changes and to further clarify the source of an error, PostgREST now adds 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 a unique code that identifies them and are documented in the :ref:`pgrst_errors` section. + +Alongside these changes, there is now a dedicated reference page for :doc:`Error documentation `. + +Administration +~~~~~~~~~~~~~~ + +Health checks +^^^^^^^^^^^^^ + +Admins can now benefit from two :ref:`health check endpoints ` 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 ` are ready for querying. + +Logging users +^^^^^^^^^^^^^ + +You can now verify the current authenticated database user in the :ref:`request log ` on stdout. + +Run without configuration +^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is now possible to execute PostgREST without specifying any configuration variable, even without the three that were mandatory + + - If :ref:`db-uri` is not set, PostgREST will use the `libpq environment variables `_ 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. + +Documentation improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Added a :doc:`/how-tos/working-with-postgresql-data-types` how-to, which contains explanations and examples on how to work with different PostgreSQL data types such as timestamps, ranges or PostGIS types, among others. + +* Added in-database and environment variable settings for each :ref:`configuration variable `. + +* Added the :ref:`file_descriptors` subsection. + +* Moved the :ref:`error_source` and the :ref:`status_codes` sections to the :doc:`errors reference page `. + +* Moved the *Casting type to custom JSON* how-to to the :ref:`casting_range_to_json` subsection. + +* Removed direct links for PostgREST versions older than 8.0 from the versions menu. + +* Removed the deprecated *Embedding table from another schema* how-to. + +Bug fixes +--------- + +* Execute deferred constraint triggers when using ``Prefer: tx=rollback`` (`#2020 `_) + +* Return ``204 No Content`` without ``Content-Type`` for ``PUT`` (`#2058 `_) + +* Fix ``is`` not working with upper or mixed case values like ``NULL, TrUe, FaLsE`` (`#2077 `_) + +* Fix schema cache loading when views with ``XMLTABLE`` and ``DEFAULT`` are present (`#2024 `_) + +* Fix wrong CORS header Authentication -> Authorization (`#1724 `_) + +* Clarify error for failed schema cache load. (`#2107 `_) + + - From ``Database connection lost. Retrying the connection`` to ``Could not query the database for the schema cache. Retrying.`` + +* Fix reading database configuration properly when ``=`` is present in its value (`#2120 `_) + +* Fix silently ignoring filter on a non-existent embedded resource (`#1771 `_) + +* Remove trigger functions from schema cache and OpenAPI output, because they can't be called directly anyway. (`#2135 `_) + +* Remove aggregates, procedures and window functions from the schema cache and OpenAPI output. (`#2101 `_) + +* Remove functions, which are not callable due to unnamed arguments, from schema cache and OpenAPI output. (`#2152 `_) + +* Fix accessing JSON array fields with ``->`` and ``->>`` in ``?select=`` and ``?order=``. (`#2145 `_) + +* Fix ``--dump-schema`` running with a wrong PG version. (`#2153 `_) + +* Keep working when ``EMFILE (Too many open files)`` is reached. (`#2042 `_) + +* Ignore ``Content-Type`` headers for ``GET`` requests when calling RPCs. Previously, ``GET`` without parameters, but with ``Content-Type: text/plain`` or ``Content-Type: application/octet-stream`` would fail with ``404 Not Found``, even if a function without arguments was available. (`#2147 `_) + +Breaking changes +---------------- + +* Return ``204 No Content`` without ``Content-Type`` for RPCs returning ``VOID`` (`#2001 `_) + + - Previously, those RPCs would return ``null`` as a body with ``Content-Type: application/json``. + +Thanks +------ + +Big thanks from the `PostgREST team `_ 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.com/?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 `_ +* `Franz Gusenbauer `_ +* `Daniel Babiak `_ +* 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 `_. diff --git a/postgrest.dict b/postgrest.dict index a20158ba4..f9cc140fc 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -14,6 +14,7 @@ Beles booleans Bouscal buildpack +bugfixes Cardano cd centric