From 8ee2310ca321c9a2ec9a2de397ad512cc8835e06 Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Fri, 7 Jan 2022 20:17:18 +0100 Subject: [PATCH] Update configuration page --- admin.rst | 2 +- api.rst | 14 +- auth.rst | 6 +- configuration.rst | 579 +++++++++++------- .../embedding-table-from-another-schema.rst | 2 +- postgrest.dict | 1 + releases/v7.0.0.rst | 2 +- tutorials/tut0.rst | 2 +- tutorials/tut1.rst | 2 +- 9 files changed, 377 insertions(+), 233 deletions(-) diff --git a/admin.rst b/admin.rst index 054a31a39..6f906363f 100644 --- a/admin.rst +++ b/admin.rst @@ -266,7 +266,7 @@ First, create postgrest configuration in ``/etc/postgrest/config`` .. code-block:: ini db-uri = "postgres://:@localhost:5432/" - db-schema = "" + db-schemas = "" db-anon-role = "" db-pool = 10 diff --git a/api.rst b/api.rst index f5d5f796d..2e39e0178 100644 --- a/api.rst +++ b/api.rst @@ -396,7 +396,7 @@ As mentioned, computed columns do not appear in the output by default. However y .. important:: - Computed columns must be created under the :ref:`exposed schema ` to be used in this way. + Computed columns must be created under the :ref:`exposed schema ` to be used in this way. Unicode support --------------- @@ -666,9 +666,9 @@ In general, when having smaller row-counts, the estimated count should be as clo To help with these cases, PostgREST can get the exact count up until a threshold and get the planned count when that threshold is surpassed. To use this behavior, you can specify the ``Prefer: count=estimated`` header. The **threshold** is -defined by :ref:`max-rows`. +defined by :ref:`db-max-rows`. -Here's an example. Suppose we set ``max-rows=1000`` and ``smalltable`` has 321 rows, then we'll get the exact count: +Here's an example. Suppose we set ``db-max-rows=1000`` and ``smalltable`` has 321 rows, then we'll get the exact count: .. tabs:: @@ -1156,7 +1156,7 @@ It's also possible to embed `Materialized Views ` 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.*``. + +.. _config_reloading: + +Configuration Reloading +======================= + +To reload the configuration without restarting the PostgREST server, send a SIGUSR2 signal to the server process. + +.. code:: bash + + killall -SIGUSR2 postgrest + +This method does not reload :ref:`env_variables_config` and it will not work for reloading a Docker container configuration. In these cases, you need to restart the PostgREST server or use the :ref:`in_db_config` as an alternative. + +.. important:: + + The following settings will not be reread when reloading the configuration. You will need to restart PostgREST in that case. + + * :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-schemas` and :ref:`jwt-secret` like this: + +.. code:: postgresql + + ALTER ROLE authenticator IN DATABASE SET pgrst.db_schemas = "tenant1, tenant2, tenant3" + ALTER ROLE authenticator IN DATABASE SET pgrst.jwt_secret = "REALLYREALLYREALLYREALLYVERYSAFE" + +Note that underscores(``_``) need to be used instead of dashes(``-``) for the in-database config parameters. + +.. 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. + +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`. + +.. _config_full_list: + +List of parameters +================== + +======================== ======= ================= ======== ========== +Name Type Default Required Reloadable +======================== ======= ================= ======== ========== +app.settings.* String Y +db-anon-role String Y Y +db-channel String pgrst Y +db-channel-enabled Boolean True Y +db-config Boolean True Y +db-extra-search-path String public Y +db-max-rows Int ∞ Y db-pool Int 10 db-pool-timeout Int 10 -db-extra-search-path String public -db-channel String pgrst -db-channel-enabled Boolean True -db-prepared-statements Boolean True -db-tx-end String commit -db-config Boolean True -db-use-legacy-gucs Boolean True +db-pre-request String Y +db-prepared-statements Boolean True Y +db-schemas String Y Y +db-tx-end String commit Y +db-uri String Y +db-use-legacy-gucs Boolean True Y +jwt-aud String Y +jwt-role-claim-key String .role Y +jwt-secret String Y +jwt-secret-is-base64 Boolean False Y +log-level String error Y +openapi-mode String follow-privileges Y +openapi-server-proxy-uri String Y +raw-media-types String Y server-host String !4 server-port Int 3000 server-unix-socket String server-unix-socket-mode String 660 -log-level String error -openapi-mode String follow-privileges -openapi-server-proxy-uri String -jwt-secret String -jwt-aud String -secret-is-base64 Boolean False -max-rows Int ∞ -pre-request String -app.settings.* String -role-claim-key String .role -raw-media-types String -======================== ======= ================= ======== +======================== ======= ================= ======== ========== -.. _db-uri: +.. _app.settings.*: -db-uri ------- +app.settings.* +-------------- - The standard connection PostgreSQL `URI format `_. Symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error. If enforcing an SSL connection to the database is required you can use `sslmode `_ in the URI, for example ``postgres://user:pass@host:5432/dbname?sslmode=require``. + =============== ==================== + **Environment** PGRST_APP_SETTINGS_* + **In-Database** pgrst.app_settings_* + =============== ==================== - When running PostgREST on the same machine as PostgreSQL, it is also possible to connect to the database using a `Unix socket `_ and the `Peer Authentication method `_ as an alternative to TCP/IP communication and authentication with a password, this also grants higher performance. To do this you can omit the host and the password, e.g. ``postgres://user@/dbname``, see the `libpq connection string `_ documentation for more details. + 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')`. - On older systems like Centos 6, with older versions of libpq, a different db-uri syntax has to be used. In this case the URI is a string of space separated key-value pairs (key=value), so the example above would be :code:`"host=host user=user port=5432 dbname=dbname password=pass"`. +.. _db-anon-role: - Choosing a value for this parameter beginning with the at sign such as ``@filename`` (e.g. ``@./configs/my-config``) loads the secret out of an external file. +db-anon-role +------------ + =============== ================== + **Environment** PGRST_DB_ANON_ROLE + **In-Database** `n/a` + =============== ================== -.. _db-schema: + The database role to use when executing commands on behalf of unauthenticated clients. For more information, see :ref:`roles`. -db-schema ---------- +.. _db-channel: - The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints. +db-channel +---------- - .. code:: bash + =============== ================ + **Environment** PGRST_DB_CHANNEL + **In-Database** `n/a` + =============== ================ - db-schema = "api" + The name of the notification channel that PostgREST uses for :ref:`schema_reloading` and configuration reloading. - This schema gets added to the `search_path `_ of every request. +.. _db-channel-enabled: -List of schemas -~~~~~~~~~~~~~~~ +db-channel-enabled +------------------ - You can also specify a list of schemas that can be used for **schema-based multitenancy** and **api versioning** by :ref:`multiple-schemas`. Example: + =============== ======================== + **Environment** PGRST_DB_CHANNEL_ENABLED + **In-Database** `n/a` + =============== ======================== - .. code:: bash + When this is set to :code:`true`, the notification channel specified in :ref:`db-channel` is enabled. - db-schema = "tenant1, tenant2" + You should set this to ``false`` when using PostgresSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section ` for more information. - If you don't :ref:`Switch Schemas `, the first schema in the list(``tenant1`` in this case) is chosen as the default schema. +.. _db-config: - *Only the chosen schema* gets added to the `search_path `_ of every request. +db-config +--------- - .. warning:: + =============== =============== + **Environment** PGRST_DB_CONFIG + **In-Database** `n/a` + =============== =============== - Never expose private schemas in this way. See :ref:`schema_isolation`. + Enables the in-database configuration. -.. _db-anon-role: +.. _db-extra-search-path: -db-anon-role ------------- +db-extra-search-path +-------------------- - The database role to use when executing commands on behalf of unauthenticated clients. For more information, see :ref:`roles`. + =============== ========================== + **Environment** PGRST_DB_EXTRA_SEARCH_PATH + **In-Database** pgrst.db_extra_search_path + =============== ========================== + + Extra schemas to add to the `search_path `_ of every request. These schemas tables, views and stored procedures **don't get API endpoints**, they can only be referred from the database objects inside your :ref:`db-schemas`. + + This parameter was meant to make it easier to use **PostgreSQL extensions** (like PostGIS) that are outside of the :ref:`db-schemas`. + + Multiple schemas can be added in a comma-separated string, e.g. ``public, extensions``. + +.. _db-max-rows: + +db-max-rows +----------- + + *For backwards compatibility, this config parameter is also available without prefix as "max-rows".* + + =============== ================= + **Environment** PGRST_DB_MAX_ROWS + **In-Database** pgrst.db_max_rows + =============== ================= + + A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests. .. _db-pool: db-pool ------- + =============== ================= + **Environment** PGRST_DB_POOL + **In-Database** `n/a` + =============== ================= + Number of connections to keep open in PostgREST's database pool. Having enough here for the maximum expected simultaneous client connections can improve performance. Note it's pointless to set this higher than the :code:`max_connections` GUC in your database. .. _db-pool-timeout: @@ -131,52 +252,91 @@ db-pool db-pool-timeout --------------- + =============== ================= + **Environment** PGRST_DB_POOL_TIMEOUT + **In-Database** `n/a` + =============== ================= + Time to live, in seconds, for an idle database pool connection. If the timeout is reached the connection will be closed. Once a new request arrives a new connection will be started. -.. _db-extra-search-path: +.. _db-pre-request: -db-extra-search-path --------------------- +db-pre-request +-------------- - Extra schemas to add to the `search_path `_ of every request. These schemas tables, views and stored procedures **don't get API endpoints**, they can only be referred from the database objects inside your :ref:`db-schema`. + *For backwards compatibility, this config parameter is also available without prefix as "pre-request".* - This parameter was meant to make it easier to use **PostgreSQL extensions** (like PostGIS) that are outside of the :ref:`db-schema`. + =============== ================= + **Environment** PGRST_DB_PRE_REQUEST + **In-Database** pgrst.db_pre_request + =============== ================= - Multiple schemas can be added in a comma-separated string, e.g. ``public, extensions``. + A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing. -.. _db-channel: +.. _db-prepared-statements: -db-channel +db-prepared-statements +---------------------- + + =============== ================= + **Environment** PGRST_DB_PREPARED_STATEMENTS + **In-Database** pgrst.db_prepared_statements + =============== ================= + + Enables or disables prepared statements. + + When disabled, the generated queries will be parameterized (invulnerable to SQL injection) but they will not be prepared (cached in the database session). Not using prepared statements will noticeably decrease performance, so it's recommended to always have this setting enabled. + + You should only set this to ``false`` when using PostgresSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section ` for more information. + +.. _db-schemas: + +db-schemas ---------- - The name of the notification channel that PostgREST uses for :ref:`schema_reloading` and configuration reloading. + *For backwards compatibility, this config parameter is also available in singular as "db-schema".* -.. _db-channel-enabled: + =============== ================= + **Environment** PGRST_DB_SCHEMAS + **In-Database** pgrst.db_schemas + =============== ================= -db-channel-enabled ------------------- + The database schema to expose to REST clients. Tables, views and stored procedures in this schema will get API endpoints. - When this is set to :code:`true`, the notification channel specified in :ref:`db-channel` is enabled. + .. code:: bash - You should set this to ``false`` when using PostgresSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section ` for more information. + db-schemas = "api" -.. _db-prepared-statements: + This schema gets added to the `search_path `_ of every request. -db-prepared-statements ----------------------- +List of schemas +~~~~~~~~~~~~~~~ - Enables or disables prepared statements. + You can also specify a list of schemas that can be used for **schema-based multitenancy** and **api versioning** by :ref:`multiple-schemas`. Example: - When disabled, the generated queries will be parameterized (invulnerable to SQL injection) but they will not be prepared (cached in the database session). Not using prepared statements will noticeably decrease performance, so it's recommended to always have this setting enabled. + .. code:: bash - You should only set this to ``false`` when using PostgresSQL behind an external connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section ` for more information. + db-schemas = "tenant1, tenant2" + + If you don't :ref:`Switch Schemas `, the first schema in the list(``tenant1`` in this case) is chosen as the default schema. + + *Only the chosen schema* gets added to the `search_path `_ of every request. + + .. warning:: + + Never expose private schemas in this way. See :ref:`schema_isolation`. .. _db-tx-end: db-tx-end --------- + =============== ================= + **Environment** PGRST_DB_TX_END + **In-Database** pgrst.db_tx_end + =============== ================= + Specifies how to terminate the database transactions. .. code:: bash @@ -193,71 +353,108 @@ 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-uri: -db-config ---------- +db-uri +------ - Enables the in-database configuration. + =============== ================= + **Environment** PGRST_DB_URI + **In-Database** `n/a` + =============== ================= + + The standard connection PostgreSQL `URI format `_. Symbols and unusual characters in the password or other fields should be percent encoded to avoid a parse error. If enforcing an SSL connection to the database is required you can use `sslmode `_ in the URI, for example ``postgres://user:pass@host:5432/dbname?sslmode=require``. + + When running PostgREST on the same machine as PostgreSQL, it is also possible to connect to the database using a `Unix socket `_ and the `Peer Authentication method `_ as an alternative to TCP/IP communication and authentication with a password, this also grants higher performance. To do this you can omit the host and the password, e.g. ``postgres://user@/dbname``, see the `libpq connection string `_ documentation for more details. + + On older systems like Centos 6, with older versions of libpq, a different db-uri syntax has to be used. In this case the URI is a string of space separated key-value pairs (key=value), so the example above would be :code:`"host=host user=user port=5432 dbname=dbname password=pass"`. + + Choosing a value for this parameter beginning with the at sign such as ``@filename`` (e.g. ``@./configs/my-config``) loads the secret out of an external file. .. _db-use-legacy-gucs: db-use-legacy-gucs ------------------ + =============== ================= + **Environment** PGRST_DB_USE_LEGACY_GUCS + **In-Database** pgrst.db_use_legacy_gucs + =============== ================= + Determine if GUC request settings for headers, cookies and jwt claims use the `legacy names `_ (string with dashes, invalid starting from PostgreSQL v14) with text values instead of the :ref:`new names ` (string without dashes, valid on all PostgreSQL versions) with json values. On PostgreSQL versions 14 and above, this parameter is ignored. -.. _server-host: - -server-host ------------ +.. _jwt-aud: - Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings: +jwt-aud +------- - * :code:`*` - any IPv4 or IPv6 hostname - * :code:`*4` - any IPv4 or IPv6 hostname, IPv4 preferred - * :code:`!4` - any IPv4 hostname - * :code:`*6` - any IPv4 or IPv6 hostname, IPv6 preferred - * :code:`!6` - any IPv6 hostname + =============== ================= + **Environment** PGRST_JWT_AUD + **In-Database** pgrst.jwt_aud + =============== ================= -.. _server-port: + Specifies the `JWT audience claim `_. If this claim is present in the client provided JWT then you must set this to the same value as in the JWT, otherwise verifying the JWT will fail. -server-port ------------ +.. _jwt-role-claim-key: - The TCP port to bind the web server. +jwt-role-claim-key +------------------ -.. _server-unix-socket: + *For backwards compatibility, this config parameter is also available without prefix as "role-claim-key".* -server-unix-socket ------------------- + =============== ================= + **Environment** PGRST_JWT_ROLE_CLAIM_KEY + **In-Database** pgrst.jwt_role_claim_key + =============== ================= - `Unix domain socket `_ where to bind the PostgREST web server. - If specified, this takes precedence over :ref:`server-port`. Example: + A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. This can be used to consume a JWT provided by a third party service like Auth0, Okta or Keycloak. Usage examples: .. code:: bash - server-unix-socket = "/tmp/pgrst.sock" + # {"postgrest":{"roles": ["other", "author"]}} + # the DSL accepts characters that are alphanumerical or one of "_$@" as keys + jwt-role-claim-key = ".postgrest.roles[1]" -.. _server-unix-socket-mode: + # {"https://www.example.com/role": { "key": "author }} + # non-alphanumerical characters can go inside quotes(escaped in the config value) + jwt-role-claim-key = ".\"https://www.example.com/role\".key" -server-unix-socket-mode ------------------------ +.. _jwt-secret: - `Unix file mode `_ to be set for the socket specified in :ref:`server-unix-socket` - Needs to be a valid octal between 600 and 777. +jwt-secret +---------- - .. code:: bash + =============== ================= + **Environment** PGRST_JWT_SECRET + **In-Database** pgrst.jwt_secret + =============== ================= - server-unix-socket-mode = "660" + The secret or `JSON Web Key (JWK) (or set) `_ used to decode JWT tokens clients provide for authentication. For security the key must be **at least 32 characters long**. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded. Both symmetric and asymmetric cryptography are supported. For more info see :ref:`asym_keys`. + +.. _jwt-secret-is-base64: + +jwt-secret-is-base64 +-------------------- + + =============== ================= + **Environment** PGRST_JWT_SECRET_IS_BASE64 + **In-Database** pgrst.jwt_secret_is_base64 + =============== ================= + + When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret. .. _log-level: log-level --------- + =============== ================= + **Environment** PGRST_LOG_LEVEL + **In-Database** `n/a` + =============== ================= + Specifies the level of information to be logged while running PostgREST. .. code:: bash @@ -282,6 +479,11 @@ log-level openapi-mode ------------ + =============== ================= + **Environment** PGRST_OPENAPI_MODE + **In-Database** pgrst.openapi_mode + =============== ================= + Specifies how the OpenAPI output should be displayed. .. code:: bash @@ -303,6 +505,11 @@ openapi-mode openapi-server-proxy-uri ------------------------ + =============== ================= + **Environment** PGRST_OPENAPI_SERVER_PROXY_URI + **In-Database** pgrst.openapi_server_proxy_uri + =============== ================= + Overrides the base URL used within the OpenAPI self-documentation hosted at the API root path. Use a complete URI syntax :code:`scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]`. Ex. :code:`https://postgrest.com` .. code:: json @@ -321,70 +528,16 @@ openapi-server-proxy-uri ] } -.. _jwt-secret: - -jwt-secret ----------- - - The secret or `JSON Web Key (JWK) (or set) `_ used to decode JWT tokens clients provide for authentication. For security the key must be **at least 32 characters long**. If this parameter is not specified then PostgREST refuses authentication requests. Choosing a value for this parameter beginning with the at sign such as :code:`@filename` loads the secret out of an external file. This is useful for automating deployments. Note that any binary secrets must be base64 encoded. Both symmetric and asymmetric cryptography are supported. For more info see :ref:`asym_keys`. - -.. _jwt-aud: - -jwt-aud -------- - - Specifies the `JWT audience claim `_. If this claim is present in the client provided JWT then you must set this to the same value as in the JWT, otherwise verifying the JWT will fail. - -.. _secret-is-base64: - -secret-is-base64 ----------------- - - When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret. - -.. _max-rows: - -max-rows --------- - - A hard limit to the number of rows PostgREST will fetch from a view, table, or stored procedure. Limits payload size for accidental or malicious requests. - -.. _pre-request: - -pre-request ------------ - - A schema-qualified stored procedure name to call right after switching roles for a client request. This provides an opportunity to modify SQL variables or raise an exception to prevent the request from completing. - -.. _app.settings.*: - -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')`. - -.. _role-claim-key: - -role-claim-key --------------- - - A JSPath DSL that specifies the location of the :code:`role` key in the JWT claims. This can be used to consume a JWT provided by a third party service like Auth0, Okta or Keycloak. Usage examples: - - .. code:: bash - - # {"postgrest":{"roles": ["other", "author"]}} - # the DSL accepts characters that are alphanumerical or one of "_$@" as keys - role-claim-key = ".postgrest.roles[1]" - - # {"https://www.example.com/role": { "key": "author }} - # non-alphanumerical characters can go inside quotes(escaped in the config value) - role-claim-key = ".\"https://www.example.com/role\".key" - .. _raw-media-types: raw-media-types --------------- + =============== ================= + **Environment** PGRST_RAW_MEDIA_TYPES + **In-Database** pgrst.raw_media_types + =============== ================= + This serves to extend the `Media Types `_ that PostgREST currently accepts through an ``Accept`` header. These media types can be requested by following the same rules as the ones defined in :ref:`binary_output`. @@ -396,76 +549,66 @@ raw-media-types raw-media-types="image/png, text/xml" -.. _env_variables_config: - -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.*``. - -.. _config_reloading: - -Configuration Reloading -======================= - -To reload the configuration without restarting the PostgREST server, send a SIGUSR2 signal to the server process. - -.. code:: bash - - killall -SIGUSR2 postgrest - -This method does not reload :ref:`env_variables_config` and it will not work for reloading a Docker container configuration. In these cases, you need to restart the PostgREST server or use the :ref:`in_db_config` as an alternative. +.. _server-host: -.. important:: +server-host +----------- - The following settings will not be reread when reloading the configuration. You will need to restart PostgREST in that case. + =============== ================= + **Environment** PGRST_SERVER_HOST + **In-Database** pgrst.server_host + =============== ================= - * :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: + Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings: -In-Database Configuration -========================= + * :code:`*` - any IPv4 or IPv6 hostname + * :code:`*4` - any IPv4 or IPv6 hostname, IPv4 preferred + * :code:`!4` - any IPv4 hostname + * :code:`*6` - any IPv4 or IPv6 hostname, IPv6 preferred + * :code:`!6` - any IPv6 hostname -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`. +.. _server-port: -For example, you can configure :ref:`db-schema` and :ref:`jwt-secret` like this: +server-port +----------- -.. code:: postgresql + =============== ================= + **Environment** PGRST_SERVER_PORT + **In-Database** pgrst.server_port + =============== ================= - ALTER ROLE authenticator IN DATABASE SET pgrst.db_schema = "tenant1, tenant2, tenant3" - ALTER ROLE authenticator IN DATABASE SET pgrst.jwt_secret = "REALLYREALLYREALLYREALLYVERYSAFE" + The TCP port to bind the web server. -Note that underscores(``_``) need to be used instead of dashes(``-``) for the in-database config options. +.. _server-unix-socket: -.. important:: +server-unix-socket +------------------ - 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. + =============== ================= + **Environment** PGRST_SERVER_UNIX_SOCKET + **In-Database** pgrst.server_unix_socket + =============== ================= -When using both the configuration file and the in-database configuration, the latter takes precedence. + `Unix domain socket `_ where to bind the PostgREST web server. + If specified, this takes precedence over :ref:`server-port`. Example: -.. danger:: + .. code:: bash - 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. + server-unix-socket = "/tmp/pgrst.sock" -.. _in_db_config_reloading: +.. _server-unix-socket-mode: -In-database configuration reloading ------------------------------------ +server-unix-socket-mode +----------------------- -To reload the in-database configuration from within the database, you can use a NOTIFY command. + =============== ================= + **Environment** PGRST_SERVER_UNIX_SOCKET_MODE + **In-Database** pgrst.server_unix_socket_mode + =============== ================= -.. code:: postgresql + `Unix file mode `_ to be set for the socket specified in :ref:`server-unix-socket` + Needs to be a valid octal between 600 and 777. - NOTIFY pgrst, 'reload config' + .. code:: bash -The ``"pgrst"`` notification channel is enabled by default. For configuring the channel, see :ref:`db-channel` and :ref:`db-channel-enabled`. + server-unix-socket-mode = "660" diff --git a/how-tos/embedding-table-from-another-schema.rst b/how-tos/embedding-table-from-another-schema.rst index 118d630d1..6631982de 100644 --- a/how-tos/embedding-table-from-another-schema.rst +++ b/how-tos/embedding-table-from-another-schema.rst @@ -3,7 +3,7 @@ Embedding a table from another schema :author: `steve-chavez `_ -Suppose you have a **people** table in the ``public`` schema and this schema is exposed through PostgREST's :ref:`db-schema`. +Suppose you have a **people** table in the ``public`` schema and this schema is exposed through PostgREST's :ref:`db-schemas`. .. code-block:: postgres diff --git a/postgrest.dict b/postgrest.dict index fba460fd9..16a91dd58 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -125,6 +125,7 @@ Rechkemmer reconnection Redux refactor +Reloadable Remo requester's RESTful diff --git a/releases/v7.0.0.rst b/releases/v7.0.0.rst index 34e5d46db..3c2c0ef58 100644 --- a/releases/v7.0.0.rst +++ b/releases/v7.0.0.rst @@ -10,7 +10,7 @@ You can download this release at the `PostgREST v7.0.0 release page ` defined in :ref:`db-schema`. +* Support for :ref:`Switching to a schema ` defined in :ref:`db-schemas`. |br| -- `@steve-chavez `_, `@mahmoudkassem `_ * Support for :ref:`planned_count` and :ref:`estimated_count`. diff --git a/tutorials/tut0.rst b/tutorials/tut0.rst index 04e6420a3..27e9cb44d 100644 --- a/tutorials/tut0.rst +++ b/tutorials/tut0.rst @@ -162,7 +162,7 @@ PostgREST uses a configuration file to tell it how to connect to the database. C .. code-block:: ini db-uri = "postgres://authenticator:mysecretpassword@localhost:5433/postgres" - db-schema = "api" + db-schemas = "api" db-anon-role = "web_anon" The configuration file has other :ref:`options `, but this is all we need. diff --git a/tutorials/tut1.rst b/tutorials/tut1.rst index ec288fc97..cb307dc4b 100644 --- a/tutorials/tut1.rst +++ b/tutorials/tut1.rst @@ -226,7 +226,7 @@ Next update :code:`tutorial.conf` and specify the new function: # add this line to tutorial.conf - pre-request = "auth.check_token" + db-pre-request = "auth.check_token" Restart PostgREST for the change to take effect. Next try making a request with our original token and then with the revoked one.