Postgres Pro
Downloads
Home   >   mailing lists

Thread: Update Help on PREPARE to mention DEALLOCATE

Update Help on PREPARE to mention DEALLOCATE

From
Kirk Wolak
Date:
Please notice this exchange:

16:20:02 devuser@nctest= # \h deallocate
Command:     DEALLOCATE
Description: deallocate a prepared statement
Syntax:
DEALLOCATE [ PREPARE ] { name | ALL }

URL: https://www.postgresql.org/docs/16/sql-deallocate.html

16:20:11 devuser@nctest= # \h PREPARE
Command:     PREPARE
Description: prepare a statement for execution
Syntax:
PREPARE name [ ( data_type [, ...] ) ] AS statement

URL: https://www.postgresql.org/docs/16/sql-prepare.html

Notice.  The DEALLOCATE  shows [ PREPARE ]
Which is great because the two commands go together.
Unfortunately it's asymmetry is painful.  Because I ALWAYS remember PREPARE.
It's DEALLOCATE I always struggle to remember.

Could we make the PREPARE line read

PREPARE [ DEALLOCATE ] ...?

So it's more consistent, and the user using a PREPARE gets a clue to DEALLOCATE?

Thanks!

Re: Update Help on PREPARE to mention DEALLOCATE

From
"David G. Johnston"
Date:
On Tue, Apr 16, 2024 at 1:27 PM Kirk Wolak <wolakk@gmail.com> wrote:
Could we make the PREPARE line read

PREPARE [ DEALLOCATE ] ...?

So it's more consistent, and the user using a PREPARE gets a clue to DEALLOCATE?


No. That is a syntax excerpt and the prepare command doesn't accept an optional deallocate keyword at that position.

If we wanted to improve the psql help here we'd have two options:
Add to the description:
prepare a statement for execution (undo this with Deallocate)

or teach our build system to add our "see also" section to the psql help pages.

The second seems reasonable but non-trivial.  The first just seems odd when reading the website.

There may be a third option but I actually haven't ever explored the psql help build module.

David J.
 

Re: Update Help on PREPARE to mention DEALLOCATE

From
Kirk Wolak
Date:
On Tue, Apr 16, 2024 at 4:42 PM David G. Johnston <david.g.johnston@gmail.com> wrote:
On Tue, Apr 16, 2024 at 1:27 PM Kirk Wolak <wolakk@gmail.com> wrote:
Could we make the PREPARE line read
...
No. That is a syntax excerpt and the prepare command doesn't accept an optional deallocate keyword at that position.

If we wanted to improve the psql help here we'd have two options:
Add to the description:
prepare a statement for execution (undo this with Deallocate)
 
I  am 100% okay with that.  I would consider DEALLOCATE to be caps so it looks like a command.

But would leave that to you guys...
Great observations on the other issues.  Not looking to complicate things.  Just enough bread crumbs to link things.

Thanks!