docs: Add CLI page to docs

PostgREST · Mar 9, 2024 · 3f92625 · 3f92625
1 parent 650249e
commit 3f92625
Show file tree

Hide file tree

Showing 4 changed files with 251 additions and 20 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
  - #3171, #3046, Log schema cache stats to stderr - @steve-chavez
  - #3210, Dump schema cache through admin API - @taimoorzaeem
  - #2676, Performance improvement on bulk json inserts, around 10% increase on requests per second by removing `json_typeof` from write queries - @steve-chavez
+ - #3248, Add CLI page to docs - @taimoorzaeem
+   + Add config type to ``--example`` in CLI
 
 ### Fixed
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -124,15 +124,16 @@ Technical references for PostgREST's functionality.
    :name: references
    :maxdepth: 1
 
-   references/auth.rst
    references/api.rst
-   references/transactions.rst
+   references/auth.rst
+   references/cli.rst
+   references/configuration.rst
    references/connection_pool.rst
-   references/schema_cache.rst
    references/errors.rst
-   references/configuration.rst
-   references/observability.rst
    references/health_check.rst
+   references/observability.rst
+   references/schema_cache.rst
+   references/transactions.rst
 
 Explanations
 ------------

diff --git a/docs/references/cli.rst b/docs/references/cli.rst
@@ -0,0 +1,40 @@
+.. _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 Configs
+~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+  $ postgrest [-e|--example] (file|db|env)
+
+This command shows the type of example configuration file.
+
+
+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
@@ -31,7 +31,7 @@ import Protolude hiding (hPutStrLn)
 
 
 main :: CLI -> IO ()
-main CLI{cliCommand, cliPath} = do
+main CLICommand{cliCommand, cliPath} = do
   conf@AppConfig{..} <-
     either panic identity <$> Config.readAppConfig mempty cliPath Nothing mempty mempty
 
@@ -46,8 +46,21 @@ main CLI{cliCommand, cliPath} = do
       CmdDumpConfig -> do
         when configDbConfig $ AppState.reReadConfig True appState (const $ pure ())
         putStr . Config.toText =<< AppState.getConfig appState
-      CmdDumpSchema -> putStrLn =<< dumpSchema appState
+      CmdDumpSchemaCache -> putStrLn =<< dumpSchema appState
       CmdRun -> App.run appState (Logger.logObservation loggerState))
+main CLIExample{exampleType} = do
+  conf <-
+    either panic identity <$> Config.readAppConfig mempty mempty Nothing mempty mempty
+
+  loggerState <- Logger.init
+  bracket
+    (AppState.init conf $ Logger.logObservation loggerState)
+    AppState.destroy
+    (\_ -> case exampleType of
+      "file" -> putStrLn exampleConfigFile
+      "db" -> putStrLn exampleConfigDb
+      "env" -> putStrLn exampleConfigEnv
+      _     -> putStrLn ("Usage: postgrest-run --example/-e file/db/env" :: [Char]))
 
 -- | Dump SchemaCache schema to JSON
 dumpSchema :: AppState -> IO LBS.ByteString
@@ -65,15 +78,23 @@ dumpSchema appState = do
     Right sCache -> return $ JSON.encode sCache
 
 -- | Command line interface options
-data CLI = CLI
+data CLI = 
+    CLICommand
   { cliCommand :: Command
   , cliPath    :: Maybe FilePath
   }
+  | CLIExample
+  { cliExample  :: Example
+  , exampleType :: [Char] }
+
+data Example 
+  = ExampleRun 
+  | ShowExample
 
 data Command
   = CmdRun
   | CmdDumpConfig
-  | CmdDumpSchema
+  | CmdDumpSchemaCache
 
 -- | Read command line interface options. Also prints help.
 readCLIShowHelp :: IO CLI
@@ -82,7 +103,7 @@ readCLIShowHelp =
   where
     prefs = O.prefs $ O.showHelpOnError <> O.showHelpOnEmpty
     opts = O.info parser $ O.fullDesc <> progDesc
-    parser = O.helper <*> versionFlag <*> exampleParser <*> cliParser
+    parser = O.helper <*> versionFlag <*> (exampleParser <|> cliParser)
 
     progDesc =
       O.progDesc $
@@ -96,16 +117,21 @@ 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 :: O.Parser CLI
+    exampleParser = 
+      CLIExample 
+        <$> showExample
+        <*> exampleConfig
+
+    exampleConfig =
+      O.strArgument $
+        O.metavar "ExampleType"
+        <> O.help "Type of config file/db/env"
 
     cliParser :: O.Parser CLI
     cliParser =
-      CLI
-        <$> (dumpConfigFlag <|> dumpSchemaFlag)
+      CLICommand
+        <$> (dumpConfigFlag <|> dumpSchemaCacheFlag)
         <*> O.optional configFileOption
 
     configFileOption =
@@ -118,11 +144,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)"
 
