From 380b2caed9b0b3cff7d25813fe8382afce91c0c6 Mon Sep 17 00:00:00 2001 From: Taimoor Zaeem Date: Mon, 13 May 2024 00:42:32 +0500 Subject: [PATCH] feat: add more config examples to CLI --- CHANGELOG.md | 6 + docs/references/cli.rst | 4 +- docs/references/configuration.rst | 2 +- src/PostgREST/CLI.hs | 241 +++++++++++++++++++++++++++++- test/io/fixtures.yaml | 10 +- 5 files changed, 249 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfbe9e708e..73053b00b2 100644 --- 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 index 8cc8c6c60e..da04fb7c7c 100644 --- 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 index 2740e70537..18035ee713 100644 --- 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 index c4f18d5477..5259d2636e 100644 --- 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 index 5c738d7c14..75aff7f45f 100644 --- 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