Use "protocol options" name instead of "protocol extensions" everywhere

On 30/10/2024 15:58, Jelte Fennema-Nio wrote:

It was pointed out by Heikki in the thread around protocol-level
wait-for-LSN that "protocol extensions" is a pretty confusing name,
since it suggests a relation to Postgres extensions. Even though there
is no such relationship at all. Attached is a small patch that aligns
on the name "protocol options" instead. This terminology is already
used in a bunch of the docs.

Since no protocol options have been introduced yet, it seems like now
is a good time to align on what to call them. It might even be worth
backporting this to have our docs of previous versions be consistent.

Bikeshedding time:

"protocol option" makes me think of GUCs.

"optional protocol features" perhaps. A bit long though..

Or keep using "protocol extension" and add a paragraph to the docs to
say explicitly that there's no support for extensions to create protocol
extensions. TLS extensions is a good comparison.

I don't have a strong opinion, all of those would work for me.

--
Heikki Linnakangas
Neon (https://neon.tech)

On Thu, Oct 31, 2024 at 10:51 AM Heikki Linnakangas <hlinnaka@iki.fi> wrote:

Bikeshedding time:

"protocol option" makes me think of GUCs.

"optional protocol features" perhaps. A bit long though..

Or keep using "protocol extension" and add a paragraph to the docs to
say explicitly that there's no support for extensions to create protocol
extensions. TLS extensions is a good comparison.

I don't have a strong opinion, all of those would work for me.

I don't particularly like "optional protocol features". I find
"protocol extensions" to be mildly clearer than "protocol options,"
but only mildly.

I don't think it's really viable to promise that we'll never talk
about extending anything other than in the context of what CREATE
EXTENSION does.

--
Robert Haas
EDB: http://www.enterprisedb.com

On Thu, Oct 31, 2024 at 7:51 AM Heikki Linnakangas <hlinnaka@iki.fi> wrote:

Or keep using "protocol extension" and add a paragraph to the docs to
say explicitly that there's no support for extensions to create protocol
extensions. TLS extensions is a good comparison.

Of the three proposed, this last one is my preference. I think it'd be
good to draw very clear lines between the transport level, the
protocol level, and the application level.

Thanks,
--Jacob

On Thu, 31 Oct 2024 at 15:50, Heikki Linnakangas <hlinnaka@iki.fi> wrote:

Bikeshedding time:

Another few options:
4. Protocol enhancement
5. Protocol flag
6. Protocol feature-flag
7. Protocol configuration
8. Protocol parameter

One thing to consider is that there's two ways of using them:
1. Turning an optional protocol feature on/of (send LSN yes/no)
2. Configuring an optional protocol feature (compress with gzip/lz4/zstd)

I think "protocol extension" is a good name for the first. But it
reads/writes a bit awkward for the second usage imo:.
1. The wait_for_lsn protocol extension needs to be enabled.
2. I configured the compression protocol extension to be gzip.

I like that "protocol option" because it works for both:
1. The wait_for_lsn protocol option needs to be enabled.
2. I set the compression protocol option to gzip.

I still think of these "protocol xyzs" as essentially being GUCs for
the protocol. Especially because they are configured the same way as
GUCs in the StartupMessage. So having "protocol option" making you
think of GUCs doesn't necessarily seem like a bad thing to me.

On Thu, 31 Oct 2024 at 17:09, Robert Haas <robertmhaas@gmail.com> wrote:

I don't think it's really viable to promise that we'll never talk
about extending anything other than in the context of what CREATE
EXTENSION does.

Agreed, but it seems nice to avoid confusion by not overloading
terminology, if we can find a good/decent alternative. When we do have
an overloaded term, we should definitely document what we mean with it
and how it differs from other usage of the term. But even then many
people won't have read those docs and assume it means the thing that
they expect it to mean.

A good example of this is the fact that initdb creates a "database
cluster". We definitely document that we use the term that way. But if
you talk/write about a database cluster many people (understandably)
expect you to mean a very different thing.

On Thu, 31 Oct 2024 at 18:15, Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

On Thu, 31 Oct 2024 at 15:50, Heikki Linnakangas <hlinnaka@iki.fi> wrote:

Bikeshedding time:

Another few options:

Okay let's just pick one of the available options. The current
situation where we use different terminology for the same thing across
the docs is definitely confusing, so let's change that. The proposed
options for the names are:

1. Protocol option
2. Protocol extension
3. Optional protocol feature
4. Protocol enhancement
5. Protocol flag
6. Protocol feature-flag
7. Protocol configuration
8. Protocol parameter

My personal preference from most to least preferred are as follows,
but I could live with any of them:

- 1
- 8
- 2
- 7
- everything else

(if we go for "protocol extension" then the patch should be updated to
include a section that clarifies that protocol extensions have nothing
to do with CREATE EXTENSION)

On Mon, Dec 23, 2024 at 8:39 AM Jelte Fennema-Nio <postgres@jeltef.nl>
wrote:

On Thu, 31 Oct 2024 at 18:15, Jelte Fennema-Nio <postgres@jeltef.nl>
wrote:

On Thu, 31 Oct 2024 at 15:50, Heikki Linnakangas <hlinnaka@iki.fi>

wrote:

Bikeshedding time:

Another few options:

Okay let's just pick one of the available options. The current
situation where we use different terminology for the same thing across
the docs is definitely confusing, so let's change that. The proposed
options for the names are:

1. Protocol option
2. Protocol extension
3. Optional protocol feature
4. Protocol enhancement
5. Protocol flag
6. Protocol feature-flag
7. Protocol configuration
8. Protocol parameter

My personal preference from most to least preferred are as follows,
but I could live with any of them:

- 1
- 8
- 2
- 7
- everything else

(if we go for "protocol extension" then the patch should be updated to
include a section that clarifies that protocol extensions have nothing
to do with CREATE EXTENSION)

There are three places being changed here, and two things that may exist: a
feature related to the protocol (reasonably called a protocol extension)
and those pre-defined variables that take on values that those features may
expose (presently called parameters in the context of the main server).

This is clearly the first thing:
-         reserved for use as protocol extensions, while others are
+         reserved for use as protocol options, while others are
I would instead suggest "reserved for use *by* protocol extensions, while
others are".

More completely:
Parameter names beginning with _pq_. are reserved for use *by* protocol
extensions and are called protocol parameters, while others are run-time
parameters to be set at backend start time.

And this, the second:
-  libpq_ngettext("protocol extension not supported by server: %s",
- "protocol extensions not supported by server: %s", num),
+  libpq_ngettext("protocol option not supported by server: %s",
+ "protocol options not supported by server: %s", num),
To which I suggest we write:
"protocol parameter not supported by server: %s"

The backup usage noted here doesn't even seem to relate specifically to the
frontend/backend protocol; or rather the protocol is designed so that the
client and server can change their behavior without requiring the protocol
layer to change. A message type is unrelated to a protocol parameter.

Thus I'd get rid of the word protocol altogether. Something like:

[This also allows]
for simpler enhancements to the backup process since the server can add new
information
[in the message stream...]

Though a slightly more involved (i.e., multiple line) re-wording should be
considered.

David J.

On Mon, 2024-12-23 at 16:39 +0100, Jelte Fennema-Nio wrote:

On Thu, 31 Oct 2024 at 18:15, Jelte Fennema-Nio <postgres@jeltef.nl> wrote:

On Thu, 31 Oct 2024 at 15:50, Heikki Linnakangas <hlinnaka@iki.fi> wrote:

Bikeshedding time:

Another few options:

Okay let's just pick one of the available options. The current
situation where we use different terminology for the same thing across
the docs is definitely confusing, so let's change that. The proposed
options for the names are:

1. Protocol option
2. Protocol extension
3. Optional protocol feature
4. Protocol enhancement
5. Protocol flag
6. Protocol feature-flag
7. Protocol configuration
8. Protocol parameter

My personal preference from most to least preferred are as follows,
but I could live with any of them:

- 1
- 8
- 2
- 7
- everything else

(if we go for "protocol extension" then the patch should be updated to
include a section that clarifies that protocol extensions have nothing
to do with CREATE EXTENSION)

My vote is to stick with "extension".

In the protocol documentation [1]https://www.postgresql.org/docs/17/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-STARTUPMESSAGE, right before the place where the
proposed patch wants to change "extensions" to "options", "option" is
used for command line arguments for the backend. Elsewhere, we use
"options" for parenthesized lists like "ANALYZE (option, ...) ..." or
"CREATE FOREIGN TABLE ... OPTIONS (...)".

I think that there is less potential for confusion with "extension".
To me, a "protocol extension" would be something that adds new
features to a protocol, while a "protocol option" sounds like a
switch that has always been there.

Yours,
Laurenz Albe

[1]: https://www.postgresql.org/docs/17/protocol-message-formats.html#PROTOCOL-MESSAGE-FORMATS-STARTUPMESSAGE

I'll set this patch to "ready for committer".
This is about the color of the bikeshed, and several people
have voiced their opinion. I don't think much more review
is needed. All that is needed is a committer who either
commits or rejects it.

Yours,
Laurenz Albe

On 31.01.25 10:32, Laurenz Albe wrote:

I'll set this patch to "ready for committer".
This is about the color of the bikeshed, and several people
have voiced their opinion. I don't think much more review
is needed. All that is needed is a committer who either
commits or rejects it.

I don't think there is consensus for change, so I'm rejecting it.