add: --ready flag for postgrest healthcheck

The `--ready` flag is a wrapper around the admin server
`/ready` request. This is done through using an http client
library in postgrest.

Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>

docs/explanations/install.rst

@@ -142,6 +142,7 @@ To avoid having to install the database at all, you can run both it and the serv
       ports:
         - "3000:3000"
       environment:
+        PGRST_SERVER_HOST: localhost # necessary for `postgrest --ready` flag to work
         PGRST_DB_URI: postgres://app_user:password@db:5432/app_db
         PGRST_OPENAPI_SERVER_PROXY_URI: http://127.0.0.1:3000
       depends_on:

docs/references/cli.rst

@@ -7,7 +7,7 @@ PostgREST provides a CLI with the options listed below:
 
 .. code:: text
 
-  Usage: postgrest [-v|--version] [-e|--example] [--dump-config | --dump-schema] 
+  Usage: postgrest [-v|--version] [-e|--example] [--dump-config | --dump-schema | --ready]
                  [FILENAME]
 
     PostgREST / create a REST API to an existing Postgres
@@ -20,6 +20,8 @@ PostgREST provides a CLI with the options listed below:
     --dump-config            Dump loaded configuration and exit
     --dump-schema            Dump loaded schema as JSON and exit (for debugging,
                              output structure is unstable)
+    --ready                  Checks the health of PostgREST by doing a request on
+                             the admin server /ready endpoint
     FILENAME                 Path to configuration file
 
 FILENAME
@@ -71,3 +73,17 @@ Dump Schema
   $ postgrest --dump-schema
 
 Dumps the schema cache in JSON format.
+
+Ready Flag
+----------
+
+Makes a request to the ``/ready`` endpoint of the :ref:`admin_server`. It exits with a return code of ``0`` on success and ``1`` on failure.
+
+.. code-block:: bash
+
+  $ postgrest --ready
+  OK: http://localhost:3001/ready
+
+.. note::
+
+  The ``--ready`` flag cannot be used when :ref:`server-host` is configured with special hostnames. We suggest to change it to ``localhost``.