pipelining in psql, commit 41625ab

On Fri, Feb 21, 2025 at 11:33:41AM +0900, Michael Paquier wrote:
> So let's take one step here, I have applied the main patch.

commit 41625ab wrote:
> * \syncpipeline queues a synchronisation request, without flushing the
> commands to the server, equivalent of PQsendPipelineSync().

libpq has both PQpipelineSync() and PQsendPipelineSync(), so I find it odd
that the psql command for PQsendPipelineSync() is \syncpipeline. I would have
expected the word "send" somewhere in its name. That said, maybe having
PQpipelineSync() was a mistake, since I think it's just PQsendPipelineSync() +
PQflush(). In that light, it's reasonable not to spread the extra "send" word
into psql. \syncpipeline is fine with me, but it's worth others taking a
second look.

> + pg_log_error("\\getresults: invalid number of requested results");
> + return PSQL_CMD_SKIP_LINE;

This should be PSQL_CMD_ERROR. That matters under ON_ERROR_STOP=1.

> --- a/src/bin/psql/help.c
> +++ b/src/bin/psql/help.c
> @@ -167,15 +167,22 @@ slashUsage(unsigned short int pager)
> HELP0(" \\close STMT_NAME close an existing prepared statement\n");
> HELP0(" \\copyright show PostgreSQL usage and distribution terms\n");
> HELP0(" \\crosstabview [COLUMNS] execute query and display result in crosstab\n");
> + HELP0(" \\endpipeline exit pipeline mode\n");
> HELP0(" \\errverbose show most recent error message at maximum verbosity\n");
> + HELP0(" \\flush push unsent data to the server\n");
> + HELP0(" \\flushrequest send a flushrequest command\n");

protocol.sgml calls it a "Flush command".

> HELP0(" \\g [(OPTIONS)] [FILE] execute query (and send result to file or |pipe);\n"
> " \\g with no arguments is equivalent to a semicolon\n");
> HELP0(" \\gdesc describe result of query, without executing it\n");
> + HELP0(" \\getresults [NUM_RES] read NUM_RES pending results. All pending results are\n"
> + " read if no argument is provided\n");
> HELP0(" \\gexec execute query, then execute each value in its result\n");
> HELP0(" \\gset [PREFIX] execute query and store result in psql variables\n");
> HELP0(" \\gx [(OPTIONS)] [FILE] as \\g, but forces expanded output mode\n");
> HELP0(" \\parse STMT_NAME create a prepared statement\n");
> HELP0(" \\q quit psql\n");
> + HELP0(" \\startpipeline enter pipeline mode\n");
> + HELP0(" \\syncpipeline add a synchronisation point to an ongoing pipeline\n");

v17 "\?" has a 14-line "General" section:

General
\bind [PARAM]... set query parameters
\copyright show PostgreSQL usage and distribution terms
\crosstabview [COLUMNS] execute query and display result in crosstab
\errverbose show most recent error message at maximum verbosity
\g [(OPTIONS)] [FILE] execute query (and send result to file or |pipe);
\g with no arguments is equivalent to a semicolon
\gdesc describe result of query, without executing it
\gexec execute query, then execute each value in its result
\gset [PREFIX] execute query and store result in psql variables
\gx [(OPTIONS)] [FILE] as \g, but forces expanded output mode
\q quit psql
\watch [[i=]SEC] [c=N] [m=MIN]
execute query every SEC seconds, up to N times,
stop if less than MIN rows are returned

v18 has raised that to 26 lines via $SUBJECT and other additions. I think a
new "Extended Query Protocol" section should house \bind and all the v18
additions. Beginners should ignore the new section. The section may as well
appear last. What do you think?