[agroal#381] Changes to pgagroal-cli commands

This commit changes two commands in `pgagroal-cli`.

The `is-alive` command is deprecated by means of the `ping`
command. Documentation has been modified accordingly.

The `details` command is now deprecated by the `status details`
one. To achieve this, the `status details` is parsed _before_ the
`status` one (that has not changed at all). In order to better reflect
this change, the internal constant `ACTION_DETAILS` has been renamed
to `ACTION_STATUS_DETAIL`.

Documentation updated accordingly.
Shell completions updated accordingly.

Close agroal#381

contrib/shell_comp/pgagroal_comp.bash

@@ -10,7 +10,7 @@ pgagroal_cli_completions()
     if [ "${#COMP_WORDS[@]}" == "2" ]; then
         # main completion: the user has specified nothing at all
         # or a single word, that is a command
-        COMPREPLY=($(compgen -W "flush is-alive enable disable shutdown status details switch-to conf clear" "${COMP_WORDS[1]}"))
+        COMPREPLY=($(compgen -W "flush ping enable disable shutdown status switch-to conf clear" "${COMP_WORDS[1]}"))
     else
         # the user has specified something else
         # subcommand required?
@@ -27,6 +27,8 @@ pgagroal_cli_completions()
 	    conf)
 		COMPREPLY+=($(compgen -W "reload get set" "${COMP_WORDS[2]}"))
 		;;
+	    status)
+		COMPREPLY+=($(compgen -W "details" "${COMP_WORDS[2]}"))
         esac
     fi
 

contrib/shell_comp/pgagroal_comp.zsh

@@ -6,7 +6,7 @@ function _pgagroal_cli()
 {
     local line
     _arguments -C \
-               "1: :(flush is-alive enable disable shutdown status details switch-to conf clear)" \
+               "1: :(flush ping enable disable shutdown status switch-to conf clear)" \
                "*::arg:->args"
 
     case $line[1] in
@@ -22,6 +22,9 @@ function _pgagroal_cli()
 	conf)
 	    _pgagroal_cli_conf
 	    ;;
+	status)
+	    _pgagroal_cli_status
+	    ;;
     esac
 }
 
@@ -78,3 +81,11 @@ function _pgagroal_admin_user()
                "1: :(add del edit ls)" \
                "*::arg:->args"
 }
+
+function _pgagroal_cli_status()
+{
+    local line
+    _arguments -C \
+               "1: :(details)" \
+               "*::arg:->args"
+}

doc/CLI.md

@@ -59,19 +59,28 @@ pgagroal-cli flush all       # pgagroal-cli flush all '*'
 pgagroal-cli flush pgbench   # pgagroal-cli flush gracefully pgbench
 ```
 
-### is-alive
-Is pgagroal alive
+### ping
+The `ping` command checks if `pgagroal` is running.
+In case of success, the command does not print anything on the standard output unless the `--verbose` flag is used.
 
 Command
 
 ```
-pgagroal-cli is-alive
+pgagroal-cli ping
 ```
 
 Example
 
 ```
-pgagroal-cli is-alive
+pgagroal-cli ping --verbose  # pgagroal-cli: Success (0)
+pgagroal-cli ping            # $? = 0
+```
+
+In the case `pgagroal` is not running, a message is printed on the standard error and the exit status is set to a non-zero value:
+
+```
+pgagroal-cli ping          # $? = 1
+Connection error on /tmp
 ```
 
 ### enable
@@ -131,7 +140,8 @@ pgagroal-cli shutdown cancel  # stops the above command
 
 
 ### status
-Status of pgagroal
+The `status` command reports the current status of the `pgagroal` pooler.
+Without any subcommand, `status` reports back a short set of information about the pooler.
 
 Command
 
@@ -143,21 +153,15 @@ Example
 
 ```
 pgagroal-cli status
-```
-
-### details
-Detailed status of pgagroal
-
-Command
 
 ```
-pgagroal-cli details
-```
+
+With the `details` subcommand, a more verbose output is printed with a detail about every connection.
 
 Example
 
 ```
