From 4aff0caa59b88b3c828fb12bcdfc13e0f797f532 Mon Sep 17 00:00:00 2001 From: Laurence Isla Date: Wed, 23 Feb 2022 17:25:07 -0500 Subject: [PATCH] Add documentation on the minimal health check --- docs/admin.rst | 29 +++++++++++++++++++++++++++++ docs/configuration.rst | 22 ++++++++++++++++++---- 2 files changed, 47 insertions(+), 4 deletions(-) diff --git a/docs/admin.rst b/docs/admin.rst index d487062ed..f2f0ad8f8 100644 --- a/docs/admin.rst +++ b/docs/admin.rst @@ -256,6 +256,35 @@ Schema Reloading Changing the schema while the server is running can lead to errors due to a stale schema cache. To learn how to refresh the cache see :ref:`schema_reloading`. +.. _health_check: + +Health Check +------------ + +You can enable a minimal health check to verify if PostgREST is available for client requests and to check the status of its internal state. + +To do this, set the configuration variable :ref:`admin-server-port` to the port number of your preference. Two endpoints ``live`` and ``ready`` will then be available. + +The ``live`` endpoint verifies if PostgREST is running on its configured port. A request will return ``200 OK`` if PostgREST is alive or ``503`` otherwise. + +The ``ready`` endpoint also checks the state of both the Database Connection and the :ref:`schema_cache`. A request will return ``200 OK`` if it is ready or ``503`` if not. + +For instance, to verify if PostgREST is running at ``localhost:3000`` while the ``admin-server-port`` is set to ``3001``: + +.. tabs:: + + .. code-tab:: http + + GET localhost:3001/live HTTP/1.1 + + .. code-tab:: bash Curl + + curl -I "http://localhost:3001/live" + +.. code-block:: http + + HTTP/1.1 200 OK + Daemonizing =========== diff --git a/docs/configuration.rst b/docs/configuration.rst index 422093d36..57c22199b 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -105,6 +105,7 @@ It's not possible to change :ref:`env_variables_config` for a running process an The following settings will not be reloaded. You will need to restart PostgREST to change those. + * :ref:`admin-server-port` * :ref:`db-uri` * :ref:`db-pool` * :ref:`db-pool-timeout` @@ -145,6 +146,7 @@ List of parameters ======================== ======= ================= ========== Name Type Default Reloadable ======================== ======= ================= ========== +admin-server-port Int app.settings.* String Y db-anon-role String Y db-channel String pgrst Y @@ -174,6 +176,18 @@ server-unix-socket String server-unix-socket-mode String 660 ======================== ======= ================= ========== +.. _admin-server-port: + +admin-server-port +----------------- + + =============== ======================= + **Environment** PGRST_ADMIN_SERVER_PORT + **In-Database** `n/a` + =============== ======================= + +Specifies the port for the :ref:`health_check` endpoints. + .. _app.settings.*: app.settings.* @@ -589,7 +603,7 @@ server-host =============== ================= **Environment** PGRST_SERVER_HOST - **In-Database** pgrst.server_host + **In-Database** `n/a` =============== ================= Where to bind the PostgREST web server. In addition to the usual address options, PostgREST interprets these reserved addresses with special meanings: @@ -607,7 +621,7 @@ server-port =============== ================= **Environment** PGRST_SERVER_PORT - **In-Database** pgrst.server_port + **In-Database** `n/a` =============== ================= The TCP port to bind the web server. @@ -619,7 +633,7 @@ server-unix-socket =============== ================= **Environment** PGRST_SERVER_UNIX_SOCKET - **In-Database** pgrst.server_unix_socket + **In-Database** `n/a` =============== ================= `Unix domain socket `_ where to bind the PostgREST web server. @@ -636,7 +650,7 @@ server-unix-socket-mode =============== ================= **Environment** PGRST_SERVER_UNIX_SOCKET_MODE - **In-Database** pgrst.server_unix_socket_mode + **In-Database** `n/a` =============== ================= `Unix file mode `_ to be set for the socket specified in :ref:`server-unix-socket`