Skip to content

Commit 2263bc0

Browse files
taimoorzaeemtaimoorzaeem
committed
feat: add more config examples to CLI
1 parent d9a51f2 commit 2263bc0

File tree

5 files changed

+269
-22
lines changed

5 files changed

+269
-22
lines changed

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
2121
- #3404, Show extra information in the `PGRST121` (could not parse RAISE 'PGRST') error - @laurenceisla
2222
+ Shows the failed MESSAGE or DETAIL in the `details` field
2323
+ Shows the correct JSON format in the `hints` field
24+
- #3248, Add more config examples to CLI - @taimoorzaeem
25+
+ Now accepts ``--example-file``, ``--example-db``, and ``--example-env``
2426

2527
### Fixed
2628

‎docs/references/cli.rst

+5-3
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,11 @@ Example Config
2323

2424
.. code:: bash
2525
26-
$ postgrest [-e|--example]
26+
$ postgrest [--example-file]
27+
$ postgrest [--example-db]
28+
$ postgrest [--example-env]
2729
28-
These commands show the example configuration file.
30+
These commands show the example configuration files.
2931

3032
Config
3133
~~~~~~
@@ -41,6 +43,6 @@ Schema Cache
4143

4244
.. code:: bash
4345
44-
$ postgrest [--dump-schema] [FILENAME]
46+
$ postgrest [--dump-schema-cache] [FILENAME]
4547
4648
Here ``FILENAME`` is the path to configuration file.

‎src/PostgREST/CLI.hs

+252-13
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ main CLI{cliCommand, cliPath} = do
4444
CmdDumpConfig -> do
4545
when configDbConfig $ AppState.reReadConfig True appState
4646
putStr . Config.toText =<< AppState.getConfig appState
47-
CmdDumpSchema -> putStrLn =<< dumpSchema appState
47+
CmdDumpSchemaCache -> putStrLn =<< dumpSchema appState
4848
CmdRun -> App.run appState)
4949

5050
-- | Dump SchemaCache schema to JSON
@@ -61,6 +61,7 @@ dumpSchema appState = do
6161
exitFailure
6262
Right sCache -> return $ JSON.encode sCache
6363

