From 42656edfd9af94a9f2391dba61a743fe8e36c4cf Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Mon, 9 Aug 2021 14:04:47 -0500 Subject: [PATCH] Improve wording in some sections --- api.rst | 9 +++++---- configuration.rst | 4 ++-- index.rst | 2 +- releases/v8.0.0.rst | 2 +- schema_cache.rst | 28 ++++++++++++---------------- 5 files changed, 21 insertions(+), 24 deletions(-) diff --git a/api.rst b/api.rst index 246d17a20..ecc34487b 100644 --- a/api.rst +++ b/api.rst @@ -1459,7 +1459,7 @@ OPTIONS You can verify which HTTP methods are allowed on endpoints for tables and views by using an OPTIONS request. These methods are allowed depending on what operations *can* be done on the table or view, not on the database permissions assigned to them. -For example, the OPTIONS request and response for a table named ``people`` are: +For a table named ``people``, OPTIONS would show: .. code-block:: http @@ -1470,7 +1470,7 @@ For example, the OPTIONS request and response for a table named ``people`` are: HTTP/1.1 200 OK Allow: OPTIONS,GET,HEAD,POST,PUT,PATCH,DELETE -For a view, the methods are determined by the presence of INSTEAD OF TRIGGERS: +For a view, the methods are determined by the presence of INSTEAD OF TRIGGERS. .. table:: :widths: auto @@ -1493,9 +1493,10 @@ For a view, the methods are determined by the presence of INSTEAD OF TRIGGERS: | `auto-updatable views `_ | +--------------------+-------------------------------------------------------------------------------------------------+ -For database function endpoints, OPTIONS requests are not supported. +For functions, OPTIONS requests are not supported. .. important:: + Whenever you add or remove tables or views, or modify a view's INSTEAD OF TRIGGERS on the database, you must refresh PostgREST's schema cache for OPTIONS requests to work properly. See the section :ref:`schema_reloading`. CORS @@ -1583,7 +1584,7 @@ PostgREST reads the ``response.headers`` SQL variable to add extra headers to th SELECT set_config('response.headers', '[{"Cache-Control": "public"}, {"Cache-Control": "max-age=259200"}]', true); - + Notice that the variable should be set to an *array* of single-key objects rather than a single multiple-key object. This is because headers such as ``Cache-Control`` or ``Set-Cookie`` need to be repeated when setting multiple values and an object would not allow the repeated key. .. note:: diff --git a/configuration.rst b/configuration.rst index d70869d5a..b758b1265 100644 --- a/configuration.rst +++ b/configuration.rst @@ -391,13 +391,13 @@ raw-media-types Configuration Reloading ======================= -To reload the configuration without restarting the PostgREST server send a SIGUSR2 signal to the server process. +To reload the configuration without restarting the PostgREST server, send a SIGUSR2 signal to the server process. .. code:: bash killall -SIGUSR2 postgrest -To refresh the cache in docker: +To reload the config in docker: .. code:: bash diff --git a/index.rst b/index.rst index af28331db..8b2033ea1 100644 --- a/index.rst +++ b/index.rst @@ -234,7 +234,7 @@ Here are some companies that use PostgREST in production. * `Catarse `_ * `Datrium `_ * `Drip Depot `_ -* `eGull `_ +* `eGull `_ * `Image-charts `_ * `Moat `_ * `MotionDynamic - Fast highly dynamic video generation at scale `_ diff --git a/releases/v8.0.0.rst b/releases/v8.0.0.rst index 55c5ad373..b79098df1 100644 --- a/releases/v8.0.0.rst +++ b/releases/v8.0.0.rst @@ -22,7 +22,7 @@ Added * No downtime when reloading the schema cache. See the note in :ref:`schema_reloading`. |br| -- `@steve-chavez `_ -* Allow schema cache reloading using PostgreSQL :ref:`NOTIFY ` command. +* Allow schema cache reloading using PostgreSQL :ref:`NOTIFY ` command. This enables :ref:`auto_schema_reloading`. |br| -- `@steve-chavez `_ * Allow sending the header ``Prefer: headers-only`` to get a response with a ``Location`` header. See :ref:`insert_update`. diff --git a/schema_cache.rst b/schema_cache.rst index 04c8c84bf..e4c265703 100644 --- a/schema_cache.rst +++ b/schema_cache.rst @@ -6,8 +6,6 @@ Schema Cache Certain PostgREST features require metadata from the database schema. Getting this metadata requires executing expensive queries, so in order to avoid repeating this work, PostgREST uses a schema cache. -The following features are the ones that require metadata from the schema cache. - +--------------------------------------------+-------------------------------------------------------------------------------+ | Feature | Required Metadata | +============================================+===============================================================================+ @@ -34,18 +32,18 @@ The Stale Schema Cache When you make changes on the metadata mentioned above, the schema cache will turn stale on a running PostgREST. Future requests that use the above features will need the :ref:`schema cache to be reloaded `; otherwise, you'll get an error instead of the expected result. -For instance, let's see what would happen if you have a stale schema for foreign key relationships and function signature: +For instance, let's see what would happen if you have a stale schema cache for foreign key relationships and function signatures. Stale Foreign Key Relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Suppose you add a ``cities`` table to your database. This table has a foreign key referencing an existing ``countries`` table. Then, you make a request to get the ``cities`` and their belonging ``countries``: +Suppose you add a ``cities`` table to your database and define a foreign key that references an existing ``countries`` table. Then, you make a request to get the ``cities`` and their belonging ``countries``. .. code-block:: http GET /cities?select=name,country:countries(id,name) HTTP/1.1 -But instead, you get an error message that looks like this: +The result will be an error: .. code-block:: json @@ -54,14 +52,14 @@ But instead, you get an error message that looks like this: "message": "Could not find a relationship between cities and countries in the schema cache" } -As you can see, PostgREST couldn't find the newly created foreign key in the schema cache. See the section :ref:`schema_reloading` to solve this issue. +As you can see, PostgREST couldn't find the newly created foreign key in the schema cache. See :ref:`schema_reloading` and :ref:`auto_schema_reloading` to solve this issue. .. _stale_function_signature: Stale Function Signature ~~~~~~~~~~~~~~~~~~~~~~~~ -Suppose you create the following function while PostgREST is running: +The same issue will occur on newly created functions on a running PostgREST. .. code-block:: plpgsql @@ -70,14 +68,10 @@ Suppose you create the following function while PostgREST is running: SELECT num + 1; $$ LANGUAGE SQL IMMUTABLE; -Then, you make this request: - .. code-block:: http GET /rpc/plus_one?num=1 HTTP/1.1 -Next, PostgREST tries to find the function on the stale schema to no avail: - .. code-block:: json { @@ -85,7 +79,7 @@ Next, PostgREST tries to find the function on the stale schema to no avail: "message": "Could not find the api.plus_one(num) function in the schema cache" } -See the section :ref:`schema_reloading` to solve this issue. +Here, PostgREST tries to find the function on the stale schema to no avail. See :ref:`schema_reloading` and :ref:`auto_schema_reloading` to solve this issue. .. _schema_reloading: @@ -125,10 +119,12 @@ There are environments where you can't send the SIGUSR1 Unix Signal (like on man The ``"pgrst"`` notification channel is enabled by default. For configuring the channel, see :ref:`db-channel` and :ref:`db-channel-enabled`. -Automatic schema cache reloading -******************************** +.. _auto_schema_reloading: -You can do automatic schema cache reloading in a pure SQL way with an `event trigger `_ and ``NOTIFY``. +Automatic Schema Cache Reloading +-------------------------------- + +You can do automatic schema cache reloading in a pure SQL way and forget about stale schema cache errors with an `event trigger `_ and ``NOTIFY``. .. code-block:: postgresql @@ -137,7 +133,7 @@ You can do automatic schema cache reloading in a pure SQL way with an `event tri LANGUAGE plpgsql AS $$ BEGIN - NOTIFY pgrst; + NOTIFY pgrst, 'reload schema'; END; $$;