From 94490ed12b88d8a73328268d928da55866fdd2f5 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Mon, 6 May 2024 09:38:48 -0500 Subject: [PATCH] docs: better place for application_name --- docs/postgrest.dict | 1 - docs/references/connection_pool.rst | 25 ++++++++++++--- docs/references/observability.rst | 50 +++++++---------------------- 3 files changed, 31 insertions(+), 45 deletions(-) diff --git a/docs/postgrest.dict b/docs/postgrest.dict index d24804de56d..ded55e8982f 100644 --- a/docs/postgrest.dict +++ b/docs/postgrest.dict @@ -157,7 +157,6 @@ stateful stdout supervisees SvelteKit -syslog systemd todo todos diff --git a/docs/references/connection_pool.rst b/docs/references/connection_pool.rst index 16a671af928..13fdf5c4d29 100644 --- a/docs/references/connection_pool.rst +++ b/docs/references/connection_pool.rst @@ -7,11 +7,6 @@ A connection pool is a cache of reusable database connections. It allows serving Minimizing connections is paramount to performance. Each PostgreSQL connection creates a process, having too many can exhaust available resources. -Connection String ------------------ - -For connecting to the database, the pool requires a connection string. You can configure it using :ref:`db-uri`. - .. _pool_growth_limit: .. _dyn_conn_pool: @@ -22,6 +17,26 @@ To conserve system resources, PostgREST uses a dynamic connection pool. This ena - If all the connections are being used, a new connection is added. The pool can grow until it reaches the :ref:`db-pool` size. Note that it’s pointless to set this higher than the ``max_connections`` setting in your database. - If a connection is unused for a period of time (:ref:`db-pool-max-idletime`), it will be released. +- For connecting to the database, the :ref:`authenticator ` role is used. You can configure this using :ref:`db-uri`. + +Connection Application Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PostgREST sets the connection `application_name `_ for all of its used connections. +This is useful for PostgreSQL statistics and logs. + +For example, you can query `pg_stat_activity `_ to get the PostgREST version: + +.. code-block:: postgres + + select distinct usename, application_name + from pg_stat_activity + where usename = 'authenticator'; + + usename | application_name + ---------------+-------------------------- + authenticator | PostgREST 12.1 + Connection lifetime ------------------- diff --git a/docs/references/observability.rst b/docs/references/observability.rst index a0079df66e1..04a91a3f729 100644 --- a/docs/references/observability.rst +++ b/docs/references/observability.rst @@ -20,33 +20,20 @@ PostgREST logs basic request information to ``stdout``, including the authentica 127.0.0.1 - user [26/Jul/2021:01:56:38 -0500] "GET /clients HTTP/1.1" 200 - "" "curl/7.64.0" 127.0.0.1 - anonymous [26/Jul/2021:01:56:48 -0500] "GET /unexistent HTTP/1.1" 404 - "" "curl/7.64.0" -For diagnostic information about the server itself, PostgREST logs to ``stderr``. +For diagnostic information about the server itself, PostgREST logs to ``stderr``. It includes the server version and also the version of the connected PostgreSQL. .. code:: - 12/Jun/2021:17:47:39 -0500: Starting PostgREST 11.1.0... - 12/Jun/2021:17:47:39 -0500: Attempting to connect to the database... - 12/Jun/2021:17:47:39 -0500: Listening on port 3000 - 12/Jun/2021:17:47:39 -0500: Connection successful - 12/Jun/2021:17:47:39 -0500: Config re-loaded - 12/Jun/2021:17:47:40 -0500: Schema cache loaded - -.. note:: - - When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a log file or to the syslog: - - .. code-block:: bash - - ssh foo@example.com \ - 'postgrest foo.conf /var/log/postgrest.log 2>&1 &' - - # another option is to pipe the output into "logger -t postgrest" - -Currently PostgREST doesn't log the SQL commands executed against the underlying database. + 06/May/2024:08:16:11 -0500: Starting PostgREST 12.1... + 06/May/2024:08:16:11 -0500: Attempting to connect to the database... + 06/May/2024:08:16:11 -0500: Successfully connected to PostgreSQL 14.10 (Ubuntu 14.10-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit + 06/May/2024:08:16:11 -0500: Listening on port 3000 Database Logs ------------- +Currently PostgREST doesn't log the SQL commands executed against the underlying database. + To find the SQL operations, you can watch the database logs. By default PostgreSQL does not keep these logs, so you'll need to make the configuration changes below. Find :code:`postgresql.conf` inside your PostgreSQL data directory (to find that, issue the command :code:`show data_directory;`). Either find the settings scattered throughout the file and change them to the following values, or append this block of code to the end of the configuration file. @@ -172,12 +159,10 @@ Max pool connections. Traces ====== -Server Version --------------- - -When debugging a problem it's important to verify the running PostgREST version. There are three ways to do this: +Server Version Header +--------------------- -- Look for the :code:`Server` HTTP response header that is returned on every request. +When debugging a problem it's important to verify the running PostgREST version. For this you can look at the :code:`Server` HTTP response header that is returned on every request. .. code:: @@ -185,20 +170,6 @@ When debugging a problem it's important to verify the running PostgREST version. Server: postgrest/11.0.1 -- Query ``application_name`` on `pg_stat_activity `_. - -.. code-block:: postgres - - select distinct application_name - from pg_stat_activity - where application_name ilike '%postgrest%'; - - application_name - ------------------------------ - PostgREST 11.1.0 - -- The ``stderr`` logs also contain the version, as noted on :ref:`pgrst_logging`. - .. _trace_header: Trace Header @@ -348,6 +319,7 @@ For example, to only allow requests from an IP address to get the execution plan const redirects = { '#health_check': 'health_check.html', + '#server-version': '#server-version-header', }; let willRedirectTo = redirects[hash];