feat: add more config examples to CLI

PostgREST · Jun 2, 2024 · 380b2ca · 380b2ca
1 parent 50b2d30
commit 380b2ca
Show file tree

Hide file tree

Showing 5 changed files with 249 additions and 14 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,6 +23,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
  - #3184, Log full pg version to stderr on connection - @steve-chavez
  - #3242. Add config `db-hoisted-tx-settings` to apply only hoisted function settings - @taimoorzaeem
  - #3214, #3229 Log connection pool events on log-level=debug - @steve-chavez, @laurenceisla
+ - #3248, Add more config examples to CLI - @taimoorzaeem
+   + Now accepts ``--example-file``, ``--example-db``, and ``--example-env``
 
 ### Fixed
 
@@ -43,6 +45,10 @@ This project adheres to [Semantic Versioning](http://semver.org/).
  - #3255, Fix incorrect `413 Request Entity Too Large` on pg errors `54*` - @taimoorzaeem
  - #3549, Remove verbosity from error logs starting with "An error occurred..." and replacing it with "Failed to..." - @laurenceisla
 
+### Changed
+ - #3248, Modified some CLI options - @taimoorzaeem
+   + Replace ``-e`` and ``--example`` with ``--example-file``
+
 ### Deprecated
 
  - `Prefer: params=single-object` is deprecated. Use [a function with a single unnamed JSON parameter](https://postgrest.org/en/latest/references/api/functions.html#function-single-json) instead. - @steve-chavez

diff --git a/docs/references/cli.rst b/docs/references/cli.rst
@@ -28,7 +28,9 @@ Example
 
 .. code:: bash
 
-  $ postgrest [-e|--example]
+  $ postgrest [--example-file]
+  $ postgrest [--example-db]
+  $ postgrest [--example-env]
 
 Shows example configuration options.
 

diff --git a/docs/references/configuration.rst b/docs/references/configuration.rst
@@ -50,7 +50,7 @@ The configuration file must contain a set of key value pairs:
   # Port the postgrest process is listening on for http requests
   server-port = 3000
 
-You can run ``postgrest --example`` to display all possible configuration parameters and how to use them in a configuration file.
+You can run ``postgrest --example-file`` to display all possible configuration parameters and how to use them in a configuration file.
 
 .. _env_variables_config:
 

diff --git a/src/PostgREST/CLI.hs b/src/PostgREST/CLI.hs
@@ -73,6 +73,8 @@ data Command
   | CmdDumpConfig
   | CmdDumpSchema
 
+data Example = ExampleFile | ExampleDb | ExampleEnv
+
 -- | Read command line interface options. Also prints help.
 readCLIShowHelp :: IO CLI
 readCLIShowHelp =
@@ -94,11 +96,22 @@ 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 =
@@ -121,11 +134,14 @@ readCLIShowHelp =
         O.long "dump-schema"
         <> 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
       |
+      |## Enables the aggregate functions in postgresql
+      |db-aggregates-enabled = "false"
+      |
       |## The database role to use when no client authentication is provided
       |# db-anon-role = "anon"
       |
@@ -139,7 +155,7 @@ exampleConfigFile =
       |db-config = true
       |
       |## Function for in-database configuration
-      |## db-pre-config = "postgrest.pre_config"
+      |# db-pre-config = "postgrest.pre_config"
       |
       |## Extra schemas to add to the search_path of every request
       |db-extra-search-path = "public"
@@ -172,6 +188,9 @@ exampleConfigFile =
       |## When disabled, statements will be parametrized but won't be prepared.
       |db-prepared-statements = true
       |
+      |## Function to override OpenAPI response
+      |# db-root-spec = "root"
+      |
       |## The name of which database schema to expose to REST clients
       |db-schemas = "public"
       |
@@ -211,6 +230,9 @@ exampleConfigFile =
       |## Admitted values: follow-privileges, ignore-privileges, disabled
       |openapi-mode = "follow-privileges"
       |
+      |## Include security options in OpenAPI output
+      |openapi-security-active = "false"
+      |
       |## Base url for the OpenAPI output
       |openapi-server-proxy-uri = ""
       |
@@ -220,6 +242,9 @@ exampleConfigFile =
       |server-host = "!4"
       |server-port = 3000
       |
+      |## Trace HTTP request header
+      |# server-trace-header = "X-Request-Id"
+      |
       |## Allow getting the request-response timing information through the `Server-Timing` header
       |server-timing-enabled = false
       |
@@ -231,3 +256,203 @@ exampleConfigFile =
       |## When none is provided, 660 is applied by default
       |# server-unix-socket-mode = "660"
       |]
+exampleConfig ExampleDb =
+  [str|-- Enables the aggregate functions in postgresql
+      |ALTER ROLE authenticator SET pgrst.db_aggregates_enabled = 'false';
+      |
+      |-- The database role to use when no client authentication is provided
+      |-- ALTER ROLE authenticator SET pgrst.db_anon_role = 'anon';
+      |
+      |-- 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';
+      |
+      |-- 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';
+      |
+      |-- Function to override the OpenAPI response
+      |-- ALTER ROLE authenticator SET pgrst.db_root_spec = 'root';
+      |
+      |-- 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'
+      |
+      |-- Specify the JWT Audience Claim
+      |-- ALTER ROLE authenticator SET pgrst.jwt_aud = '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';
+      |
+      |-- 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';
+      |
+      |-- Include security options in OpenAPI output
+      |ALTER ROLE authenticator SET pgrst.openapi_security_active = 'false'
+      |
+      |-- 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 = '';
+      |
+      |-- Trace HTTP request header
+      |-- ALTER ROLE authenticator SET pgrst.server_trace_header = 'X-Request-Id';
+      |
+      |-- Allow getting the request-response timing information through the `Server-Timing` header
+      |ALTER ROLE authenticator SET pgrst.server_timing_enabled = 'false';
+      |]
+exampleConfig ExampleEnv =
+  [str|## Admin server used for checks. It's disabled by default unless a port is specified.
+      |# PGRST_ADMIN_SERVER_PORT=3001
+      |
+      |## Enables the aggregate function in postgresql
+      |PGRST_DB_AGGREGATES_ENABLED='false'
+      |
+      |## The database role to use when no client authentication is provided
+      |# PGRST_DB_ANON_ROLE=root
+      |
+      |## Notification channel for reloading the schema cache
+      |PGRST_DB_CHANNEL=postgrest
+      |
+      |## Enable or disable the notification channel
+      |PGRST_DB_CHANNEL_ENABLED=false
+      |
+      |## Enable in-database configuration
+      |PGRST_DB_CONFIG=false
+      |
+      |## Function for in-database configuration
+      |# PGRST_DB_PRE_CONFIG='postgrest.pre_config'
+      |
+      |## Extra schemas to add to the search_path of every request
+      |PGRST_DB_EXTRA_SEARCH_PATH='public'
+      |
+      |## Limit rows in response
+      |# PGRST_DB_MAX_ROWS=1000
+      |
+      |## Allow getting the EXPLAIN plan through the `Accept: application/vnd.pgrst.plan` header
+      |# PGRST_DB_PLAN_ENABLED=false
+      |
+      |## Number of open connections in the pool
+      |PGRST_DB_POOL=10
+      |
+      |## Time in seconds to wait to acquire a slot from the connection pool
+      |# PGRST_DB_POOL_ACQUISITION_TIMEOUT=10
+      |
+      |## Time in seconds after which to recycle pool connections
+      |# PGRST_DB_POOL_MAX_LIFETIME=1800
+      |
+      |## Time in seconds after which to recycle unused pool connections
+      |# PGRST_DB_POOL_MAX_IDLETIME=30
+      |
+      |## Allow automatic database connection retrying
+      |# PGRST_DB_POOL_AUTOMATIC_RECOVERY=true
+      |
+      |## Stored proc to exec immediately after auth
+      |# 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.
+      |PGRST_DB_PREPARED_STATEMENTS=true
+      |
+      |## Function to override the OpenAPI response
+      |# PGRST_DB_ROOT_SPEC='root'
+      |
+      |## The name of which database schema to expose to REST clients
+      |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
+      |PGRST_DB_TX_END=commit
+      |
+      |## The standard connection URI format, documented at
+      |## https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
+      |PGRST_DB_URI='postgresql://'
+      |
+      |# PGRST_JWT_AUD='your_audience_claim'
+      |
+      |## Jspath to the role claim key
+      |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)
+      |# PGRST_JWT_SECRET='secret_with_at_least_32_characters'
+      |
+      |PGRST_JWT_SECRET_IS_BASE64=false
+      |
+      |## Enables and set JWT Cache max lifetime, disables caching with 0
+      |# PGRST_JWT_CACHE_MAX_LIFETIME=0
+      |
+      |## Logging level, the admitted values are: crit, error, warn and info.
+      |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
+      |PGRST_OPENAPI_MODE='follow-privileges'
+      |
+      |## Include security options in OpenAPI output
+      |PGRST_OPENAPI_SECURITY_ACTIVE='false'
+      |
+      |## Base url for the OpenAPI output
+      |PGRST_OPENAPI_SERVER_PROXY_URI=''
+      |
+      |## Configurable CORS origins
+      |# PGRST_SERVER_CORS_ALLOWED_ORIGINS=''
+      |
+      |PGRST_SERVER_HOST=!4
+      |PGRST_SERVER_PORT=3000
+      |
+      |## Trace HTTP request header
+      |# PGRST_SERVER_TRACE_HEADER='X-Request-Id'
+      |
+      |## Allow getting the request-response timing information through the `Server-Timing` header
+      |PGRST_SERVER_TIMING_ENABLED=false
+      |
+      |## Unix socket location
+      |## if specified it takes precedence over server-port
+      |# PGRST_SERVER_UNIX_SOCKET='/tmp/pgrst.sock'
+      |
+      |## Unix socket file mode
+      |## When none is provided, 660 is applied by default
+      |# PGRST_SERVER_UNIX_SOCKET_MODE=660
+      |]
diff --git a/test/io/fixtures.yaml b/test/io/fixtures.yaml
@@ -8,10 +8,12 @@ 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