[agroal#253] Refactor commands in pgagroal-cli

Now `pgagroal-cli` has a set of "logically" grouped commands and
subcommands. For example, all the commands related to shutting down
the pooler are under the `shutdown` command, that can operate with
subcommands like `gracefully`, `immediate` or `cancel`.

In order to provide this capability, two new functions have been
introduced:
- `parse_command()` accepts the command line and seek for a command,
possibly its subcommand, and an optional "value" (often the database
or server name).
- `parse_deprecated_command()` does pretty much the same thing but
against the old command. Thanks to this, old commands can still work
and the user will be warned about their deprecation, but the interface
of `pgagroal-cli` is not broken.

Both functions requires to know the offset at which start seeking for
a command, and that depends on the number of options already parsed
via `getopt_long()`. Since the `&option_index` is valued only for long
options, I decided to use the `optind` global value, see
getopt_long(3).
This value is initialized with the "next thing" to seek on the command
line, i.e., the next index on `argv`.

In the case the command accepts an optional database name, the
database value is automatically set to '*' (all databases) in case the
database name is not found on the command line.
Therefore:
   pgagroal-cli flush idle
is equivalent to
   pgagroal-cli flush idle '*'

On the other hand, commands that require a server name get the value
automatically set to "\0" (an invalid server name) in order to "block"
other pieces of code. Moroever, if the server has not been specified,
the command is automatically set to "unknown" so that the help screen
is shown.

The `pgagroal-cli` has a set of `pgagroal_log_trace()` calls whenever
a command is "parsed", so that it is possible to quickly follow the
command line parsing.

Also, since the `pgagroal-cli` exists if no command line arguments
have been specified, the safety check aboutt `argc > 0` around the
command line parsing have been removed.

In the case the user specified an unknown command, she is warned on
stdout before printing the `usage()` help screen.

Deprecated commands are notified to the user via a warning message,
printed on stderr, that provides some hints about the correct usage of
the new command.

Documentation has been updated and improved.
A specific documentation section about deprecated
commands have been introduced.

Close agroal#253

doc/CLI.md

@@ -1,8 +1,21 @@
-# pgagroal-cli user guide
+# `pgagroal-cli` user guide
+
+`pgagroal-cli` is a command line interface to interact with `pgagroal`.
+The executable accepts a set of options, as well as a command to execute.
+If no command is provided, the program will show the help screen.
+
+The `pgagroal-cli` utility has the following synopsis:
 
 ```
-pgagroal-cli [ -c CONFIG_FILE ] [ COMMAND ]
+pgagroal-cli [ OPTIONS ] [ COMMAND ]
+```
+
 
+## Options
+
+Available options are the following ones:
+
+```
 -c, --config CONFIG_FILE Set the path to the pgagroal.conf file
 -h, --host HOST          Set the host name
 -p, --port PORT          Set the port number
@@ -12,65 +25,41 @@ pgagroal-cli [ -c CONFIG_FILE ] [ COMMAND ]
 -v, --verbose            Output text string of result
 -V, --version            Display version information
 -?, --help               Display help
-```
-
-Commands are described in the following sections.
-Several commands work against an optional specified database.
-It is possible to specify *all database* at once by means of the special string `*` (take care of shell expansion!).
-If no database name is specified, the command is automatically run against all databases (i.e., as if `*` has been specified).
-
-## flush-idle
-Flush idle connections.
-Without any argument, or with `*` as only argument,
-works against all configured databases.
-
-Command
 
-```
-pgagroal-cli flush-idle [*|<database>]
 ```
 
-Example
+Options can be specified either in short or long form, in any position of the command line.
 
-```
-pgagroal-cli flush-idle
-```
-
-## flush-gracefully
-Flush all connections gracefully.
-Without any argument, or with `*` as only argument,
-works against all configured databases.
-
-Command
-
-```
-pgagroal-cli flush-gracefully [*|<database>]
-```
+## Commands
 
-Example
+### flush
+The `flush` command performs a connection flushing.
+It accepts a *mode* to operate the actual flushing:
+- `gracefully` (the default if not specified), flush connections when possible;
+- `idle` to flush only connections in state *idle*;
+- `all` to flush all the connections (**use with caution!**).
 
-```
-pgagroal-cli flush-gracefully
-```
+The command accepts a database name, that if provided, restricts the scope of
+`flush` only to connections related to such database.
+If no database is provided, the `flush` command is operated against all databases.
 
-## flush-all
-Flush all connections. **USE WITH CAUTION !**
-Without any argument, or with `*` as only argument,
-works against all configured databases.
 
 Command
 
 ```
-pgagroal-cli flush-all [*|<database>]
+pgagroal-cli flush [gracefully|idle|all] [*|<database>]
 ```
 
-Example
+Examples
 
 ```
-pgagroal-cli flush-all mydb
+pgagroal-cli flush           # pgagroal-cli flush gracefully '*'
+pgagroal-cli flush idle      # pgagroal-cli flush idle '*'
+pgagroal-cli flush all       # pgagroal-cli flush all '*'
+pgagroal-cli flush pgbench   # pgagroal-cli flush gracefully pgbench
 ```
 
-## is-alive
+### is-alive
 Is pgagroal alive
 
 Command
@@ -85,10 +74,8 @@ Example
 pgagroal-cli is-alive
 ```
 
-## enable
-Enables the specified database.
-Without any argument, or with `*` as only argument,
-works against all configured databases.
+### enable
+Enables a database (or all databases).
 
 Command
 
@@ -102,11 +89,8 @@ Example
 pgagroal-cli enable
 ```
 
-## disable
-Disables a database specified by its name.
-Without any argument, or with `*` as only argument,
-works against all configured databases.
-
+### disable
+Disables a database (or all databases).
 
 Command
 
@@ -120,52 +104,33 @@ Example
 pgagroal-cli disable
 ```
 
-## gracefully
-Stop pgagroal gracefully
+### shutdown
+The `shutdown` command is used to stop the connection pooler.
+It supports the following operating modes:
+- `gracefully` (the default) closes the pooler as soon as no active connections are running;
+- `immediate` force an immediate stop.
 
-Command
+If the `gracefully` mode is requested, chances are the system will take some time to
+perform the effective shutdown, and therefore it is possible to abort the request
+issuing another `shutdown` command with the mode `cancel`.
 
-```
-pgagroal-cli gracefully
-```
-
-Example
-
-```
-pgagroal-cli gracefully
-```
-
-## stop
-Stop pgagroal
 
 Command
 
 ```
-pgagroal-cli stop
+pgagroal-cli shutdown [gracefully|immediate|cancel]
 ```
 
-Example
-
-```
-pgagroal-cli stop
-```
-
-## cancel-shutdown
-Cancel the graceful shutdown
-
-Command
+Examples
 
 ```
-pgagroal-cli cancel-shutdown
+pgagroal-cli shutdown   # pgagroal-cli shutdown gracefully
+...
+pgagroal-cli shutdown cancel  # stops the above command
 ```
 
-Example
-
-```
-pgagroal-cli cancel-shutdown
-```
 
-## status
+### status
 Status of pgagroal
 
 Command
@@ -180,7 +145,7 @@ Example
 pgagroal-cli status
 ```
 
-## details
+### details
 Detailed status of pgagroal
 
 Command
@@ -195,8 +160,8 @@ Example
 pgagroal-cli details
 ```
 
-## switch-to
-Switch to another primary
+### switch-to
+Switch to another primary server.
 
 Command
 
@@ -210,7 +175,7 @@ Example
 pgagroal-cli switch-to replica
 ```
 
-## reload
+### reload
 Reload the configuration
 
 Command
@@ -225,31 +190,52 @@ Example
 pgagroal-cli reload
 ```
 
-## reset
-Reset the Prometheus statistics
-Command
+### clear
+Resets different parts of the pooler. It accepts an operational mode:
+- `prometheus` resets the metrics provided without altering the pooler status;
+- `server` resets the specified server status.
+
 
 ```
-pgagroal-cli reset
+pgagroal-cli clear [prometheus|server <server>]
 ```
 
-Example
+Examples
 
 ```
-pgagroal-cli reset
+pgagroal-cli clear spengler            # pgagroal-cli clear server spengler
+pgagroal-cli clear prometheus
 ```
 
-## reset-server
-Reset the state of a server
 
-Command
+## Deprecated commands
+
+The following commands have been deprecated and will be removed
+in later releases of `pgagroal`.
+For each command, this is the corresponding current mapping
+to the working command:
+
+- `flush-idle` is equivalent to `flush idle`;
+- `flush-all` is equivalent to `flush all`;
+- `flush-gracefully` is equivalent to `flush gracefully` or simply `flush`;
+- `stop` is equivalent to `shutdown immediate`;
+- `gracefully` is equivalent to `shutdown gracefully` or simply `shutdown`;
+- `reset` is equivalent to `clear prometheus`;
+- `reset-server` is equivalent to `clear server` or simply `clear`.
+
+
+Whenever you use a deprecated command, the `pgagroal-cli` will print on standard error a warning message.
+For example:
 
 ```
-pgagroal-cli reset-server <server>
+pgagroal-cli reset-server
+
+Deprecated command <reset-server>; use <clear server> instead!
 ```
 
-Example
+If you don't want to get any warning about deprecated commands, you
+can redirect the `stderr` to `/dev/null` or any other location with:
 
 ```
-pgagroal-cli reset-server primary
+pgagroal-cli reset-server 2>/dev/null
 ```