+    showExample =
+      O.flag ExampleRun ShowExample $
+        O.long "example"
+        <> O.short 'e'
+        <> O.help "Show config example"
+
+
+-- Shown in CLI "--example file"
 exampleConfigFile :: [Char]
 exampleConfigFile =
   [str|## Admin server used for checks. It's disabled by default unless a port is specified.
@@ -233,3 +267,157 @@ exampleConfigFile =
       |## When none is provided, 660 is applied by default
       |# server-unix-socket-mode = "660"
       |]
+
+-- Shown in CLI "--example db"
+exampleConfigDb :: [Char]
+exampleConfigDb = 
+  [str|## reloadable config options
+      |ALTER ROLE db_config_authenticator SET pgrst.admin_server_port = '3001';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_anon_role = 'anon';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_channel = 'pgrst';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_channel_enabled = 'true';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_config = 'true';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pre_config = 'postgrest.pre_config';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_extra_search_path = 'public';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_max_rows = '1000';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_plan_enabled = 'false';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pool = '10';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pool_acquisition_timeout = '10';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pool_max_lifetime = '1800';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pool_max_idletime = '30';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pool_automatic_recovery = 'true';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_pre_request = 'stored_proc_name';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_prepared_statements = 'true';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_schemas = 'public';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_tx_end = 'commit';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.db_uri = 'postgresql://';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.jwt_aut = 'your_audience_claim';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.jwt_role_claim_key = '.role';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.jwt_secret_is_base64 = 'false';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.jwt_cache_max_lifetime = '0';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.log_level = 'error';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.openapi_mode = 'follow-privileges';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.openapi_server_proxy_uri = '';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.server_cors_allowed_origins = '';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.server_host = '!4';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.server_port = '3000';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.server_timing_enabled = 'false';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.server_unix_socket = '/tmp/pgrst.sock';
+      |
+      |ALTER ROLE db_config_authenticator SET pgrst.server_unix_socket_mods = '660';
+      |]
+
+-- Shown in CLI "--example env"
+exampleConfigEnv :: [Char]
+exampleConfigEnv = 
+  [str|## example env config
+      |PGRST_APP_SETTINGS_test2: test
+      |
+      |PGRST_APP_SETTINGS_test: test
+      |
+      |PGRST_DB_AGGREGATES_ENABLED: true
+      |
+      |PGRST_DB_ANON_ROLE: root
+      |
+      |PGRST_DB_CHANNEL: postgrest
+      |
+      |PGRST_DB_CHANNEL_ENABLED: false
+      |
+      |PGRST_DB_EXTRA_SEARCH_PATH: public, test
+      |
+      |PGRST_DB_MAX_ROWS: 1000
+      |
+      |PGRST_DB_PLAN_ENABLED: true
+      |
+      |PGRST_DB_POOL: 1
+      |
+      |PGRST_DB_POOL_ACQUISITION_TIMEOUT: 30
+      |
+      |PGRST_DB_POOL_MAX_LIFETIME: 3600
+      |
+      |PGRST_DB_POOL_MAX_IDLETIME: 60
+      |
+      |PGRST_DB_POOL_AUTOMATIC_RECOVERY: false
+      |
+      |PGRST_DB_PREPARED_STATEMENTS: false
+      |
+      |PGRST_DB_PRE_REQUEST: please_run_fast
+      |
+      |PGRST_DB_ROOT_SPEC: openapi_v3
+      |
+      |PGRST_DB_SCHEMAS: multi,   tenant,setup
+      |
+      |PGRST_DB_CONFIG: false
+      |
+      |PGRST_DB_PRE_CONFIG: "postgrest.pre_config"
+      |
+      |PGRST_DB_TX_END: rollback-allow-override
+      |
+      |PGRST_DB_URI: tmp_db
+      |
+      |PGRST_DB_USE_LEGACY_GUCS: false
+      |
+      |PGRST_JWT_AUD: 'https://postgrest.org'
+      |
+      |PGRST_JWT_ROLE_CLAIM_KEY: '.user[0]."real-role"'
+      |
+      |PGRST_JWT_SECRET: c2VjdXJpdHl0aHJvdWdob2JzY3VyaXR5
+      |
+      |PGRST_JWT_SECRET_IS_BASE64: true
+      |
+      |PGRST_JWT_CACHE_MAX_LIFETIME: 86400
+      |
+      |PGRST_LOG_LEVEL: info
+      |
+      |PGRST_OPENAPI_MODE: 'ignore-privileges'
+      |
+      |PGRST_OPENAPI_SECURITY_ACTIVE: true
+      |
+      |PGRST_OPENAPI_SERVER_PROXY_URI: 'https://postgrest.org'
+      |
+      |PGRST_SERVER_CORS_ALLOWED_ORIGINS: "http://example.com"
+      |
+      |PGRST_SERVER_HOST: 0.0.0.0
+      |
+      |PGRST_SERVER_PORT: 80
+      |
+      |PGRST_SERVER_TRACE_HEADER: X-Request-Id
+      |
+      |PGRST_SERVER_TIMING_ENABLED: true
+      |
+      |PGRST_SERVER_UNIX_SOCKET: /tmp/pgrst_io_test.sock
+      |
+      |PGRST_SERVER_UNIX_SOCKET_MODE: 777
+      |
+      |PGRST_ADMIN_SERVER_PORT: 3001
+      |]