add CLI to docs

CHANGELOG.md

@@ -17,6 +17,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
  - #3435, Add log-level=debug, for development purposes - @steve-chavez
  - #1526, Add `/metrics` endpoint on admin server - @steve-chavez
    - Exposes connection pool metrics, schema cache metrics
+ - #3248, Add more config examples to CLI - @taimoorzaeem
+   + Now accepts ``--example-file``, ``--example-db``, and ``--example-env``
+   + Add docs page for CLI
 
 ### Fixed
 

docs/index.rst

@@ -147,6 +147,7 @@ Technical references for PostgREST's functionality.
 
    references/auth.rst
    references/api.rst
+   references/cli.rst
    references/transactions.rst
    references/connection_pool.rst
    references/schema_cache.rst

docs/postgrest.dict

@@ -15,6 +15,7 @@ Cardano
 casted
 cd
 centric
+CLI
 coercible
 conf
 Cloudflare

docs/references/cli.rst

@@ -0,0 +1,41 @@
+.. _cli:
+
+CLI
+===
+
+PostgREST provides a CLI to start and run your postgrest service. The CLI provides the commands listed below:
+
+.. _cli_commands:
+
+CLI Commands
+------------
+
+Help and Version
+~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+  $ postgrest [-h|--help]
+  $ postgrest [-v|--version]
+
+
+Example Config
+~~~~~~~~~~~~~~
+
+.. code:: bash
+
+  $ postgrest [--example-file]
+  $ postgrest [--example-db]
+  $ postgrest [--example-env]
+
+These commands show the example configuration file of the selected type.
+
+
+Config or Schema Cache
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+  $ postgrest [--dump-config|--dump-schema-cache] [FILENAME]
+
+Here ``FILENAME`` is the path to configuration file.

src/PostgREST/CLI.hs

@@ -44,7 +44,7 @@ main CLI{cliCommand, cliPath} = do
       CmdDumpConfig -> do
         when configDbConfig $ AppState.reReadConfig True appState
         putStr . Config.toText =<< AppState.getConfig appState
-      CmdDumpSchema -> putStrLn =<< dumpSchema appState
+      CmdDumpSchemaCache -> putStrLn =<< dumpSchema appState
       CmdRun -> App.run appState)
 
 -- | Dump SchemaCache schema to JSON
@@ -61,6 +61,7 @@ dumpSchema appState = do
       exitFailure
     Right sCache -> return $ JSON.encode sCache
 
