From d59e2498be84b18eed47cf98f27a1ce8abc2c253 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Sun, 28 May 2023 00:01:54 -0500 Subject: [PATCH] add pre-config function --- docs/references/configuration.rst | 55 +++++++++++++++++-------- docs/releases/unreleased.rst | 68 +++++++++++++++++++++++++++++++ postgrest.dict | 1 + 3 files changed, 108 insertions(+), 16 deletions(-) create mode 100644 docs/releases/unreleased.rst diff --git a/docs/references/configuration.rst b/docs/references/configuration.rst index 440ada5d2..a55b5fef3 100644 --- a/docs/references/configuration.rst +++ b/docs/references/configuration.rst @@ -57,36 +57,51 @@ Environment Variables You can also set these :ref:`configuration parameters ` using environment variables. They are capitalized, have a ``PGRST_`` prefix, and use underscores. For example: ``PGRST_DB_URI`` corresponds to ``db-uri`` and ``PGRST_APP_SETTINGS_*`` to ``app.settings.*``. +See the full list of environment variable names on :ref:`config_full_list`. + .. _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`. +Using a :ref:`pre-config ` function, you can configure the server with database settings. For example, you can configure :ref:`db-schemas` and :ref:`jwt-secret` like this: -For example, you can configure :ref:`db-schemas` and :ref:`jwt-secret` like this: +.. code-block:: -.. code:: postgresql + # postgrest.conf - ALTER ROLE authenticator SET pgrst.db_schemas = "tenant1, tenant2, tenant3" - ALTER ROLE authenticator IN DATABASE SET pgrst.jwt_secret = "REALLYREALLYREALLYREALLYVERYSAFE" + db-pre-config = "postgrest.pre_config" -You can use both database-specific settings with `IN DATABASE` and cluster-wide settings without it. Database-specific settings will override cluster-wide settings if both are used for the same parameter. + # or env vars -Note that underscores(``_``) need to be used instead of dashes(``-``) for the in-database config parameters. + PGRST_DB_PRE_CONFIG = "postgrest.pre_config" -.. important:: +.. code-block:: postgresql - 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. + -- create a dedicated schema, hidden from the API + create schema postgrest; + -- grant usage on this schema to the authenticator + grant usage on schema postgrest to authenticator; -When using both the configuration file and the in-database configuration, the latter takes precedence. + -- the function can configure postgREST by using set_config + create or replace function postgrest.pre_config() + returns void as $$ + select + set_config('pgrst.db_schemas', 'schema1, schema2', true) + , set_config('pgrst.db_jwt_secret', 'REALLYREALLYREALLYREALLYVERYSAFE', true); + $$ language sql; -.. danger:: +Note that underscores(``_``) need to be used instead of dashes(``-``) for the in-database config parameters. See the full list of in-database names on :ref:`config_full_list`. - 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. +You can disable the in-database configuration by setting :ref:`db-config` to ``false``. + +.. note:: + For backwards compatibility, you can do in-db config by modifying the :ref:`authenticator role `. This is no longer recommended as it requires SUPERUSER. + + .. code:: postgresql + + ALTER ROLE authenticator SET pgrst.db_schemas = "tenant1, tenant2, tenant3" + ALTER ROLE authenticator IN DATABASE SET pgrst.db_schemas = "tenant4, tenant5" -- database-specific setting, overrides the previous setting .. _config_reloading: @@ -97,7 +112,7 @@ It's possible to reload PostgREST's configuration without restarting the server. - Any modification to the :ref:`file_config` will be applied during reload. - Any modification to the :ref:`in_db_config` will be applied during reload. -- Not all settings are reloadable, the reloadable column on :ref:`config_full_list` specifies which ones are. +- Not all settings are reloadable, see the reloadable list on :ref:`config_full_list`. - It's not possible to change :ref:`env_variables_config` for a running process, hence reloading a Docker container configuration will not work. In these cases, you can restart the process or use :ref:`in_db_config`. .. _config_reloading_signal: @@ -138,6 +153,7 @@ db-anon-role String Y PGRST_DB_ANON_R db-channel String pgrst Y PGRST_DB_CHANNEL db-channel-enabled Boolean True Y PGRST_DB_CHANNEL_ENABLED db-config Boolean True Y PGRST_DB_CONFIG +db-pre-config String Y PGRST_DB_PRE_CONFIG pgrst.db_pre_config db-extra-search-path String public Y PGRST_DB_EXTRA_SEARCH_PATH pgrst.db_extra_search_path db-max-rows Int ∞ Y PGRST_DB_MAX_ROWS pgrst.db_max_rows db-plan-enabled Boolean False Y PGRST_DB_PLAN_ENABLED pgrst.db_plan_enabled @@ -213,6 +229,13 @@ db-config Enables the in-database configuration. +.. _db-pre-config: + +db-pre-config +------------- + + Name of the function that does in-database configuration. + .. _db-extra-search-path: db-extra-search-path diff --git a/docs/releases/unreleased.rst b/docs/releases/unreleased.rst new file mode 100644 index 000000000..8b88fa9ca --- /dev/null +++ b/docs/releases/unreleased.rst @@ -0,0 +1,68 @@ +Unreleased +========== + +Features +-------- + +Configuration +~~~~~~~~~~~~~ + +- New :ref:`in_db_config`. It no longer requires high privileges and can be used on cloud-hosted databases. + +Documentation improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bug fixes +--------- + +Thanks +------ + +Big thanks from the `PostgREST team `_ to our sponsors! + +.. container:: image-container + + .. image:: ../_static/cybertec-new.png + :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest + :width: 13em + + .. image:: ../_static/2ndquadrant.png + :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo + :width: 13em + + .. image:: ../_static/retool.png + :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest + :width: 13em + + .. image:: ../_static/gnuhost.png + :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest + :width: 13em + + .. image:: ../_static/supabase.png + :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage + :width: 13em + + .. image:: ../_static/oblivious.jpg + :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest + :width: 13em + +* `Roboflow `_ +* Evans Fernandes +* Jan Sommer +* `Franz Gusenbauer `_ +* Zac Miller +* Tsingson Qin +* Michel Pelletier +* Jay Hannah +* Robert Stolarz +* Nicholas DiBiase +* Christopher Reid +* Nathan Bouscal +* Daniel Rafaj +* David Fenko +* Remo Rechkemmer +* Severin Ibarluzea +* Tom Saleeba +* Pawel Tyll + +If you like to join them please consider `supporting PostgREST development `_. diff --git a/postgrest.dict b/postgrest.dict index 9f01bfde9..fa04fbd50 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -148,6 +148,7 @@ Rechkemmer reconnection Redux refactor +reloadable Reloadable Remo requester's