From d7c64a93f8ec2ce4cb3ee25617327fc89e30f0ac Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Mon, 1 Apr 2024 12:53:22 -0500 Subject: [PATCH] docs: update schema cache --- docs/references/errors.rst | 2 +- docs/references/schema_cache.rst | 53 ++++++++++---------------------- 2 files changed, 18 insertions(+), 37 deletions(-) diff --git a/docs/references/errors.rst b/docs/references/errors.rst index 047fec7f76..bb05a9dfab 100644 --- a/docs/references/errors.rst +++ b/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 `. Most of the time, these errors are solved by :ref:`reloading the schema cache `. +Related to a :ref:`schema_cache`. Most of the time, these errors are solved by :ref:`schema_reloading`. +---------------+-------------+-------------------------------------------------------------+ | Code | HTTP status | Description | diff --git a/docs/references/schema_cache.rst b/docs/references/schema_cache.rst index 27b4e94ca3..a46c06c10b 100644 --- a/docs/references/schema_cache.rst +++ b/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 ` | Function signature (parameters, return type, volatility and | -| | `overloading `_) | -+--------------------------------------------+-------------------------------------------------------------------------------+ -| :ref:`Upserts ` | Primary keys | -+--------------------------------------------+-------------------------------------------------------------------------------+ -| :ref:`Insertions ` | Primary keys (optional: only if the Location header is requested) | -+--------------------------------------------+-------------------------------------------------------------------------------+ -| :ref:`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` 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 `_. + +.. note:: + + - If you are using the :ref:`in_db_config`, a schema cache reload will :ref:`reload the configuration` 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 -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 `_ and ``NOTIFY``. +You can do automatic reloading and forget there is a schema cache. For this use an `event trigger `_ and ``NOTIFY``. .. code-block:: postgres