jimmy/postgrest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update schema cache

Browse Source
This commit is contained in:
steve-chavez
2024-04-01 19:03:14 -05:00
committed by Steve Chavez
parent 2543b8d724
commit d7c64a93f8
2 changed files with 18 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/references/errors.rst
+1 -1
View File
@@ -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
+17 -36
View File
@@ -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.
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`.
+--------------------------------------------+-------------------------------------------------------------------------------+
| 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.
.. 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