diff --git a/CHANGELOG.md b/CHANGELOG.md index 5928ba1761..3aaf08ecb6 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 @@ -42,6 +44,11 @@ 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`` + + Rename option ``--dump-schema`` to ``--dump-schema-cache`` + ### 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..5b4b5683cc 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. @@ -46,6 +48,6 @@ Dump Schema .. code:: bash - $ postgrest [--dump-schema] + $ postgrest [--dump-schema-cache] Dumps the schema cache in JSON format. 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/nix/tools/tests.nix b/nix/tools/tests.nix index f842b7948c..65c5efdbcf 100644 --- a/nix/tools/tests.nix +++ b/nix/tools/tests.nix @@ -128,7 +128,7 @@ let '' ${withTools.withPg} -f test/spec/fixtures/load.sql \ ${cabal-install}/bin/cabal v2-run ${devCabalOptions} --verbose=0 -- \ - postgrest --dump-schema + postgrest --dump-schema-cache ''; coverage = diff --git a/src/PostgREST/CLI.hs b/src/PostgREST/CLI.hs index c4f18d5477..95c35a7e07 100644 --- a/src/PostgREST/CLI.hs +++ b/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 @@ -71,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 @@ -94,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 = @@ -116,16 +129,19 @@ 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 | + |## 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..0fd83e46ac 100644 --- a/test/io/fixtures.yaml +++ b/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 diff --git a/test/io/test_cli.py b/test/io/test_cli.py index a85a0111c2..f00828201d 100644 --- a/test/io/test_cli.py +++ b/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",