Improve wording in some sections

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 <https://www.postgresql.org/docs/current/sql-createview.html#SQL-CREATEVIEW-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::

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
 

index.rst

@@ -234,7 +234,7 @@ Here are some companies that use PostgREST in production.
 * `Catarse <https://www.catarse.me>`_
 * `Datrium <https://www.datrium.com>`_
 * `Drip Depot <https://www.dripdepot.com>`_
-* `eGull <https://www.egull.co>`_
+* `eGull <http://www.egull.co>`_
 * `Image-charts <https://www.image-charts.com>`_
 * `Moat <https://moat.com>`_
 * `MotionDynamic - Fast highly dynamic video generation at scale <https://motiondynamic.tech>`_

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 <https://github.com/steve-chavez>`_
 
-* Allow schema cache reloading using PostgreSQL :ref:`NOTIFY <schema_reloading_notify>` command.
+* Allow schema cache reloading using PostgreSQL :ref:`NOTIFY <schema_reloading_notify>` command. This enables :ref:`auto_schema_reloading`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
 
 * Allow sending the header ``Prefer: headers-only`` to get a response with a ``Location`` header. See :ref:`insert_update`.

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 <schema_reloading>`; 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 <https://www.postgresql.org/docs/current/event-trigger-definition.html>`_ 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 <https://www.postgresql.org/docs/current/event-trigger-definition.html>`_ 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;
   $$;