[PATCH] Documentation

On 12/18/25 8:31 AM, Mikael Gustavsson wrote:

This is my first ever patch to postgresql so please guide me if i'm
doing something wrong.

This patch updates some examples in documentation client-auth.sgml from
md5 to scram-sha-256
Reference: https://www.postgresql.org/message-
id/176595607507.978865.11597773194269211255%40wrigleys.postgresql.org
<https://www.postgresql.org/message-
id/176595607507.978865.11597773194269211255%40wrigleys.postgresql.org>

Välkommen!

The patch looks good to me and it looks like a useful change. To make
sure it is not lost you can add it to the current open commitfest but it
is also possible that some committer will just pick up the patch directly.

You can add it here: https://commitfest.postgresql.org/

I personally usually use "git format-patch" when submitting to the
mailing list but this format works just as well if it is just one simple
patch like this and not a series of multiple patches.

Thanks for the patch!

Andreas

On Thu, 2025-12-18 at 08:51 +0100, Andreas Karlsson wrote:

On 12/18/25 8:31 AM, Mikael Gustavsson wrote:

This is my first ever patch to postgresql so please guide me if i'm
doing something wrong.

This patch updates some examples in documentation client-auth.sgml from
md5 to scram-sha-256
Reference: https://www.postgresql.org/message-
id/176595607507.978865.11597773194269211255%40wrigleys.postgresql.org
<https://www.postgresql.org/message-
id/176595607507.978865.11597773194269211255%40wrigleys.postgresql.org>

The patch looks good to me and it looks like a useful change.

+1

Yours,
Laurenz Albe

On Thu, Dec 18, 2025 at 2:51 PM Andreas Karlsson <andreas@proxel.se> wrote:

The patch looks good to me and it looks like a useful change. To make
sure it is not lost you can add it to the current open commitfest but it
is also possible that some committer will just pick up the patch directly.

I can commit this tomorrow.

Deprecating md5 came into v18, so even though this is not a
correction, we could backpatch this to v18 for consistency. Anyone
want to make a case for or against?

--
John Naylor
Amazon Web Services

On Thu, Dec 18, 2025 at 2:31 PM Mikael Gustavsson
<mikael.gustavsson@smhi.se> wrote:

This patch updates some examples in documentation client-auth.sgml from md5 to scram-sha-256
Reference: /messages/by-id/176595607507.978865.11597773194269211255@wrigleys.postgresql.org

Pushed and backpatched to PG18, thanks!

--
John Naylor
Amazon Web Services

On Fri, Dec 19, 2025 at 5:53 PM John Naylor <johncnaylorls@gmail.com> wrote:

On Thu, Dec 18, 2025 at 2:31 PM Mikael Gustavsson
<mikael.gustavsson@smhi.se> wrote:

This patch updates some examples in documentation client-auth.sgml from md5 to scram-sha-256
Reference: /messages/by-id/176595607507.978865.11597773194269211255@wrigleys.postgresql.org

Pushed and backpatched to PG18, thanks!

This change made me wonder whether we should also update the
pg_hba.conf examples
in high-availability.sgml and logical-replication.sgml. I've attached
a patch for that. Thoughts?

Regards,

--
Fujii Masao

On 19/12/2025 17:14, Fujii Masao wrote:

On Fri, Dec 19, 2025 at 5:53 PM John Naylor <johncnaylorls@gmail.com> wrote:

On Thu, Dec 18, 2025 at 2:31 PM Mikael Gustavsson
<mikael.gustavsson@smhi.se> wrote:

This patch updates some examples in documentation client-auth.sgml from md5 to scram-sha-256
Reference: /messages/by-id/176595607507.978865.11597773194269211255@wrigleys.postgresql.org

Pushed and backpatched to PG18, thanks!

This change made me wonder whether we should also update the
pg_hba.conf examples
in high-availability.sgml and logical-replication.sgml. I've attached
a patch for that. Thoughts?

+1

Let's update this example in createuser.sgml too while we're at it:

<para>
To create the user <literal>joe</literal> as a superuser,
and assign a password immediately:
<screen>
<prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput>
<computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput>
<computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput>
<computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
</screen>
In the above example, the new password isn't actually echoed when typed,
but we show what was typed for clarity. As you see, the password is
encrypted before it is sent to the client.
</para>

I get this output for that command now:

