From 254a2f7f36efd687561593773d06b00c34d14e2e Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Mon, 26 Jul 2021 04:39:02 -0500
Subject: [PATCH] Add in-db config plus reloading

---
 configuration.rst     | 63 ++++++++++++++++++++++++++++++++++++++-----
 releases/upcoming.rst |  3 +++
 schema_cache.rst      |  2 +-
 3 files changed, 60 insertions(+), 8 deletions(-)

diff --git a/configuration.rst b/configuration.rst
index c7355f0fb..d70869d5a 100644
--- a/configuration.rst
+++ b/configuration.rst
@@ -47,6 +47,7 @@ db-channel               String  pgrst
 db-channel-enabled       Boolean True
 db-prepared-statements   Boolean True
 db-tx-end                String  commit
+db-config                Boolean True
 server-host              String  !4
 server-port              Int     3000
 server-unix-socket       String
@@ -191,6 +192,13 @@ db-tx-end
     # The transaction is rolled back unless a "Prefer: tx=commit" header is sent
     db-tx-end = "rollback-allow-override"
 
+.. _db-config:
+
+db-config
+---------
+
+   Enables the in-database configuration.
+
 .. _server-host:
 
 server-host
@@ -402,11 +410,52 @@ To refresh the cache in docker:
 
   The following settings will not be reread when reloading the configuration. You will need to restart PostgREST in that case.
 
-    * ``db-uri``
-    * ``db-pool``
-    * ``db-pool-timeout``
-    * ``server-host``
-    * ``server-port``
-    * ``server-unix-socket``
-    * ``server-unix-socket-mode``
+    * :ref:`db-uri`
+    * :ref:`db-pool`
+    * :ref:`db-pool-timeout`
+    * :ref:`server-host`
+    * :ref:`server-port`
+    * :ref:`server-unix-socket`
+    * :ref:`server-unix-socket-mode`
 
+.. _in_db_config:
+
+In-Database Configuration
+=========================
+
+By adding settings to the **authenticator** role (see :ref:`roles`), you can make the database the single source of truth for PostgREST's configuration.
+This is enabled by :ref:`db-config`.
+
+For example, you can configure :ref:`db-schema` and :ref:`jwt-secret` like this:
+
+.. code:: postgresql
+
+   ALTER ROLE authenticator SET pgrst.db_schema = "tenant1, tenant2, tenant3"
+   ALTER ROLE authenticator SET pgrst.jwt_secret = "REALLYREALLYREALLYREALLYVERYSAFE"
+
+.. important::
+
+   For altering a role in this way, you need a SUPERUSER. You might not be able to use this configuration mode on cloud-hosted databases.
+
+Note that underscores(``_``) need to be used instead of dashes(``-``) for the options when the configuration is inside the database.
+
+When using both the configuration file and the in-database configuration, the latter takes precedence.
+
+.. danger::
+
+  If direct connections to the database are allowed, then it's not safe to use the in-db configuration for storing the :ref:`jwt-secret`.
+  The settings of every role are PUBLIC - they can be viewed by any user that queries the ``pg_catalog.pg_db_role_setting`` table.
+  In this case you should keep the :ref:`jwt-secret` in the configuration file or as environment variables.
+
+.. _in_db_config_reloading:
+
+In-database configuration reloading
+-----------------------------------
+
+To reload the in-database configuration from within the database, you can use a NOTIFY command.
+
+.. code:: postgresql
+
+   NOTIFY pgrst, 'reload config'
+
+The ``"pgrst"`` notification channel is enabled by default. For configuring the channel, see :ref:`db-channel` and :ref:`db-channel-enabled`.
diff --git a/releases/upcoming.rst b/releases/upcoming.rst
index fde6b391d..81f8bbe88 100644
--- a/releases/upcoming.rst
+++ b/releases/upcoming.rst
@@ -37,6 +37,9 @@ Added
 * Allow ``Bearer`` with and without capitalization as authentication schema. See :ref:`client_auth`.
   |br| -- `@wolfgangwalther <https://github.com/wolfgangwalther>`_
 
+* :ref:`in_db_config` that can be :ref:`reloaded with NOTIFY <in_db_config_reloading>`.
+  |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
+
 * Allow OPTIONS to generate HTTP methods based on views triggers. See :ref:`OPTIONS requests <options_requests>`.
   |br| -- `@laurenceisla <https://github.com/laurenceisla>`_
 
diff --git a/schema_cache.rst b/schema_cache.rst
index e03359a8c..04c8c84bf 100644
--- a/schema_cache.rst
+++ b/schema_cache.rst
@@ -92,7 +92,7 @@ See the section :ref:`schema_reloading` to solve this issue.
 Schema Cache Reloading
 ----------------------
 
-To refresh the cache without restarting the PostgREST server, send a SIGUSR1 signal to the server process.
+To reload the cache without restarting the PostgREST server, send a SIGUSR1 signal to the server process.
 
 .. code:: bash