feat: add more config examples to CLI

CHANGELOG.md

@@ -21,6 +21,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
  - #3404, Show extra information in the `PGRST121` (could not parse RAISE 'PGRST') error - @laurenceisla
    + Shows the failed MESSAGE or DETAIL in the `details` field
    + Shows the correct JSON format in the `hints` field
+ - #3248, Add more config examples to CLI - @taimoorzaeem
+   + Now accepts ``--example-file``, ``--example-db``, and ``--example-env``
 
 ### Fixed
 

docs/references/cli.rst

@@ -23,9 +23,11 @@ Example Config
 
 .. code:: bash
 
-  $ postgrest [-e|--example]
+  $ postgrest [--example-file]
+  $ postgrest [--example-db]
+  $ postgrest [--example-env]
 
-These commands show the example configuration file.
+These commands show the example configuration files.
 
 Config
 ~~~~~~
@@ -41,6 +43,6 @@ Schema Cache
 
 .. code:: bash
 
-  $ postgrest [--dump-schema] [FILENAME]
+  $ postgrest [--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,27 @@ readCLIShowHelp =
         <> O.short 'v'
         <> O.help "Show the version information"
 
-    exampleParser =
-      O.infoOption exampleConfigFile $
-        O.long "example"
-        <> O.short 'e'
-        <> O.help "Show an example configuration file"
+    exampleParser = exampleParserFile <|> exampleParserDb <|> exampleParserEnv
+
+    exampleParserFile =
+      O.infoOption (exampleConfig ExampleFile) $
+        O.long "example-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 +129,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 +212,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 +245,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
+      |]

test/io/fixtures.yaml

@@ -8,14 +8,16 @@ cli:
     args: ['--version']
   - name: version short
     args: ['-v']
-  - name: example long
-    args: ['--example']
-  - name: example short
-    args: ['-e']
+  - name: example file long
+    args: ['--example-file']
+  - name: example db long
+    args: ['--example-db']
+  - name: example env long
+    args: ['--example-env']
   - name: dump config
     args: ['--dump-config']
   - name: dump schema
-    args: ['--dump-schema']
+    args: ['--dump-schema-cache']
     use_defaultenv: true
   - name: no config
 # failures: config files

test/io/test_cli.py

@@ -261,7 +261,9 @@ def test_invalid_openapi_mode(invalidopenapimodes, defaultenv):
 def test_schema_cache_snapshot(baseenv, key, snapshot_yaml):
     "Dump of schema cache should match snapshot."
 
-    schema_cache = yaml.load(cli(["--dump-schema"], env=baseenv), Loader=yaml.Loader)
+    schema_cache = yaml.load(
+        cli(["--dump-schema-cache"], env=baseenv), Loader=yaml.Loader
+    )
     formatted = yaml.dump(
         schema_cache[key],
         encoding="utf8",