docs: Add an example for PGRST_APP_SETTINGS_* #3804
Conversation
I had to figure stuff out and I thought it would be useful for everyone if I provided some more information
docs/references/configuration.rst
Outdated
| @@ -191,6 +191,10 @@ app.settings.* | |||
|
|
|||
| Arbitrary settings that can be used to pass in secret keys directly as strings, or via OS environment variables. For instance: :code:`app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)"` will take :code:`MYAPP_JWT_SECRET` from the environment and make it available to PostgreSQL functions as :code:`current_setting('app.settings.jwt_secret')`. | |||
|
|
|||
| When using the environment variable `PGRST_APP_SETTINGS_*` form, the remainder of the variable is used as the new name. Case is not important : :code:`PGRST_APP_SETTINGS_MY_ENV_VARIABLE=some_value` can be accessed in postgres as :code:`current_setting('app.settings.my_env_variable')`. | |||
|
|
|||
| The :code:`current_setting` function has `an optional boolean second <https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SET>`_ argument to avoid it from raising an error if the value was not defined. Default values to :code:`app.settings` can then easily be given by combining this argument with :code:`coalesce` : :code:`coalesce(current_setting('app.settings.my_custom_variable', true), 'default value')` | |||
There was a problem hiding this comment.
This doesn't always work. This is because GUCs have the strange effect that they are reset to an empty string in further transactions. This means coalesce(...) will work on the first request, but then maybe not later anymore.
You'd need something like this instead:
coalesce(nullif(current_setting('app.settings.my_custom_variable', true), ''), 'default value')Additionally, I think this piece of advice is important for all other things that can be read via current_setting(...)... ah right, we already have a hint about that here: https://docs.postgrest.org/en/v12/references/transactions.html#request-headers-cookies-and-jwt-claims
So maybe don't talk specifically about current_setting here but link to the transactions page by saying "current_setting can be used with those app settings similar to how you can use it over there"?
There was a problem hiding this comment.
This part is quite important. I think we need to bring more attention to it. It occurs to me that we need to split the Transactions page and have a dedicated one on "Transaction-scoped settings" (maybe we should rename this as "Transactional settings" or "Transactional variables") and then have this note at the top-level.
|
@wolfgangwalther : I added a reference to the section you mentioned and edited the example to add I believe that the example should stay : the motivation of this (very simple) PR was precisely to give the reader what I think the way they'll want to use it anyway. I did spend a good 30 minutes to 1 hour toying with the feature to "guess" how it worked, and even then I had no knowledge that the GUC was not reset in transactions - for which I thank you. |
docs/references/configuration.rst
Outdated
| @@ -191,6 +191,10 @@ app.settings.* | |||
|
|
|||
| Arbitrary settings that can be used to pass in secret keys directly as strings, or via OS environment variables. For instance: :code:`app.settings.jwt_secret = "$(MYAPP_JWT_SECRET)"` will take :code:`MYAPP_JWT_SECRET` from the environment and make it available to PostgreSQL functions as :code:`current_setting('app.settings.jwt_secret')`. | |||
|
|
|||
| When using the environment variable `PGRST_APP_SETTINGS_*` form, the remainder of the variable is used as the new name. Case is not important : :code:`PGRST_APP_SETTINGS_MY_ENV_VARIABLE=some_value` can be accessed in postgres as :code:`current_setting('app.settings.my_env_variable')`. | |||
|
|
|||
| The :code:`current_setting` function has `an optional boolean second <https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SET>`_ argument to avoid it from raising an error if the value was not defined. Default values to :code:`app.settings` can then easily be given by combining this argument with :code:`coalesce` and :code:`nullif` : :code:`coalesce(nullif(current_setting('app.settings.my_custom_variable', true), ''), 'default value')`. The use of :code:`nullif` is necessary because if set in a transaction, the setting is sometimes not "rolled back" to :code:`null`. See also :ref:`this section <guc_req_headers_cookies_claims>` for more information on this behaviour. | |||
There was a problem hiding this comment.
I suggest to remove "easily" (related).
| The :code:`current_setting` function has `an optional boolean second <https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SET>`_ argument to avoid it from raising an error if the value was not defined. Default values to :code:`app.settings` can then easily be given by combining this argument with :code:`coalesce` and :code:`nullif` : :code:`coalesce(nullif(current_setting('app.settings.my_custom_variable', true), ''), 'default value')`. The use of :code:`nullif` is necessary because if set in a transaction, the setting is sometimes not "rolled back" to :code:`null`. See also :ref:`this section <guc_req_headers_cookies_claims>` for more information on this behaviour. | |
| The :code:`current_setting` function has `an optional boolean second <https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-SET>`_ argument to avoid it from raising an error if the value was not defined. Default values to :code:`app.settings` can then be given by combining this argument with :code:`coalesce` and :code:`nullif` : :code:`coalesce(nullif(current_setting('app.settings.my_custom_variable', true), ''), 'default value')`. The use of :code:`nullif` is necessary because if set in a transaction, the setting is sometimes not "rolled back" to :code:`null`. See also :ref:`this section <guc_req_headers_cookies_claims>` for more information on this behaviour. |
There was a problem hiding this comment.
I'm sorry I did another commit to remove easily, I'm not very familiar with github's capabilities
There was a problem hiding this comment.
No problem, I can just squash the commits. Nice work!
I had to figure stuff out and I thought it would be useful for everyone if I provided some more information