-pgagroal-cli details
+pgagroal-cli status details
 ```
 
 ### switch-to
@@ -334,7 +338,9 @@ to the working command:
 - `reset` is equivalent to `clear prometheus`;
 - `reset-server` is equivalent to `clear server` or simply `clear`;
 - `config-get` and `config-set` are respectively `conf get` and `conf set`;
-- `reload` is equivalent to `conf reload`.
+- `reload` is equivalent to `conf reload`;
+- `is-alive` is equivalent to `ping`;
+- `details` is equivalent to `status details`.
 
 
 Whenever you use a deprecated command, the `pgagroal-cli` will print on standard error a warning message.

src/cli.c

@@ -55,7 +55,7 @@
 #define ACTION_GRACEFULLY      2
 #define ACTION_STOP            3
 #define ACTION_STATUS          4
-#define ACTION_DETAILS         5
+#define ACTION_STATUS_DETAILS  5
 #define ACTION_ISALIVE         6
 #define ACTION_CANCELSHUTDOWN  7
 #define ACTION_ENABLEDB        8
@@ -119,15 +119,14 @@ usage(void)
    printf("                           - 'idle' to flush only idle connections\n");
    printf("                           - 'all' to flush all connections. USE WITH CAUTION!\n");
    printf("                           If no <database> name is specified, applies to all databases.\n");
-   printf("  is-alive                 Is pgagroal alive?\n");
+   printf("  ping                     Verifies if pgagroal is up and running\n");
    printf("  enable   [database]      Enables the specified databases (or all databases)\n");
    printf("  disable  [database]      Disables the specified databases (or all databases)\n");
    printf("  shutdown [mode]          Stops pgagroal pooler. The <mode> can be:\n");
    printf("                           - 'gracefully' (default) waits for active connections to quit\n");
    printf("                           - 'immediate' forces connections to close and terminate\n");
    printf("                           - 'cancel' avoid a previously issued 'shutdown gracefully'\n");
-   printf("  status                   Status of pgagroal\n");
-   printf("  details                  Detailed status of pgagroal\n");
+   printf("  status [details]         Status of pgagroal, with optional details\n");
    printf("  switch-to <server>       Switches to the specified primary server\n");
    printf("  conf <action>            Manages the configuration (e.g., reloads the configuration\n");
    printf("                           The subcommand <action> can be:\n");
@@ -388,17 +387,20 @@ main(int argc, char** argv)
       action = ACTION_GRACEFULLY;
       pgagroal_log_trace("Command: <shutdown gracefully>");
    }
+   else if (parse_command_simple(argc, argv, optind, "status", "details")
+            || parse_deprecated_command(argc, argv, optind, "details", NULL, "status details", 1, 6))
+   {
+      /* the 'status details' has to be parsed before the normal 'status' command !*/
+      action = ACTION_STATUS_DETAILS;
+      pgagroal_log_trace("Command: <status details>");
+   }
    else if (parse_command_simple(argc, argv, optind, "status", NULL))
    {
       action = ACTION_STATUS;
       pgagroal_log_trace("Command: <status>");
    }
-   else if (parse_command_simple(argc, argv, optind, "details", NULL))
-   {
-      action = ACTION_DETAILS;
-      pgagroal_log_trace("Command: <details>");
-   }
-   else if (parse_command_simple(argc, argv, optind, "is-alive", NULL))
+   else if (parse_command_simple(argc, argv, optind, "ping", NULL)
+            || parse_deprecated_command(argc, argv, optind, "is-alive", NULL, "ping", 1, 6))
    {
       action = ACTION_ISALIVE;
       pgagroal_log_trace("Command: <is-alive>");
@@ -572,7 +574,7 @@ main(int argc, char** argv)
    {
       exit_code = status(s_ssl, socket);
    }
-   else if (action == ACTION_DETAILS)
+   else if (action == ACTION_STATUS_DETAILS)
    {
       exit_code = details(s_ssl, socket);
    }