docs: update schema cache

docs/references/errors.rst

@@ -259,7 +259,7 @@ Related to the HTTP request elements.
 Group 2 - Schema Cache
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Related to a :ref:`stale schema cache <stale_schema>`. Most of the time, these errors are solved by :ref:`reloading the schema cache <schema_reloading>`.
+Related to a :ref:`schema_cache`. Most of the time, these errors are solved by :ref:`schema_reloading`.
 
 +---------------+-------------+-------------------------------------------------------------+
 | Code          | HTTP status | Description                                                 |

docs/references/schema_cache.rst

@@ -3,46 +3,29 @@
 Schema Cache
 ============
 
-Some PostgREST features need metadata from the database schema. Getting this metadata requires expensive queries. To avoid repeating this work, PostgREST uses a schema cache.
-
-+--------------------------------------------+-------------------------------------------------------------------------------+
-| Feature                                    | Required Metadata                                                             |
-+============================================+===============================================================================+
-| :ref:`resource_embedding`                  | Foreign key constraints                                                       |
-+--------------------------------------------+-------------------------------------------------------------------------------+
-| :ref:`Functions <functions>`               | Function signature (parameters, return type, volatility and                   |
-|                                            | `overloading <https://www.postgresql.org/docs/current/xfunc-overload.html>`_) |
-+--------------------------------------------+-------------------------------------------------------------------------------+
-| :ref:`Upserts <upsert>`                    | Primary keys                                                                  |
-+--------------------------------------------+-------------------------------------------------------------------------------+
-| :ref:`Insertions <insert>`                 | Primary keys (optional: only if the Location header is requested)             |
-+--------------------------------------------+-------------------------------------------------------------------------------+
-| :ref:`OPTIONS requests <options_requests>` | View INSTEAD OF TRIGGERS and primary keys                                     |
-+--------------------------------------------+-------------------------------------------------------------------------------+
-| :ref:`open-api`                            | Table columns, primary keys and foreign keys                                  |
-+                                            +-------------------------------------------------------------------------------+
-|                                            | View columns and INSTEAD OF TRIGGERS                                          |
-+                                            +-------------------------------------------------------------------------------+
-|                                            | Function signature                                                            |
-+--------------------------------------------+-------------------------------------------------------------------------------+
-
-.. _stale_schema:
-
-Stale Schema Cache
-------------------
-
-One operational problem that comes with a cache is that it can go stale. This can happen for PostgREST when you make changes to the metadata before mentioned. Requests that depend on the metadata will fail.
-
-You can solve this by reloading the cache manually or automatically.
+PostgREST requires metadata from the database schema to provide a REST API that abstracts SQL details. One example of this is the interface for :ref:`resource_embedding`.
 
-.. note::
-  If you are using :ref:`in_db_config`, a schema reload will always :ref:`reload the configuration<config_reloading>` as well.
+Getting this metadata requires expensive queries. To avoid repeating this work, PostgREST uses a schema cache.
 
 .. _schema_reloading:
 
 Schema Cache Reloading
 ----------------------
 
+To not let the schema cache go stale (happens when you make changes to the database), you need to reload it.
+
+You can do this with UNIX signals or with PostgreSQL notifications. It's also possible to do this automatically using `event triggers <https://www.postgresql.org/docs/current/event-trigger-definition.html>`_.
+
+.. note::
+
+  - If you are using the :ref:`in_db_config`, a schema cache reload will :ref:`reload the configuration<config_reloading>` as well.
+  - There’s no downtime when reloading the schema cache. The reloading will happen on a background thread while serving requests.
+
+.. _schema_reloading_signals:
+
+Schema Cache Reloading with Unix Signals
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 To manually reload the cache without restarting the PostgREST server, send a SIGUSR1 signal to the server process.
 
 .. code:: bash
@@ -59,8 +42,6 @@ For docker you can do:
   # or in docker-compose
   docker-compose kill -s SIGUSR1 <service>
 
-There’s no downtime when reloading the schema cache. The reloading will happen on a background thread while serving requests.
-
 .. _schema_reloading_notify:
 
 Schema Cache Reloading with NOTIFY
@@ -81,7 +62,7 @@ The ``pgrst`` notification channel is enabled by default. For configuring the ch
 Automatic Schema Cache Reloading
 --------------------------------
 
-You can do automatic schema cache reloading in a pure SQL way and forget about stale schema cache errors. For this use an `event trigger <https://www.postgresql.org/docs/current/event-trigger-definition.html>`_ and ``NOTIFY``.
+You can do automatic reloading and forget there is a schema cache. For this use an `event trigger <https://www.postgresql.org/docs/current/event-trigger-definition.html>`_ and ``NOTIFY``.
 
 .. code-block:: postgres