From 49bc82bfcaed2167d7e7aaa72623fd7d397cc83a Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Thu, 13 Aug 2020 17:29:32 +0200 Subject: [PATCH] Clarify function volatility and location header (#339) * clarify location header only available with PK * clarify function volatility and GET/POST * improve stable/immutable for post and get * add 405 for read only transaction error --- api.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/api.rst b/api.rst index 199951721..6fd9c4ff9 100644 --- a/api.rst +++ b/api.rst @@ -882,7 +882,7 @@ To create a row in a database table post a JSON object whose keys are the names { "col1": "value1", "col2": "value2" } -The response will include a :code:`Location` header describing where to find the new object. If the table is write-only then constructing the Location header will cause a permissions error. To successfully insert an item to a write-only table you will need to suppress the Location response header by including the request header :code:`Prefer: return=minimal`. +If the table has a primary key, the response will include a :code:`Location` header describing where to find the new object. If the table is write-only then constructing the Location header will cause a permissions error. To successfully insert an item to a write-only table you will need to suppress the Location response header by including the request header :code:`Prefer: return=minimal`. On the other end of the spectrum you can get the full created object back in the response to your request by including the header :code:`Prefer: return=representation`. That way you won't have to make another HTTP call to discover properties that may have been filled in on the server side. You can also apply the standard :ref:`v_filter` to these results. @@ -1148,13 +1148,15 @@ PostgreSQL has four procedural languages that are part of the core distribution: Immutable and stable functions ------------------------------ -Procedures in PostgreSQL marked with :code:`stable` or :code:`immutable` `volatility `_ can only read, not modify, the database and PostgREST executes them in a read-only transaction compatible for read-replicas. Stable and immutable functions can be called with the HTTP GET verb if desired. +PostgREST executes POST requests in a read/write transaction except for functions marked as ``IMMUTABLE`` or ``STABLE``. Those must not modify the database and are executed in a read-only transaction compatible for read-replicas. + +Procedures that do not modify the database can be called with the HTTP GET verb as well, if desired. PostgREST executes all GET requests in a read-only transaction. Modifying the database inside read-only transactions is not possible and calling volatile functions with GET will fail. .. note:: - The volatility marker is a promise about the behavior of the function. PostgreSQL will let you mark a function that modifies the database as ``immutable/stable`` without failure. However the function will fail when called through PostgREST since it executes it in a read-only transaction. + The `volatility marker `_ is a promise about the behavior of the function. PostgreSQL will let you mark a function that modifies the database as ``IMMUTABLE`` or ``STABLE`` without failure. However, because of the read-only transaction this would still fail with PostgREST. -Because ``add_them`` was declared IMMUTABLE, we can alternately call the function with a GET request: +Because ``add_them`` is ``IMMUTABLE``, we can alternately call the function with a GET request: .. code-block:: http @@ -1227,6 +1229,8 @@ as in ``{1,2,3,4}``. Note that the curly brackets have to be urlencoded(``{`` is In these versions we recommend using function parameters of type json to accept arrays from the client. +.. _s_procs_variadic: + Scalar functions ---------------- @@ -1635,6 +1639,8 @@ PostgREST translates `PostgreSQL error codes