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

Reorganize the Schema Cache information into a separate reference page (#404)

Browse Source
This commit is contained in:
laurenceisla
2021-06-18 12:10:31 -05:00
committed by GitHub
parent 326019cca2
commit f7f3aadab8
5 changed files with 143 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admin.rst
+1 -49
View File
@@ -196,58 +196,10 @@ Restart the database and watch the log file in real-time to understand how HTTP
docker run -v "$(pwd)/init.sh":"/docker-entrypoint-initdb.d/init.sh" -d postgres
docker logs -f <container-id>
.. _schema_reloading:
Schema Reloading
----------------
Users are often confused by PostgREST's database schema cache. It is present because detecting foreign key relationships between tables (including how those relationships pass through views) is necessary, but costly. API requests consult the schema cache as part of :ref:`resource_embedding`. However if the schema changes while the server is running it results in a stale cache and leads to errors claiming that no relations are detected between tables.
.. important::
Since v5.0, PostgREST also makes use of the schema cache for stored functions metadata: parameters, return type, volatility.
It also uses the schema cache for resolving overloaded functions. You should refresh the cache if a change in any of the prior is done.
To refresh the cache without restarting the PostgREST server, send the server process a SIGUSR1 signal:
.. code:: bash
killall -SIGUSR1 postgrest
.. note::
To refresh the cache in docker:
.. code:: bash
docker kill -s SIGUSR1 <container>
# or in docker-compose
docker-compose kill -s SIGUSR1 <service>
The above is the manual way to do it. To automate the schema reloads, use a database trigger like this:
.. code-block:: postgresql
CREATE OR REPLACE FUNCTION public.notify_ddl_postgrest()
RETURNS event_trigger
LANGUAGE plpgsql
AS $$
BEGIN
NOTIFY ddl_command_end;
END;
$$;
CREATE EVENT TRIGGER ddl_postgrest ON ddl_command_end
EXECUTE PROCEDURE public.notify_ddl_postgrest();
Then run the `pg_listen <https://github.com/begriffs/pg_listen>`_ utility to monitor for that event and send a SIGUSR1 when it occurs:
.. code-block:: bash
pg_listen <db-uri> ddl_command_end $(which killall) -SIGUSR1 postgrest
Now, whenever the structure of the database schema changes, PostgreSQL will notify the ``ddl_command_end`` channel, which will cause ``pg_listen`` to send PostgREST the signal to reload its cache. Note that pg_listen requires full path to the executable in the example above.
Changing the schema while the server is running can lead to errors due to a stale schema cache. To learn how to refresh the cache see :ref:`schema_reloading`.
Daemonizing
===========