64+
6465
-- | Command line interface options
6566
data CLI = CLI
6667
{ cliCommand :: Command
@@ -70,7 +71,9 @@ data CLI = CLI
7071
data Command
7172
= CmdRun
7273
| CmdDumpConfig
73-
| CmdDumpSchema
74+
| CmdDumpSchemaCache
75+
76+
data Example = ExampleFile | ExampleDb | ExampleEnv
7477

7578
-- | Read command line interface options. Also prints help.
7679
readCLIShowHelp :: IO CLI
@@ -93,16 +96,27 @@ readCLIShowHelp =
9396
<> O.short 'v'
9497
<> O.help "Show the version information"
9598

96-
exampleParser =
97-
O.infoOption exampleConfigFile $
98-
O.long "example"
99-
<> O.short 'e'
100-
<> O.help "Show an example configuration file"
99+
exampleParser = exampleParserFile <|> exampleParserDb <|> exampleParserEnv
100+
101+
exampleParserFile =
102+
O.infoOption (exampleConfig ExampleFile) $
103+
O.long "example-file"
104+
<> O.help "Show an example of a configuration file"
105+
106+
exampleParserDb =
107+
O.infoOption (exampleConfig ExampleDb) $
108+
O.long "example-db"
109+
<> O.help "Show an example of in-database configuration"
110+
111+
exampleParserEnv =
112+
O.infoOption (exampleConfig ExampleEnv) $
113+
O.long "example-env"
114+
<> O.help "Show an example of environment variables configuration"
101115

102116
cliParser :: O.Parser CLI
103117
cliParser =
104118
CLI
105-
<$> (dumpConfigFlag <|> dumpSchemaFlag)
119+
<$> (dumpConfigFlag <|> dumpSchemaCacheFlag)
106120
<*> O.optional configFileOption
107121

108122
configFileOption =
@@ -115,13 +129,13 @@ readCLIShowHelp =
115129
O.long "dump-config"
116130
<> O.help "Dump loaded configuration and exit"
117131

118-
dumpSchemaFlag =
119-
O.flag CmdRun CmdDumpSchema $
120-
O.long "dump-schema"
132+
dumpSchemaCacheFlag =
133+
O.flag CmdRun CmdDumpSchemaCache $
134+
O.long "dump-schema-cache"
121135
<> O.help "Dump loaded schema as JSON and exit (for debugging, output structure is unstable)"
122136

123-
exampleConfigFile :: [Char]
124-
exampleConfigFile =
137+
exampleConfig :: Example -> [Char]
138+
exampleConfig ExampleFile =
125139
[str|## Admin server used for checks. It's disabled by default unless a port is specified.
126140
|# admin-server-port = 3001
127141
|
@@ -198,6 +212,7 @@ exampleConfigFile =
198212
|## Choose a secret, JSON Web Key (or set) to enable JWT auth
199213
|## (use "@filename" to load from separate file)
200214
|# jwt-secret = "secret_with_at_least_32_characters"
215+
|
201216
|jwt-secret-is-base64 = false
202217
|
203218
|## Enables and set JWT Cache max lifetime, disables caching with 0
@@ -230,3 +245,227 @@ exampleConfigFile =
230245
|## When none is provided, 660 is applied by default
231246
|# server-unix-socket-mode = "660"
232247
|]
248+
exampleConfig ExampleDb =
249+
[str|## Admin server used for checks. It's disabled by default unless a port is specified.
250+
|# ALTER ROLE authenticator SET pgrst.admin_server_port = '3001';
251+
|
252+
|## The database role to use when no client authentication is provided
253+
|# ALTER ROLE authenticator SET pgrst.db_anon_role = 'anon';
254+
|
255+
|## Notification channel for reloading the schema cache
256+
|ALTER ROLE authenticator SET pgrst.db_channel = 'pgrst';
257+
|
258+
|## Enable or disable the notification channel
259+
|ALTER ROLE authenticator SET pgrst.db_channel_enabled = 'true';
260+
|
261+
|## Enable in-database configuration
262+
|ALTER ROLE authenticator SET pgrst.db_config = 'true';
263+
|
264+
|## Function for in-database configuration
265+
|# ALTER ROLE authenticator SET pgrst.db_pre_config = 'postgrest.pre_config';
266+
|
267+
|## Extra schemas to add to the search_path of every request
268+
|ALTER ROLE authenticator SET pgrst.db_extra_search_path = 'public';
269+
|
270+
|## Limit rows in response
271+
|# ALTER ROLE authenticator SET pgrst.db_max_rows = '1000';
272+
|
273+
|## Allow getting the EXPLAIN plan through the `Accept: application/vnd.pgrst.plan` header
274+
|# ALTER ROLE authenticator SET pgrst.db_plan_enabled = 'false';
275+
|
276+
|## Number of open connections in the pool
277+
|ALTER ROLE authenticator SET pgrst.db_pool = '10';
278+
|
279+
|## Time in seconds to wait to acquire a slot from the connection pool
280+
|# ALTER ROLE authenticator SET pgrst.db_pool_acquisition_timeout = '10';
281+
|
282+
|## Time in seconds after which to recycle pool connections
283+
|# ALTER ROLE authenticator SET pgrst.db_pool_max_lifetime = '1800';
284+
|
285+
|## Time in seconds after which to recycle unused pool connections
286+
|# ALTER ROLE authenticator SET pgrst.db_pool_max_idletime = '30';
287+
|
288+
|## Allow automatic database connection retrying
289+
|# ALTER ROLE authenticator SET pgrst.db_pool_automatic_recovery = 'true';
290+
|
291+
|## Stored proc to exec immediately after auth
292+
|# ALTER ROLE authenticator SET pgrst.db_pre_request = 'stored_proc_name';
293+
|
294+
|## Enable or disable prepared statements. disabling is only necessary when behind a connection pooler.
295+
|## When disabled, statements will be parametrized but won't be prepared.
296+
|ALTER ROLE authenticator SET pgrst.db_prepared_statements = 'true';
297+
|
298+
|## The name of which database schema to expose to REST clients
299+
|ALTER ROLE authenticator SET pgrst.db_schemas = 'public';
300+
|
301+
|## How to terminate database transactions
302+
|## Possible values are:
303+
|## commit (default)
304+
|## Transaction is always committed, this can not be overriden
305+
|## commit-allow-override
306+
|## Transaction is committed, but can be overriden with Prefer tx=rollback header
307+
|## rollback
308+
|## Transaction is always rolled back, this can not be overriden
309+
|## rollback-allow-override
310+
|## Transaction is rolled back, but can be overriden with Prefer tx=commit header
311+
|ALTER ROLE authenticator SET pgrst.db_tx_end = 'commit';
312+
|
313+
|## The standard connection URI format, documented at
314+
|## https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
315+
|ALTER ROLE authenticator SET pgrst.db_uri = 'postgresql://';
316+
|
317+
|# ALTER ROLE authenticator SET pgrst.jwt_aut = 'your_audience_claim';
318+
|
319+
|## Jspath to the role claim key
320+
|ALTER ROLE authenticator SET pgrst.jwt_role_claim_key = '.role';
321+
|
322+
|## Choose a secret, JSON Web Key (or set) to enable JWT auth
323+
|## (use "@filename" to load from separate file)
324+
|# ALTER ROLE authenticator SET pgrst.jwt_secret = 'secret_with_at_least_32_characters'
325+
|
326+
|ALTER ROLE authenticator SET pgrst.jwt_secret_is_base64 = 'false';
327+
|
328+
|## Enables and set JWT Cache max lifetime, disables caching with 0
329+
|# ALTER ROLE authenticator SET pgrst.jwt_cache_max_lifetime = '0';
330+
|
331+
|## Logging level, the admitted values are: crit, error, warn and info.
332+
|ALTER ROLE authenticator SET pgrst.log_level = 'error';
333+
|
334+
|## Determine if the OpenAPI output should follow or ignore role privileges or be disabled entirely.
335+
|## Admitted values: follow-privileges, ignore-privileges, disabled
336+
|ALTER ROLE authenticator SET pgrst.openapi_mode = 'follow-privileges';
337+
|
338+
|## Base url for the OpenAPI output
339+
|ALTER ROLE authenticator SET pgrst.openapi_server_proxy_uri = '';
340+
|
341+
|## Configurable CORS origins
342+
|# ALTER ROLE authenticator SET pgrst.server_cors_allowed_origins = '';
343+
|
344+
|ALTER ROLE authenticator SET pgrst.server_host = '!4';
345+
|
346+
|ALTER ROLE authenticator SET pgrst.server_port = '3000';
347+
|
348+
|## Allow getting the request-response timing information through the `Server-Timing` header
349+
|ALTER ROLE authenticator SET pgrst.server_timing_enabled = 'false';
350+
|
351+
|## Unix socket location
352+
|## if specified it takes precedence over server-port
353+
|# ALTER ROLE authenticator SET pgrst.server_unix_socket = '/tmp/pgrst.sock';
354+
|
355+
|## Unix socket file mode
356+
|## When none is provided, 660 is applied by default
357+
|# ALTER ROLE authenticator SET pgrst.server_unix_socket_mods = '660';
358+
|]
359+
exampleConfig ExampleEnv =
360+
[str|## Admin server used for checks. It's disabled by default unless a port is specified.
361+
|# export PGRST_ADMIN_SERVER_PORT=3001
362+
|
363+
|## The database role to use when no client authentication is provided
364+
|# export PGRST_DB_ANON_ROLE=root
365+
|
366+
|## Notification channel for reloading the schema cache
367+
|export PGRST_DB_CHANNEL=postgrest
368+
|
369+
|## Enable or disable the notification channel
370+
|export PGRST_DB_CHANNEL_ENABLED=false
371+
|
372+
|## Enable in-database configuration
373+
|export PGRST_DB_CONFIG=false
374+
|
375+
|## Function for in-database configuration
376+
|# export PGRST_DB_PRE_CONFIG='postgrest.pre_config'
377+
|
378+
|## Extra schemas to add to the search_path of every request
379+
|export PGRST_DB_EXTRA_SEARCH_PATH='public'
380+
|
381+
|## Limit rows in response
382+
|# export PGRST_DB_MAX_ROWS=1000
383+
|
384+
|## Allow getting the EXPLAIN plan through the `Accept: application/vnd.pgrst.plan` header
385+
|# export PGRST_DB_PLAN_ENABLED=false
386+
|
387+
|## Number of open connections in the pool
388+
|export PGRST_DB_POOL=10
389+
|
390+
|## Time in seconds to wait to acquire a slot from the connection pool
391+
|# export PGRST_DB_POOL_ACQUISITION_TIMEOUT=10
392+
|
393+
|## Time in seconds after which to recycle pool connections
394+
|# export PGRST_DB_POOL_MAX_LIFETIME=1800
395+
|
396+
|## Time in seconds after which to recycle unused pool connections
397+
|# export PGRST_DB_POOL_MAX_IDLETIME=30
398+
|
399+
|## Allow automatic database connection retrying
400+
|# export PGRST_DB_POOL_AUTOMATIC_RECOVERY=true
401+
|
402+
|## Stored proc to exec immediately after auth
403+
|# export PGRST_DB_PRE_REQUEST='stored_proc_name'
404+
|
405+
|## Enable or disable prepared statements. disabling is only necessary when behind a connection pooler.
406+
|## When disabled, statements will be parametrized but won't be prepared.
407+
|export PGRST_DB_PREPARED_STATEMENTS=true
408+
|
409+
|## The name of which database schema to expose to REST clients
410+
|export PGRST_DB_SCHEMAS='public'
411+
|
412+
|## How to terminate database transactions
413+
|## Possible values are:
414+
|## commit (default)
415+
|## Transaction is always committed, this can not be overriden
416+
|## commit-allow-override
417+
|## Transaction is committed, but can be overriden with Prefer tx=rollback header
418+
|## rollback
419+
|## Transaction is always rolled back, this can not be overriden
420+
|## rollback-allow-override
421+
|## Transaction is rolled back, but can be overriden with Prefer tx=commit header
422+
|export PGRST_DB_TX_END=commit
423+
|
424+
|## The standard connection URI format, documented at
425+
|## https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
426+
|export PGRST_DB_URI='postgresql://'
427+
|
428+
|# export PGRST_JWT_AUD='your_audience_claim'
429+
|
430+
|## Jspath to the role claim key
431+
|export PGRST_JWT_ROLE_CLAIM_KEY='.role'
432+
|
433+
|## Choose a secret, JSON Web Key (or set) to enable JWT auth
434+
|## (use "@filename" to load from separate file)
435+
|# export PGRST_JWT_SECRET='secret_with_at_least_32_characters'
436+
|
437+
|export PGRST_JWT_SECRET_IS_BASE64=false
438+
|
439+
|## Enables and set JWT Cache max lifetime, disables caching with 0
440+
|# export PGRST_JWT_CACHE_MAX_LIFETIME=0
441+
|
442+
|## Logging level, the admitted values are: crit, error, warn and info.
443+
|export PGRST_LOG_LEVEL=error
444+
|
445+
|## Determine if the OpenAPI output should follow or ignore role privileges or be disabled entirely.
446+
|## Admitted values: follow-privileges, ignore-privileges, disabled
447+
|export PGRST_OPENAPI_MODE='follow-privileges'
448+
|
449+
|## Base url for the OpenAPI output
450+
|export PGRST_OPENAPI_SERVER_PROXY_URI=''
451+
|
452+
|## Configurable CORS origins
453+
|# export PGRST_SERVER_CORS_ALLOWED_ORIGINS=''
454+
|
455+
|export PGRST_SERVER_HOST=!4
456+
|
457+
|export PGRST_SERVER_PORT=3000
458+
|
459+
|## Allow getting the request-response timing information through the `Server-Timing` header
460+
|export PGRST_SERVER_TIMING_ENABLED=false
461+
|
462+
|export PGRST_SERVER_TRACE_HEADER=X-Request-Id
463+
|
464+
|## Unix socket location
465+
|## if specified it takes precedence over server-port
466+
|# export PGRST_SERVER_UNIX_SOCKET='/tmp/pgrst.sock'
467+
|
468+
|## Unix socket file mode
469+
|## When none is provided, 660 is applied by default
470+
|# export PGRST_SERVER_UNIX_SOCKET_MODE=660
471+
|]

‎test/io/fixtures.yaml

+7-5
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,16 @@ cli:
88
args: ['--version']
99
- name: version short
1010
args: ['-v']
11-
- name: example long
12-
args: ['--example']
13-
- name: example short
14-
args: ['-e']
11+
- name: example file long
12+
args: ['--example-file']
13+
- name: example db long
14+
args: ['--example-db']
15+
- name: example env long
16+
args: ['--example-env']
1517
- name: dump config
1618
args: ['--dump-config']
1719
- name: dump schema
18-
args: ['--dump-schema']
20+
args: ['--dump-schema-cache']
1921
use_defaultenv: true
2022
- name: no config
2123
# failures: config files

‎test/io/test_cli.py

+3-1
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,9 @@ def test_invalid_openapi_mode(invalidopenapimodes, defaultenv):
261261
def test_schema_cache_snapshot(baseenv, key, snapshot_yaml):
262262
"Dump of schema cache should match snapshot."
263263

264-
schema_cache = yaml.load(cli(["--dump-schema"], env=baseenv), Loader=yaml.Loader)
264+
schema_cache = yaml.load(
265+
cli(["--dump-schema-cache"], env=baseenv), Loader=yaml.Loader
266+
)
265267
formatted = yaml.dump(
266268
schema_cache[key],
267269
encoding="utf8",

0 commit comments

Comments
 (0)