+
 -- | Command line interface options
 data CLI = CLI
   { cliCommand :: Command
@@ -70,7 +71,9 @@ data CLI = CLI
 data Command
   = CmdRun
   | CmdDumpConfig
-  | CmdDumpSchema
+  | CmdDumpSchemaCache
+
+data Example = ExampleFile | ExampleDb | ExampleEnv
 
 -- | Read command line interface options. Also prints help.
 readCLIShowHelp :: IO CLI
@@ -93,16 +96,28 @@ readCLIShowHelp =
         <> O.short 'v'
         <> O.help "Show the version information"
 
-    exampleParser =
-      O.infoOption exampleConfigFile $
-        O.long "example"
+    exampleParser = exampleParserFile <|> exampleParserDb <|> exampleParserEnv
+
+    exampleParserFile =
+      O.infoOption (exampleConfig ExampleFile) $
+        O.long "example-file"
         <> O.short 'e'
-        <> O.help "Show an example configuration file"
+        <> O.help "Show an example of a configuration file"
+
+    exampleParserDb =
+      O.infoOption (exampleConfig ExampleDb) $
+        O.long "example-db"
+        <> O.help "Show an example of in-database configuration"
+
+    exampleParserEnv =
+      O.infoOption (exampleConfig ExampleEnv) $
+        O.long "example-env"
+        <> O.help "Show an example of environment variables configuration"
 
     cliParser :: O.Parser CLI
     cliParser =
       CLI
-        <$> (dumpConfigFlag <|> dumpSchemaFlag)
+        <$> (dumpConfigFlag <|> dumpSchemaCacheFlag)
         <*> O.optional configFileOption
 
     configFileOption =
@@ -115,13 +130,13 @@ readCLIShowHelp =
         O.long "dump-config"
         <> O.help "Dump loaded configuration and exit"
 
-    dumpSchemaFlag =
-      O.flag CmdRun CmdDumpSchema $
-        O.long "dump-schema"
+    dumpSchemaCacheFlag =
+      O.flag CmdRun CmdDumpSchemaCache $
+        O.long "dump-schema-cache"
         <> O.help "Dump loaded schema as JSON and exit (for debugging, output structure is unstable)"
 
-exampleConfigFile :: [Char]
-exampleConfigFile =
+exampleConfig :: Example -> [Char]
+exampleConfig ExampleFile =
   [str|## Admin server used for checks. It's disabled by default unless a port is specified.
       |# admin-server-port = 3001
       |
@@ -198,6 +213,7 @@ exampleConfigFile =
       |## Choose a secret, JSON Web Key (or set) to enable JWT auth
       |## (use "@filename" to load from separate file)
       |# jwt-secret = "secret_with_at_least_32_characters"
+      |
       |jwt-secret-is-base64 = false
       |
       |## Enables and set JWT Cache max lifetime, disables caching with 0
@@ -230,3 +246,227 @@ exampleConfigFile =
       |## When none is provided, 660 is applied by default
       |# server-unix-socket-mode = "660"
       |]
+exampleConfig ExampleDb =
+  [str|## Admin server used for checks. It's disabled by default unless a port is specified.
+      |# ALTER ROLE authenticator SET pgrst.admin_server_port = '3001';
+      |
+      |## The database role to use when no client authentication is provided
+      |# ALTER ROLE authenticator SET pgrst.db_anon_role = 'anon';
+      |
+      |## Notification channel for reloading the schema cache
+      |ALTER ROLE authenticator SET pgrst.db_channel = 'pgrst';
+      |
+      |## Enable or disable the notification channel
+      |ALTER ROLE authenticator SET pgrst.db_channel_enabled = 'true';
+      |
+      |## Enable in-database configuration
+      |ALTER ROLE authenticator SET pgrst.db_config = 'true';
+      |
+      |## Function for in-database configuration
+      |# ALTER ROLE authenticator SET pgrst.db_pre_config = 'postgrest.pre_config';
+      |
+      |## Extra schemas to add to the search_path of every request
+      |ALTER ROLE authenticator SET pgrst.db_extra_search_path = 'public';
+      |
+      |## Limit rows in response
+      |# ALTER ROLE authenticator SET pgrst.db_max_rows = '1000';
+      |
+      |## Allow getting the EXPLAIN plan through the `Accept: application/vnd.pgrst.plan` header
+      |# ALTER ROLE authenticator SET pgrst.db_plan_enabled = 'false';
+      |
+      |## Number of open connections in the pool
+      |ALTER ROLE authenticator SET pgrst.db_pool = '10';
+      |
+      |## Time in seconds to wait to acquire a slot from the connection pool
+      |# ALTER ROLE authenticator SET pgrst.db_pool_acquisition_timeout = '10';
+      |
+      |## Time in seconds after which to recycle pool connections
+      |# ALTER ROLE authenticator SET pgrst.db_pool_max_lifetime = '1800';
+      |
+      |## Time in seconds after which to recycle unused pool connections
+      |# ALTER ROLE authenticator SET pgrst.db_pool_max_idletime = '30';
+      |
+      |## Allow automatic database connection retrying
+      |# ALTER ROLE authenticator SET pgrst.db_pool_automatic_recovery = 'true';
+      |
+      |## Stored proc to exec immediately after auth
+      |# ALTER ROLE authenticator SET pgrst.db_pre_request = 'stored_proc_name';
+      |
+      |## Enable or disable prepared statements. disabling is only necessary when behind a connection pooler.
+      |## When disabled, statements will be parametrized but won't be prepared.
+      |ALTER ROLE authenticator SET pgrst.db_prepared_statements = 'true';
+      |
+      |## The name of which database schema to expose to REST clients
+      |ALTER ROLE authenticator SET pgrst.db_schemas = 'public';
+      |
+      |## How to terminate database transactions
+      |## Possible values are:
+      |## commit (default)
+      |##   Transaction is always committed, this can not be overriden
+      |## commit-allow-override
+      |##   Transaction is committed, but can be overriden with Prefer tx=rollback header
+      |## rollback
+      |##   Transaction is always rolled back, this can not be overriden
+      |## rollback-allow-override
+      |##   Transaction is rolled back, but can be overriden with Prefer tx=commit header
+      |ALTER ROLE authenticator SET pgrst.db_tx_end = 'commit';
+      |
+      |## The standard connection URI format, documented at
+      |## https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
+      |ALTER ROLE authenticator SET pgrst.db_uri = 'postgresql://';
+      |
+      |# ALTER ROLE authenticator SET pgrst.jwt_aut = 'your_audience_claim';
+      |
+      |## Jspath to the role claim key
+      |ALTER ROLE authenticator SET pgrst.jwt_role_claim_key = '.role';
+      |
+      |## Choose a secret, JSON Web Key (or set) to enable JWT auth
+      |## (use "@filename" to load from separate file)
+      |# ALTER ROLE authenticator SET pgrst.jwt_secret = 'secret_with_at_least_32_characters'
+      |
+      |ALTER ROLE authenticator SET pgrst.jwt_secret_is_base64 = 'false';
+      |
+      |## Enables and set JWT Cache max lifetime, disables caching with 0
+      |# ALTER ROLE authenticator SET pgrst.jwt_cache_max_lifetime = '0';
+      |
+      |## Logging level, the admitted values are: crit, error, warn and info.
+      |ALTER ROLE authenticator SET pgrst.log_level = 'error';
+      |
+      |## Determine if the OpenAPI output should follow or ignore role privileges or be disabled entirely.
+      |## Admitted values: follow-privileges, ignore-privileges, disabled
+      |ALTER ROLE authenticator SET pgrst.openapi_mode = 'follow-privileges';
+      |
+      |## Base url for the OpenAPI output
+      |ALTER ROLE authenticator SET pgrst.openapi_server_proxy_uri = '';
+      |
+      |## Configurable CORS origins
+      |# ALTER ROLE authenticator SET pgrst.server_cors_allowed_origins = '';
+      |
+      |ALTER ROLE authenticator SET pgrst.server_host = '!4';
+      |
+      |ALTER ROLE authenticator SET pgrst.server_port = '3000';
+      |
+      |## Allow getting the request-response timing information through the `Server-Timing` header
+      |ALTER ROLE authenticator SET pgrst.server_timing_enabled = 'false';
+      |
+      |## Unix socket location
+      |## if specified it takes precedence over server-port
+      |# ALTER ROLE authenticator SET pgrst.server_unix_socket = '/tmp/pgrst.sock';
+      |
+      |## Unix socket file mode
+      |## When none is provided, 660 is applied by default
+      |# ALTER ROLE authenticator SET pgrst.server_unix_socket_mods = '660';
+      |]
+exampleConfig ExampleEnv =
+  [str|## Admin server used for checks. It's disabled by default unless a port is specified.
+      |# export PGRST_ADMIN_SERVER_PORT=3001
+      |
+      |## The database role to use when no client authentication is provided
+      |# export PGRST_DB_ANON_ROLE=root
+      |
+      |## Notification channel for reloading the schema cache
+      |export PGRST_DB_CHANNEL=postgrest
+      |
+      |## Enable or disable the notification channel
+      |export PGRST_DB_CHANNEL_ENABLED=false
+      |
+      |## Enable in-database configuration
+      |export PGRST_DB_CONFIG=false
+      |
+      |## Function for in-database configuration
+      |# export PGRST_DB_PRE_CONFIG='postgrest.pre_config'
+      |
+      |## Extra schemas to add to the search_path of every request
+      |export PGRST_DB_EXTRA_SEARCH_PATH='public'
+      |
+      |## Limit rows in response
+      |# export PGRST_DB_MAX_ROWS=1000
+      |
+      |## Allow getting the EXPLAIN plan through the `Accept: application/vnd.pgrst.plan` header
+      |# export PGRST_DB_PLAN_ENABLED=false
+      |
+      |## Number of open connections in the pool
+      |export PGRST_DB_POOL=10
+      |
+      |## Time in seconds to wait to acquire a slot from the connection pool
+      |# export PGRST_DB_POOL_ACQUISITION_TIMEOUT=10
+      |
+      |## Time in seconds after which to recycle pool connections
+      |# export PGRST_DB_POOL_MAX_LIFETIME=1800
+      |
+      |## Time in seconds after which to recycle unused pool connections
+      |# export PGRST_DB_POOL_MAX_IDLETIME=30
+      |
+      |## Allow automatic database connection retrying
+      |# export PGRST_DB_POOL_AUTOMATIC_RECOVERY=true
+      |
+      |## Stored proc to exec immediately after auth
+      |# export PGRST_DB_PRE_REQUEST='stored_proc_name'
+      |
+      |## Enable or disable prepared statements. disabling is only necessary when behind a connection pooler.
+      |## When disabled, statements will be parametrized but won't be prepared.
+      |export PGRST_DB_PREPARED_STATEMENTS=true
+      |
+      |## The name of which database schema to expose to REST clients
+      |export PGRST_DB_SCHEMAS='public'
+      |
+      |## How to terminate database transactions
+      |## Possible values are:
+      |## commit (default)
+      |##   Transaction is always committed, this can not be overriden
+      |## commit-allow-override
+      |##   Transaction is committed, but can be overriden with Prefer tx=rollback header
+      |## rollback
+      |##   Transaction is always rolled back, this can not be overriden
+      |## rollback-allow-override
+      |##   Transaction is rolled back, but can be overriden with Prefer tx=commit header
+      |export PGRST_DB_TX_END=commit
+      |
+      |## The standard connection URI format, documented at
+      |## https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
+      |export PGRST_DB_URI='postgresql://'
+      |
+      |# export PGRST_JWT_AUD='your_audience_claim'
+      |
+      |## Jspath to the role claim key
+      |export PGRST_JWT_ROLE_CLAIM_KEY='.role'
+      |
+      |## Choose a secret, JSON Web Key (or set) to enable JWT auth
+      |## (use "@filename" to load from separate file)
+      |# export PGRST_JWT_SECRET='secret_with_at_least_32_characters'
+      |
+      |export PGRST_JWT_SECRET_IS_BASE64=false
+      |
+      |## Enables and set JWT Cache max lifetime, disables caching with 0
+      |# export PGRST_JWT_CACHE_MAX_LIFETIME=0
+      |
+      |## Logging level, the admitted values are: crit, error, warn and info.
+      |export PGRST_LOG_LEVEL=error
+      |
+      |## Determine if the OpenAPI output should follow or ignore role privileges or be disabled entirely.
+      |## Admitted values: follow-privileges, ignore-privileges, disabled
+      |export PGRST_OPENAPI_MODE='follow-privileges'
+      |
+      |## Base url for the OpenAPI output
+      |export PGRST_OPENAPI_SERVER_PROXY_URI=''
+      |
+      |## Configurable CORS origins
+      |# export PGRST_SERVER_CORS_ALLOWED_ORIGINS=''
+      |
+      |export PGRST_SERVER_HOST=!4
+      |
+      |export PGRST_SERVER_PORT=3000
+      |
+      |## Allow getting the request-response timing information through the `Server-Timing` header
+      |export PGRST_SERVER_TIMING_ENABLED=false
+      |
+      |export PGRST_SERVER_TRACE_HEADER=X-Request-Id
+      |
+      |## Unix socket location
+      |## if specified it takes precedence over server-port
+      |# export PGRST_SERVER_UNIX_SOCKET='/tmp/pgrst.sock'
+      |
+      |## Unix socket file mode
+      |## When none is provided, 660 is applied by default
+      |# export PGRST_SERVER_UNIX_SOCKET_MODE=660
+      |]