$ createuser -P -s -e joe
Enter password for new role:
Enter it again:
SELECT pg_catalog.set_config('search_path', '', false);
CREATE ROLE joe PASSWORD
'SCRAM-SHA-256$4096:vrJL1JVwK9VyDQ+XmGk2lg==$K32pX1bdFx3J+LeBcFpUOmaBnIUIduAexL+ufLYz/MI=:O6gxeGemIC3wbqEWMZXKAMOnQ5A1hM07nEu7KeSrEiE='
SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN NOREPLICATION NOBYPASSRLS;

- Heikki

On Thu, Dec 18, 2025 at 12:31 AM Mikael Gustavsson <
mikael.gustavsson@smhi.se> wrote:

This is my first ever patch to postgresql so please guide me if i'm doing
something wrong.

The subject line of an email should fairly precisely say what is being
changed in the proposed patch. The documentation is huge, writing just
that helps no one when this email is showing up in their mail reader list
of emails or the search results page.

David J.

________________________________
Från: David G. Johnston <david.g.johnston@gmail.com>
Skickat: den 19 december 2025 18:01
Till: Mikael Gustavsson
Kopia: pgsql-hackers@lists.postgresql.org
Ämne: Re: [PATCH] Documentation

On Thu, Dec 18, 2025 at 12:31 AM Mikael Gustavsson <mikael.gustavsson@smhi.se<mailto:mikael.gustavsson@smhi.se>> wrote:

This is my first ever patch to postgresql so please guide me if i'm doing something wrong.

The subject line of an email should fairly precisely say what is being changed in the proposed patch. The documentation is huge, writing just that helps no one when this email is showing up in their mail reader list of emails or the search results page.

David J.

Thanks for the advice, I will do that next time.

/Mikael

On Fri, Dec 19, 2025 at 11:00 PM Heikki Linnakangas <hlinnaka@iki.fi> wrote:

On 19/12/2025 17:14, Fujii Masao wrote:

On Fri, Dec 19, 2025 at 5:53 PM John Naylor <johncnaylorls@gmail.com> wrote:

On Thu, Dec 18, 2025 at 2:31 PM Mikael Gustavsson
<mikael.gustavsson@smhi.se> wrote:

This patch updates some examples in documentation client-auth.sgml from md5 to scram-sha-256
Reference: /messages/by-id/176595607507.978865.11597773194269211255@wrigleys.postgresql.org

Pushed and backpatched to PG18, thanks!

This change made me wonder whether we should also update the
pg_hba.conf examples
in high-availability.sgml and logical-replication.sgml. I've attached
a patch for that. Thoughts?

Sorry, I neglected to look around for similar places to update. I
don't see any other such places, so I will commit this and backpatch
to PG18 as well.

Let's update this example in createuser.sgml too while we're at it:

<computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>

I get this output for that command now:

SELECT pg_catalog.set_config('search_path', '', false);
CREATE ROLE joe PASSWORD
'SCRAM-SHA-256$4096:vrJL1JVwK9VyDQ+XmGk2lg==$K32pX1bdFx3J+LeBcFpUOmaBnIUIduAexL+ufLYz/MI=:O6gxeGemIC3wbqEWMZXKAMOnQ5A1hM07nEu7KeSrEiE='
SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN NOREPLICATION NOBYPASSRLS;

+1

This will need to be backpatched to PG14. Unlike the md5 case, the
encrypted password will not be reproducible. Since the above omission
hasn't been noticed, I don't suppose we need to call out this fact?

--
John Naylor
Amazon Web Services

On Mon, Jan 5, 2026 at 1:39 PM John Naylor <johncnaylorls@gmail.com> wrote:

On Fri, Dec 19, 2025 at 11:00 PM Heikki Linnakangas <hlinnaka@iki.fi> wrote:

On 19/12/2025 17:14, Fujii Masao wrote:

This change made me wonder whether we should also update the
pg_hba.conf examples
in high-availability.sgml and logical-replication.sgml. I've attached
a patch for that. Thoughts?

Sorry, I neglected to look around for similar places to update. I
don't see any other such places, so I will commit this and backpatch
to PG18 as well.

I pushed your patch, thanks!

Let's update this example in createuser.sgml too while we're at it:

<computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>

This will need to be backpatched to PG14. Unlike the md5 case, the
encrypted password will not be reproducible. Since the above omission
hasn't been noticed, I don't suppose we need to call out this fact?

I pushed a fix for this, including missing tokens for earlier branches
(and decided not to mention random salt for the example).

--
John Naylor
Amazon Web Services