diff --git a/CHANGELOG.md b/CHANGELOG.md index 67debfab91..0269de9cf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ This project adheres to [Semantic Versioning](http://semver.org/). - #3435, Add log-level=debug, for development purposes - @steve-chavez - #1526, Add `/metrics` endpoint on admin server - @steve-chavez - Exposes connection pool metrics, schema cache metrics + - #3248, Add more config examples to CLI - @taimoorzaeem + + Now accepts ``--example-file``, ``--example-db``, and ``--example-env`` + + Add docs page for CLI ### Fixed diff --git a/docs/index.rst b/docs/index.rst index 16c3508b45..b0fb672cbc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -147,6 +147,7 @@ Technical references for PostgREST's functionality. references/auth.rst references/api.rst + references/cli.rst references/transactions.rst references/connection_pool.rst references/schema_cache.rst diff --git a/docs/postgrest.dict b/docs/postgrest.dict index 63d935ec6b..d24804de56 100644 --- a/docs/postgrest.dict +++ b/docs/postgrest.dict @@ -15,6 +15,7 @@ Cardano casted cd centric +CLI coercible conf Cloudflare diff --git a/docs/references/cli.rst b/docs/references/cli.rst new file mode 100644 index 0000000000..1bbbdc98e5 --- /dev/null +++ b/docs/references/cli.rst @@ -0,0 +1,41 @@ +.. _cli: + +CLI +=== + +PostgREST provides a CLI to start and run your postgrest service. The CLI provides the commands listed below: + +.. _cli_commands: + +CLI Commands +------------ + +Help and Version +~~~~~~~~~~~~~~~~ + +.. code:: bash + + $ postgrest [-h|--help] + $ postgrest [-v|--version] + + +Example Config +~~~~~~~~~~~~~~ + +.. code:: bash + + $ postgrest [--example-file] + $ postgrest [--example-db] + $ postgrest [--example-env] + +These commands show the example configuration file of the selected type. + + +Config or Schema Cache +~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + $ postgrest [--dump-config|--dump-schema-cache] [FILENAME] + +Here ``FILENAME`` is the path to configuration file. diff --git a/src/PostgREST/CLI.hs b/src/PostgREST/CLI.hs index 9550bc3f18..82ccb35623 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 @@ -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,28 @@ readCLIShowHelp = <> O.short 'v' <> O.help "Show the version information" - exampleParser = - O.infoOption exampleConfigFile $ - O.long "example" + exampleParser = exampleParserFile <|> exampleParserDb <|> exampleParserEnv + + exampleParserFile = + O.infoOption (exampleConfig ExampleFile) $ + O.long "example-file" <> O.short 'e' - <> O.help "Show an example configuration 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 +130,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 +213,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 +246,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 + |] 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",