Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: add more config examples to CLI #3481

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+262 −24
Open

feat: add more config examples to CLI #3481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
380b2ca
feat: add more config examples to CLI
taimoorzaeem May 12, 2024
c1d67b6
chore: rename option --dump-schema to --dump-schema-cache
taimoorzaeem Jun 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Comment on lines +26 to +27
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You also have two changes here, one to rename the dump schema cache command and the other to remove --example and -e. Those should probably go into the changed section as well.


### Fixed

Expand All @@ -43,6 +45,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
Expand Down
6 changes: 4 additions & 2 deletions docs/references/cli.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,9 @@ Example

.. code:: bash

$ postgrest [-e|--example]
$ postgrest [--example-file]
$ postgrest [--example-db]
$ postgrest [--example-env]

Shows example configuration options.

Expand All @@ -46,6 +48,6 @@ Dump Schema

.. code:: bash

$ postgrest [--dump-schema]
$ postgrest [--dump-schema-cache]

Dumps the schema cache in JSON format.
2 changes: 1 addition & 1 deletion docs/references/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion nix/tools/tests.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
253 changes: 239 additions & 14 deletions src/PostgREST/CLI.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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 =
Expand All @@ -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"
wolfgangwalther marked this conversation as resolved.
Show resolved Hide resolved
<> 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"
|
Expand All @@ -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"
Expand Down Expand Up @@ -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"
|
Expand Down Expand Up @@ -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 = ""
|
Expand All @@ -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
|
Expand All @@ -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
|]