pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedGood beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
21+ messages / 8 participants
[nested] [flat]
* Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-06 13:41 Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 21+ messages in thread
From: Daniel Gustafsson @ 2026-11-06 13:41 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
While working on a docs patch I realized that we use a wide variety of
terminology for secrets that will not be encrypted, which is very different
from secrets which will be encrypted; the former is IMO cleartext and the
latter plaintext.
In the documentation, when we talk about secrets used for passwords
authentication and similar, we use a mix of "clear-text", "cleartext" and
"clear text"; in at least one place we also use "plaintext". There are several
cases where we use "plaintext password" correctly, but we also have the variant
"plain text" vs, "plain-text" vs. "plaintext" there as well.
It would be nice to get that cleaned up and consistent, but I don't intend to
spend time on it myself. However, I know from attending a session on
documentation at PGConf.EU that there are several potential contributors who
would like to work on the docs but don't know exactly where to start, so I
figured I'd raise it here as a good introductory project.
If someone does take a stab at it, I will of course spend the time to review
it.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-06 14:44 Karen Jex <karenjex@hotmail.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-06 14:44 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
It would be nice to get that cleaned up and consistent, but I don't intend to
spend time on it myself. However, I know from attending a session on
documentation at PGConf.EU that there are several potential contributors who
would like to work on the docs but don't know exactly where to start, so I
figured I'd raise it here as a good introductory project.
I would love to take this on - thank you for flagging it as a potential first doc-hacking task.
In the documentation, when we talk about secrets used for passwords
authentication and similar, we use a mix of "clear-text", "cleartext" and
"clear text"; in at least one place we also use "plaintext". There are several
cases where we use "plaintext password" correctly, but we also have the variant
"plain text" vs, "plain-text" vs. "plaintext" there as well.
Just to confirm my understanding:
1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext".
Regards,
--
Karen Jex
________________________________
From: Daniel Gustafsson <daniel@yesql.se>
Sent: 06 November 2026 14:41
To: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Subject: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
While working on a docs patch I realized that we use a wide variety of
terminology for secrets that will not be encrypted, which is very different
from secrets which will be encrypted; the former is IMO cleartext and the
latter plaintext.
In the documentation, when we talk about secrets used for passwords
authentication and similar, we use a mix of "clear-text", "cleartext" and
"clear text"; in at least one place we also use "plaintext". There are several
cases where we use "plaintext password" correctly, but we also have the variant
"plain text" vs, "plain-text" vs. "plaintext" there as well.
It would be nice to get that cleaned up and consistent, but I don't intend to
spend time on it myself. However, I know from attending a session on
documentation at PGConf.EU that there are several potential contributors who
would like to work on the docs but don't know exactly where to start, so I
figured I'd raise it here as a good introductory project.
If someone does take a stab at it, I will of course spend the time to review
it.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-06 14:49 David E. Wheeler <david@justatheory.com>
parent: Karen Jex <karenjex@hotmail.com>
0 siblings, 2 replies; 21+ messages in thread
From: David E. Wheeler @ 2026-11-06 14:49 UTC (permalink / raw)
To: Karen Jex <karenjex@hotmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Nov 6, 2026, at 09:44, Karen Jex <karenjex@hotmail.com> wrote:
> I would love to take this on - thank you for flagging it as a potential first doc-hacking task.
Yay!
> Just to confirm my understanding:
> 1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
> 2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext”.
I thought these were synonyms, in contrast to “ciphertext”. Should we not pick one to replace all of the others? Searching around a bit, it seems like “ciphertext” and “plaintext” are most often contrasting terms, e.g., https://en.wikipedia.org/wiki/Ciphertext.
Best,
David
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-06 19:16 Karen Jex <karenhjex@gmail.com>
parent: David E. Wheeler <david@justatheory.com>
1 sibling, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-06 19:16 UTC (permalink / raw)
To: David E. Wheeler <david@justatheory.com>; +Cc: Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Le ven. 6 nov. 2026 à 15:49, David E. Wheeler <david@justatheory.com> a écrit :
>
> > Just to confirm my understanding:
> > 1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
> > 2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext”.
>
> I thought these were synonyms, in contrast to “ciphertext”. Should we not pick one to replace all of the others? Searching around a bit, it seems like “ciphertext” and “plaintext” are most often contrasting terms, e.g., https://en.wikipedia.org/wiki/Ciphertext.
I think you're right, and that makes the task much simpler (that was
my initial understanding, before I found various articles suggesting
that cleartext and plaintext were not the same). I see that the
cleartext Wikipedia entry redirects to plaintext:
https://en.wikipedia.org/wiki/Plaintext, which implies that plaintext
may be the preferred term.
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-10 16:30 Karen Jex <karenhjex@gmail.com>
parent: Karen Jex <karenhjex@gmail.com>
0 siblings, 2 replies; 21+ messages in thread
From: Karen Jex @ 2026-11-10 16:30 UTC (permalink / raw)
To: David E. Wheeler <david@justatheory.com>; +Cc: Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Le ven. 6 nov. 2026 à 20:16, Karen Jex <karenhjex@gmail.com> a écrit :
> I see that the cleartext Wikipedia entry redirects to plaintext:
> https://en.wikipedia.org/wiki/Plaintext, which implies that plaintext
> may be the preferred term.
I originally thought we should standardise on "plaintext", but after
reviewing the ways in which the terms are used throughout the docs, I
propose the following approach:
1. Use "plain text" to indicate unformatted text: e.g. "...a plain
text file with special syntax that translators edit."
(https://www.postgresql.org/docs/devel/nls-translator.html#NLS-TRANSLATOR-CONCEPTS).
2. Use "cleartext" to indicate unencrypted passwords/secrets: e.g. "It
is good practice not to send the original cleartext password..."
(https://www.postgresql.org/docs/devel/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN).
This is consistent with the AuthenticationCleartextPassword server
message referenced on the same page.
This is consistent with the vocabulary that is used most often in the
documentation, and the terms are different enough to avoid
confusion/ambiguity.
I attach the proposed patch and, for completeness, a csv file that
lists the proposed changes. I would be very grateful for any feedback
before I submit it to -hackers.
--
Karen
Attachments:
plaintext_proposed_changes.csv (text/csv, 10.1K) download
File,Term,URL,Text containing the term,Change Required
doc/src/sgml/arch-dev.sgml,plain text,https://www.postgresql.org/docs/devel/connect-estab.html,"The query is transmitted using plain text, i.e., there is no parsing done in the client.",No change
doc/src/sgml/arch-dev.sgml,plain text,https://www.postgresql.org/docs/devel/parser-stage.html,The parser has to check the query string (which arrives as plain text) for valid syntax.,No change
doc/src/sgml/catalogs.sgml,plain-text,https://www.postgresql.org/docs/devel/catalog-pg-subscription.html,...it could contain plain-text passwords.,Change to cleartext
doc/src/sgml/client-auth.sgml,clear text,https://www.postgresql.org/docs/devel/auth-pg-hba-conf.html,...the password is sent in clear text over the network...,Change to cleartext
doc/src/sgml/client-auth.sgml,clear text,https://www.postgresql.org/docs/devel/auth-pg-hba-conf.html,...the bearer token is sent in clear text over the network...,Change to cleartext
doc/src/sgml/client-auth.sgml,clear-text,https://www.postgresql.org/docs/devel/auth-oauth.html,The bearer token is sent in clear-text...,Change to cleartext
doc/src/sgml/client-auth.sgml,clear-text,https://www.postgresql.org/docs/devel/auth-password.html,...sends the password in clear-text...,Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,...avoids storing passwords on the server in plain text...,Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,...password transmission will be in plain text in the latter case...,Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,"...again, with the password transmitted in plain text in the latter case...",Change to cleartext
doc/src/sgml/client-auth.sgml,plain text,https://www.postgresql.org/docs/devel/auth-password.html,...storing the password on the server in plain text.,Change to cleartext
doc/src/sgml/config.sgml,plaintext,https://www.postgresql.org/docs/devel/runtime-config-logging.html,...might reveal sensitive data and even contain plaintext passwords,Change to cleartext
doc/src/sgml/datatype.sgml,plain text,https://www.postgresql.org/docs/devel/datatype-net-types.html,...better to use these types instead of plain text types to store network addresses...,No change
doc/src/sgml/dblink.sgml,plain-text,https://www.postgresql.org/docs/devel/contrib-dblink-connect.html,...uses SCRAM-hashed secrets instead of plain-text user passwords...,Change to cleartext
doc/src/sgml/dblink.sgml,plain-text,https://www.postgresql.org/docs/devel/contrib-dblink-connect.html,This avoids storing plain-text user passwords in...,Change to cleartext
doc/src/sgml/docguide.sgml,plain text,https://www.postgresql.org/docs/devel/docguide.html,"PostgreSQL has four primary documentation formats ... Plain text, for pre-installation information",No change
doc/src/sgml/docguide.sgml,plain-text,https://www.postgresql.org/docs/devel/docguide.html,...a number of plain-text README files...,Change to plain text
doc/src/sgml/func/func-trigger.sgml,plain-text,https://www.postgresql.org/docs/devel/functions-trigger.html,...column from associated plain-text document column(s).,Change to plain text
doc/src/sgml/func/func-trigger.sgml,plain-text,https://www.postgresql.org/docs/devel/functions-trigger.html,...column from associated plain-text document column(s).,Change to plain text
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-connect.html,...makes the destination host name appear in cleartext in the network traffic...,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-misc.html,...good practice not to send the original cleartext password...,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-misc.html,...the cleartext password...,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-misc.html,...the new cleartext password.,No change
doc/src/sgml/libpq.sgml,cleartext,https://www.postgresql.org/docs/devel/libpq-ssl.html,The key may be stored in cleartext or encrypted...,No change
doc/src/sgml/libpq.sgml,plaintext,https://www.postgresql.org/docs/devel/libpq-connect.html,The server must request plaintext password authentication.,Change to cleartext
doc/src/sgml/libpq.sgml,plaintext,https://www.postgresql.org/docs/devel/libpq-connect.html,...fallback to plaintext authentication...,Change to cleartext
doc/src/sgml/logical-replication.sgml,plain text,https://www.postgresql.org/docs/devel/logical-replication-subscription.html,"Conflicts that occur during replication are, by default, logged as plain text in the server log",No change
doc/src/sgml/maintenance.sgml,plaintext,https://www.postgresql.org/docs/devel/logfile-maintenance.html,...some DDL statements might contain plaintext passwords...,Change to cleartext
doc/src/sgml/nls.sgml,plain text,https://www.postgresql.org/docs/devel/nls-translator.html,...a plain text file with special syntax...,No change
doc/src/sgml/passwordcheck.sgml,clear text,https://www.postgresql.org/docs/devel/passwordcheck.html,...forcing users to set their passwords in clear text...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,clear text,https://www.postgresql.org/docs/devel/pgcrypto.html,...passwords move between pgcrypto and client applications in clear text...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,plaintext,https://www.postgresql.org/docs/devel/pgcrypto.html,...guarantee that the decrypted plaintext actually originated from...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,plaintext,https://www.postgresql.org/docs/devel/pgcrypto.html,Recovering such plaintext via pgcrypto requires...,Change to cleartext
doc/src/sgml/pgcrypto.sgml,plaintext,https://www.postgresql.org/docs/devel/pgcrypto.html,...does not make the recovered plaintext trustworthy.,Change to cleartext
doc/src/sgml/postgres-fdw.sgml,plain-text,https://www.postgresql.org/docs/devel/postgres-fdw.html,...instead of plain-text user passwords to connect to the remote server. ,Change to cleartext
doc/src/sgml/postgres-fdw.sgml,plain-text,https://www.postgresql.org/docs/devel/postgres-fdw.html,This avoids storing plain-text user passwords...,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,https://www.postgresql.org/docs/devel/protocol-flow.html,...PasswordMessage containing the password in clear-text form.,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,https://www.postgresql.org/docs/devel/protocol-message-formats.html,Specifies that a clear-text password is required.,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,https://www.postgresql.org/docs/devel/sasl-authentication.html,...like a clear-text password.,Change to cleartext
doc/src/sgml/protocol.sgml,clear-text,www.postgresql.org/docs/devel/protocol-flow.html,...containing the password in clear-text form.,Change to cleartext
doc/src/sgml/protocol.sgml,cleartext,https://www.postgresql.org/docs/devel/protocol-flow.html,<term>AuthenticationCleartextPassword</term>,No change
doc/src/sgml/protocol.sgml,cleartext,https://www.postgresql.org/docs/devel/protocol-message-formats.html,"<varlistentry id=""protocol-message-formats-AuthenticationCleartextPassword"">",No change
doc/src/sgml/protocol.sgml,cleartext,https://www.postgresql.org/docs/devel/protocol-message-formats.html,<term>AuthenticationCleartextPassword (B)</term>,No change
doc/src/sgml/ref/alter_role.sgml,cleartext,https://www.postgresql.org/docs/devel/sql-alterrole.html,The password will be transmitted to the server in cleartext...,No change
doc/src/sgml/ref/alter_role.sgml,cleartext,https://www.postgresql.org/docs/devel/sql-alterrole.html,without exposing the cleartext password...,No change
doc/src/sgml/ref/create_role.sgml,cleartext,https://www.postgresql.org/docs/devel/sql-createrole.html,The password will be transmitted to the server in cleartext...,No change
doc/src/sgml/ref/pg_dump.sgml,plain text,https://www.postgresql.org/docs/devel/app-pgdump.html,For plain text output...,No change
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,This can only be specified for plain-text dumps...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,...when restoring a database from a plain-text pg_dump script...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,...dumps are plain-text files...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,Output a plain-text SQL script file...,Change to plain text
doc/src/sgml/ref/pg_dump.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgdump.html,Non-plain-text dumps...,Change to plain text
doc/src/sgml/ref/pg_restore.sgml,plain text,https://www.postgresql.org/docs/devel/app-pgrestore.html,...is equivalent to the plain text output format...,No change
doc/src/sgml/ref/pg_restore.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgrestore.html,one of the non-plain-text formats,Change to plain text
doc/src/sgml/ref/pg_restore.sgml,plain-text,https://www.postgresql.org/docs/devel/app-pgrestore.html,Non-plain-text dumps,Change to plain text
doc/src/sgml/ref/psql-ref.sgml,cleartext,https://www.postgresql.org/docs/devel/app-psql.html,...the new password does not appear in cleartext...,No change
doc/src/sgml/ref/psql-ref.sgml,plain-text,https://www.postgresql.org/docs/devel/app-psql.html,...for use in plain-text dumps...,Change to plain text
doc/src/sgml/ref/psql-ref.sgml,plain-text,https://www.postgresql.org/docs/devel/app-psql.html,...for use in plain-text dumps...,Change to plain text
doc/src/sgml/sources.sgml,plain text,https://www.postgresql.org/docs/devel/source-format.html,...will re-flow indented comment blocks as though they were plain text.,No change
doc/src/sgml/uuid-ossp.sgml,cleartext,https://www.postgresql.org/docs/devel/uuid-ossp.html,"The name parameter will be MD5-hashed, so the cleartext cannot be derived from the generated UUID.",No change
v1-0001-Doc-standardise-cleartext-and-plain-text-terms.patch (application/octet-stream, 19.9K) download
From 48783b01f00c7a910abd926ad495c5fd6132d19f Mon Sep 17 00:00:00 2001
From: Karen Jex <karenhjex@gmail.com>
Date: Tue, 10 Nov 2026 17:09:48 +0100
Subject: [PATCH v1] Doc: standardise cleartext and plain text terms
---
doc/src/sgml/catalogs.sgml | 2 +-
doc/src/sgml/client-auth.sgml | 16 ++++++++--------
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/dblink.sgml | 4 ++--
doc/src/sgml/docguide.sgml | 2 +-
doc/src/sgml/func/func-trigger.sgml | 4 ++--
doc/src/sgml/libpq.sgml | 4 ++--
doc/src/sgml/maintenance.sgml | 2 +-
doc/src/sgml/passwordcheck.sgml | 2 +-
doc/src/sgml/pgcrypto.sgml | 8 ++++----
doc/src/sgml/postgres-fdw.sgml | 4 ++--
doc/src/sgml/protocol.sgml | 6 +++---
doc/src/sgml/ref/pg_dump.sgml | 10 +++++-----
doc/src/sgml/ref/pg_restore.sgml | 4 ++--
doc/src/sgml/ref/psql-ref.sgml | 4 ++--
15 files changed, 37 insertions(+), 37 deletions(-)
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 78cce7e370d..942e7fbefee 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8030,7 +8030,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
<para>
Access to the column <structfield>subconninfo</structfield> is revoked from
- normal users, because it could contain plain-text passwords.
+ normal users, because it could contain cleartext passwords.
</para>
<table>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 873ddd8f068..b7211b3cf71 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -549,7 +549,7 @@ include_dir <replaceable>directory</replaceable>
<para>
Require the client to supply an unencrypted password for
authentication.
- Since the password is sent in clear text over the
+ Since the password is sent in cleartext over the
network, this should not be used on untrusted networks.
See <xref linkend="auth-password"/> for details.
</para>
@@ -652,7 +652,7 @@ include_dir <replaceable>directory</replaceable>
<listitem>
<para>
Authorize and optionally authenticate using a third-party OAuth 2.0
- identity provider. Since the bearer token is sent in clear text over
+ identity provider. Since the bearer token is sent in cleartext over
the network, this should not be used on untrusted networks. See
<xref linkend="auth-oauth"/> for details.
</para>
@@ -1258,7 +1258,7 @@ omicron bryanh guest1
<para>
The method <literal>md5</literal> uses a custom less secure challenge-response
mechanism. It prevents password sniffing and avoids storing passwords
- on the server in plain text but provides no protection if an attacker
+ on the server in cleartext but provides no protection if an attacker
manages to steal the password hash from the server. Also, the MD5 hash
algorithm is nowadays no longer considered secure against determined
attacks.
@@ -1286,7 +1286,7 @@ omicron bryanh guest1
<term><literal>password</literal></term>
<listitem>
<para>
- The method <literal>password</literal> sends the password in clear-text and is
+ The method <literal>password</literal> sends the password in cleartext and is
therefore vulnerable to password <quote>sniffing</quote> attacks. It should
always be avoided if possible. If the connection is protected by SSL
encryption then <literal>password</literal> can be used safely, though.
@@ -1320,15 +1320,15 @@ omicron bryanh guest1
the <literal>scram-sha-256</literal> setting, then it can be used for the
authentication methods <literal>scram-sha-256</literal>
and <literal>password</literal> (but password transmission will be in
- plain text in the latter case). The authentication method
+ cleartext in the latter case). The authentication method
specification <literal>md5</literal> will automatically switch to using
the <literal>scram-sha-256</literal> method in this case, as explained
above, so it will also work. If a password was encrypted using
the <literal>md5</literal> setting, then it can be used only for
the <literal>md5</literal> and <literal>password</literal> authentication
- method specifications (again, with the password transmitted in plain text
+ method specifications (again, with the password transmitted in cleartext
in the latter case). (Previous PostgreSQL releases supported storing the
- password on the server in plain text. This is no longer possible.) To
+ password on the server in cleartext. This is no longer possible.) To
check the currently stored password hashes, see the system
catalog <literal>pg_authid</literal>.
</para>
@@ -2344,7 +2344,7 @@ host ... ldap ldapbasedn="dc=example,dc=net"
which are a type of access token used with OAuth 2.0 where the token is an
opaque string. The format of the access token is implementation specific
and is chosen by each authorization server. The bearer token is sent
- in clear-text, and is vulnerable to network sniffing. For this reason
+ in cleartext, and is vulnerable to network sniffing. For this reason
OAuth should only be used over SSL connections.
</para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index a6a2df177f2..a3f5f816356 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -8646,7 +8646,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a '
</para>
<para>
Logged statements might reveal sensitive data and even contain
- plaintext passwords.
+ cleartext passwords.
</para>
</note>
</listitem>
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index fc496b74288..9120295d019 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -157,9 +157,9 @@ dblink_connect(text connname, text connstr) returns text
authentication to connect to the remote database. It can be specified
for a foreign server or a user mapping. A user mapping setting overrides
the foreign server setting. With SCRAM pass-through authentication,
- <filename>dblink</filename> uses SCRAM-hashed secrets instead of plain-text
+ <filename>dblink</filename> uses SCRAM-hashed secrets instead of cleartext
user passwords to connect to the remote server. This avoids storing
- plain-text user passwords in PostgreSQL system catalogs.
+ cleartext user passwords in PostgreSQL system catalogs.
See the documentation of the equivalent <link
linkend="postgres-fdw-option-use-scram-passthrough"><literal>use_scram_passthrough</literal></link>
option of postgres_fdw for further details and restrictions.
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index a91b386817c..866f4a6ce51 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -30,7 +30,7 @@
</listitem>
</itemizedlist>
- Additionally, a number of plain-text <filename>README</filename> files can
+ Additionally, a number of plain text <filename>README</filename> files can
be found throughout the <productname>PostgreSQL</productname> source tree,
documenting various implementation issues.
</para>
diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml
index 94b40adbdb8..a212fcadfc5 100644
--- a/doc/src/sgml/func/func-trigger.sgml
+++ b/doc/src/sgml/func/func-trigger.sgml
@@ -60,7 +60,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is specified by name as a trigger argument. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
@@ -79,7 +79,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is taken from a <type>regconfig</type> column of the table. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index b213a266cb2..3caaea91137 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1330,7 +1330,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<term><literal>password</literal></term>
<listitem>
<para>
- The server must request plaintext password authentication.
+ The server must request cleartext password authentication.
</para>
</listitem>
</varlistentry>
@@ -1851,7 +1851,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
start SSL handshake directly after establishing the TCP/IP
connection. This is only allowed with
<literal>sslmode=require</literal> or higher, because the weaker
- settings could lead to unintended fallback to plaintext
+ settings could lead to unintended fallback to cleartext
authentication when the server does not support direct SSL
handshake.
</para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index e3f5cedd589..e3cc7ad01db 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1291,7 +1291,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<para>
The server log can contain sensitive information and needs to be protected,
no matter how or where it is stored, or the destination to which it is routed.
- For example, some DDL statements might contain plaintext passwords or other
+ For example, some DDL statements might contain cleartext passwords or other
authentication details. Logged statements at the <literal>ERROR</literal>
level might show the SQL source code for applications
and might also contain some parts of data rows. Recording data, events and
diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml
index 7ea32410463..d8b061738e4 100644
--- a/doc/src/sgml/passwordcheck.sgml
+++ b/doc/src/sgml/passwordcheck.sgml
@@ -55,7 +55,7 @@
<para>
Alternatively, you could modify <filename>passwordcheck</filename>
to reject pre-encrypted passwords, but forcing users to set their
- passwords in clear text carries its own security risks.
+ passwords in cleartext carries its own security risks.
</para>
</caution>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 00a35f3715c..b1ef6075e40 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -980,19 +980,19 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt
created when the <literal>cipher-algo</literal> was unavailable under the
OpenSSL configuration in use. Such faulty messages do not require the
correct decryption key when <literal>ignore-cipher-failure</literal> is
- enabled, so there is no guarantee that the decrypted plaintext actually
+ enabled, so there is no guarantee that the decrypted cleartext actually
originated from a holder of the key.
</para>
<para>
Contrast the case of a message which was correctly encrypted, but the cipher
that produced it is unavailable under the current <productname>OpenSSL</productname>
- configuration. Recovering such plaintext via <filename>pgcrypto</filename>
+ configuration. Recovering such cleartext via <filename>pgcrypto</filename>
requires making the actual cipher available to OpenSSL by, for example,
enabling the appropriate provider. <literal>ignore-cipher-failure</literal>
is not necessary or helpful for that scenario. If <quote>decryption</quote>
of a correctly encrypted message with this option happens to pass PGP
integrity checks, that result is coincidental and does not make the
- recovered plaintext trustworthy.
+ recovered cleartext trustworthy.
</para>
<literallayout>
Values: 0, 1
@@ -1338,7 +1338,7 @@ fips_mode() returns boolean
All <filename>pgcrypto</filename> functions run inside the database server.
That means that all
the data and passwords move between <filename>pgcrypto</filename> and client
- applications in clear text. Thus you must:
+ applications in cleartext. Thus you must:
</para>
<orderedlist>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 01577d8d69b..cab065405b2 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -815,8 +815,8 @@ OPTIONS (ADD password_required 'false');
A user mapping setting overrides the foreign server setting.
With SCRAM pass-through authentication,
<filename>postgres_fdw</filename> uses SCRAM-hashed secrets instead of
- plain-text user passwords to connect to the remote server. This
- avoids storing plain-text user passwords in PostgreSQL system
+ cleartext user passwords to connect to the remote server. This
+ avoids storing cleartext user passwords in PostgreSQL system
catalogs.
</para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 541673eb282..50ce1cbdb32 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -471,7 +471,7 @@
<listitem>
<para>
The frontend must now send a PasswordMessage containing the
- password in clear-text form. If
+ password in cleartext form. If
this is the correct password, the server responds with an
AuthenticationOk, otherwise it responds with an ErrorResponse.
</para>
@@ -2087,7 +2087,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<note>
<para>
The bearer token is sent across the connection, as part of the client
- initial response, and grants access to the database like a clear-text
+ initial response, and grants access to the database like a cleartext
password. On an unencrypted connection it can be captured by network
sniffing. For this reason <literal>OAUTHBEARER</literal> should only be
used over SSL connections.
@@ -3923,7 +3923,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32(3)</term>
<listitem>
<para>
- Specifies that a clear-text password is required.
+ Specifies that a cleartext password is required.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 774be23b4f9..d601733f197 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -56,7 +56,7 @@ PostgreSQL documentation
<para>
Dumps can be output in script or archive file formats. Script
- dumps are plain-text files containing the SQL commands required
+ dumps are plain text files containing the SQL commands required
to reconstruct the database to the state it was in at the time it was
saved. To restore from such a script, feed it to <xref
linkend="app-psql"/>. Script files
@@ -101,7 +101,7 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Non-plain text dumps can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
@@ -315,7 +315,7 @@ PostgreSQL documentation
<term><literal>plain</literal></term>
<listitem>
<para>
- Output a plain-text <acronym>SQL</acronym> script file (the default).
+ Output a plain text <acronym>SQL</acronym> script file (the default).
</para>
</listitem>
</varlistentry>
@@ -1236,7 +1236,7 @@ PostgreSQL documentation
<para>
Use the provided string as the <application>psql</application>
<command>\restrict</command> key in the dump output. This can only be
- specified for plain-text dumps, i.e., when <option>--format</option> is
+ specified for plain text dumps, i.e., when <option>--format</option> is
set to <literal>plain</literal> or the <option>--format</option> option
is omitted. If no restrict key is specified,
<application>pg_dump</application> will generate a random one as
@@ -1740,7 +1740,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para>
It is generally recommended to use the <option>-X</option>
(<option>--no-psqlrc</option>) option when restoring a database from a
- plain-text <application>pg_dump</application> script to ensure a clean
+ plain text <application>pg_dump</application> script to ensure a clean
restore process and prevent potential conflicts with
non-default <application>psql</application> configurations.
</para>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 98d7456e83b..b7ad2f116da 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -39,7 +39,7 @@ PostgreSQL documentation
<para>
<application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive
- created by <xref linkend="app-pgdump"/> in one of the non-plain-text
+ created by <xref linkend="app-pgdump"/> in one of the non-plain text
formats. It will issue the commands necessary to reconstruct the
database to the state it was in at the time it was saved. The
archive files also allow <application>pg_restore</application> to
@@ -74,7 +74,7 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Non-plain text dumps can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 4058caf061b..b0f86e931ab 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3587,7 +3587,7 @@ SELECT $1 \parse stmt1
restricted mode. The key may contain only alphanumeric characters.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
@@ -3856,7 +3856,7 @@ SELECT 1 \bind \sendpipeline
<command>\restrict</command> when restricted mode was entered.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
--
2.50.1 (Apple Git-155)
^ permalink raw reply [nested|flat] 21+ messages in thread
* RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-10 19:29 Xavier Fischer <xavier_fischer@hotmail.fr>
parent: Karen Jex <karenhjex@gmail.com>
1 sibling, 1 reply; 21+ messages in thread
From: Xavier Fischer @ 2026-11-10 19:29 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; David E. Wheeler <david@justatheory.com>; +Cc: Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Hi! I was one of the attendees of the PGConfEU talk too (asked about whether images in the were encouraged, and heard Daniel's call for action regarding docs patches review).
I'd like to help and will start to review your changes Karen.
________________________________
De : Karen Jex <karenhjex@gmail.com>
Envoyé : mardi 10 novembre 2026 17:30
À : David E. Wheeler <david@justatheory.com>
Cc : Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Objet : Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Le ven. 6 nov. 2026 à 20:16, Karen Jex <karenhjex@gmail.com> a écrit :
> I see that the cleartext Wikipedia entry redirects to plaintext:
> https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FPlainte...;, which implies that plaintext
> may be the preferred term.
I originally thought we should standardise on "plaintext", but after
reviewing the ways in which the terms are used throughout the docs, I
propose the following approach:
1. Use "plain text" to indicate unformatted text: e.g. "...a plain
text file with special syntax that translators edit."
(https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2Fdevel...;).
2. Use "cleartext" to indicate unencrypted passwords/secrets: e.g. "It
is good practice not to send the original cleartext password..."
(https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2Fdevel...;).
This is consistent with the AuthenticationCleartextPassword server
message referenced on the same page.
This is consistent with the vocabulary that is used most often in the
documentation, and the terms are different enough to avoid
confusion/ambiguity.
I attach the proposed patch and, for completeness, a csv file that
lists the proposed changes. I would be very grateful for any feedback
before I submit it to -hackers.
--
Karen
^ permalink raw reply [nested|flat] 21+ messages in thread
* RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-10 20:56 Xavier Fischer <xavier_fischer@hotmail.fr>
parent: Xavier Fischer <xavier_fischer@hotmail.fr>
0 siblings, 0 replies; 21+ messages in thread
From: Xavier Fischer @ 2026-11-10 20:56 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; David E. Wheeler <david@justatheory.com>; +Cc: Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
I ran a grep on the docs and found the same occurences. I agree with your changes Karen.
________________________________
De : Xavier Fischer <xavier_fischer@hotmail.fr>
Envoyé : mardi 10 novembre 2026 20:29
À : Karen Jex <karenhjex@gmail.com>; David E. Wheeler <david@justatheory.com>
Cc : Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Objet : RE: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Hi! I was one of the attendees of the PGConfEU talk too (asked about whether images in the were encouraged, and heard Daniel's call for action regarding docs patches review).
I'd like to help and will start to review your changes Karen.
________________________________
De : Karen Jex <karenhjex@gmail.com>
Envoyé : mardi 10 novembre 2026 17:30
À : David E. Wheeler <david@justatheory.com>
Cc : Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Objet : Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
Le ven. 6 nov. 2026 à 20:16, Karen Jex <karenhjex@gmail.com> a écrit :
> I see that the cleartext Wikipedia entry redirects to plaintext:
> https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FPlainte...;, which implies that plaintext
> may be the preferred term.
I originally thought we should standardise on "plaintext", but after
reviewing the ways in which the terms are used throughout the docs, I
propose the following approach:
1. Use "plain text" to indicate unformatted text: e.g. "...a plain
text file with special syntax that translators edit."
(https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2Fdevel...;).
2. Use "cleartext" to indicate unencrypted passwords/secrets: e.g. "It
is good practice not to send the original cleartext password..."
(https://emea01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.postgresql.org%2Fdocs%2Fdevel...;).
This is consistent with the AuthenticationCleartextPassword server
message referenced on the same page.
This is consistent with the vocabulary that is used most often in the
documentation, and the terms are different enough to avoid
confusion/ambiguity.
I attach the proposed patch and, for completeness, a csv file that
lists the proposed changes. I would be very grateful for any feedback
before I submit it to -hackers.
--
Karen
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-11 07:22 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Karen Jex <karenhjex@gmail.com>
1 sibling, 1 reply; 21+ messages in thread
From: Laurenz Albe @ 2026-11-11 07:22 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; David E. Wheeler <david@justatheory.com>; +Cc: Karen Jex <karenjex@hotmail.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Tue, 2026-11-10 at 17:30 +0100, Karen Jex wrote:
> I originally thought we should standardise on "plaintext", but after
> reviewing the ways in which the terms are used throughout the docs, I
> propose the following approach:
>
> 1. Use "plain text" to indicate unformatted text: e.g. "...a plain
> text file with special syntax that translators edit."
> (https://www.postgresql.org/docs/devel/nls-translator.html#NLS-TRANSLATOR-CONCEPTS).
>
> 2. Use "cleartext" to indicate unencrypted passwords/secrets: e.g. "It
> is good practice not to send the original cleartext password..."
> (https://www.postgresql.org/docs/devel/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN).
> This is consistent with the AuthenticationCleartextPassword server
> message referenced on the same page.
>
> This is consistent with the vocabulary that is used most often in the
> documentation, and the terms are different enough to avoid
> confusion/ambiguity.
>
> I attach the proposed patch and, for completeness, a csv file that
> lists the proposed changes. I would be very grateful for any feedback
> before I submit it to -hackers.
Submitting the patch to pgsql-docs is good enough; you don't need to
re-send it to -hackers (but you can do that of course). You can have a
commitfest entry point to a message in any PostgreSQL mailing list -
just reference the message ID.
I think your choice of "cleartext" and "plain text" is fine. I personally
would feel better about "plain-text" whenever you use it as an adjective
(like in "a plain-text file") and "plain text" for a noun (like "write a
file as plain text"), but I am not a native speaker, and my feeling could
be the German-speaker's preference for compound words. Also, the borders
between noun and adjective in English are blurry ("a fun thing").
There are three occurrences of "non-plain-text" that you changed to
"non-plain text". This feels wrong, since to me the hyphen ties stronger
than the space. I would read that as meaning something like "compound text".
I'd suggest that you rewrite those sentences to avoid the construct.
You could add some of the considerations that led to your choice of words
to the commit message, as well as "Author:", "Reviewed-By:" and
"Discussion:" tags (see other commit messages). It would save the
committer some keystrokes.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-11 10:58 Peter Eisentraut <peter@eisentraut.org>
parent: David E. Wheeler <david@justatheory.com>
1 sibling, 1 reply; 21+ messages in thread
From: Peter Eisentraut @ 2026-11-11 10:58 UTC (permalink / raw)
To: David E. Wheeler <david@justatheory.com>; Karen Jex <karenjex@hotmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On 06.11.26 15:49, David E. Wheeler wrote:
> On Nov 6, 2026, at 09:44, Karen Jex <karenjex@hotmail.com> wrote:
>
>> I would love to take this on - thank you for flagging it as a potential first doc-hacking task.
>
>
> Yay!
>
>> Just to confirm my understanding:
>> 1. We should use "cleartext" and "plaintext" throughout, not "clear-text", "clear text", "plain text" or "plain-text".
>> 2. There is at least one case where "plaintext" is used incorrectly in place of "cleartext”.
>
> I thought these were synonyms, in contrast to “ciphertext”. Should we not pick one to replace all of the others? Searching around a bit, it seems like “ciphertext” and “plaintext” are most often contrasting terms, e.g., https://en.wikipedia.org/wiki/Ciphertext.
My understanding is/was that plaintext is data meant for encryption,
after which it becomes ciphertext. Cleartext is data not meant for
encryption.
So you would use plaintext and ciphertext when describing the steps of
an encryption method. And you would use cleartext when describing what
goes over the wire when you do do LDAP authentication in PostgreSQL.
But it seems like these terms are not actually universally used that
way. If we tidy this up, consider adding glossary entries.
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-11 11:43 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 21+ messages in thread
From: Daniel Gustafsson @ 2026-11-11 11:43 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: David E. Wheeler <david@justatheory.com>; Karen Jex <karenjex@hotmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
> On 11 Nov 2026, at 11:58, Peter Eisentraut <peter@eisentraut.org> wrote:
Thanks for working on this Karen!
> My understanding is/was that plaintext is data meant for encryption, after which it becomes ciphertext. Cleartext is data not meant for encryption.
That's my understanding as well, but it's not standardized anywhere and
scanning relevant RFC's didn't provide any real guidance.
> If we tidy this up, consider adding glossary entries.
+1
> There are three occurrences of "non-plain-text" that you changed to
> "non-plain text". This feels wrong, since to me the hyphen ties stronger
> than the space. I would read that as meaning something like "compound text".
> I'd suggest that you rewrite those sentences to avoid the construct.
non-plain-text was never good for non-native speakers, and this didn't improve
it. I agree with trying to rewrite the sentences to avoid this construct.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-11 14:35 Karen Jex <karenhjex@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 0 replies; 21+ messages in thread
From: Karen Jex @ 2026-11-11 14:35 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: David E. Wheeler <david@justatheory.com>; Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Le mer. 11 nov. 2026 à 08:22, Laurenz Albe <laurenz.albe@cybertec.at> a écrit :
>
> Submitting the patch to pgsql-docs is good enough; you don't need to
> re-send it to -hackers (but you can do that of course). You can have a
> commitfest entry point to a message in any PostgreSQL mailing list -
> just reference the message ID.
ack
>
> I think your choice of "cleartext" and "plain text" is fine. I personally
> would feel better about "plain-text" whenever you use it as an adjective
> (like in "a plain-text file") and "plain text" for a noun (like "write a
> file as plain text"), but I am not a native speaker, and my feeling could
> be the German-speaker's preference for compound words. Also, the borders
> between noun and adjective in English are blurry ("a fun thing").
>
In strict grammatical terms, you are entirely correct! It "should" be
"a plain-text file". Unfortunately, computer folks appear to have
standardised on "plain text" without a hyphen in this case. I've
followed this convention rather than the more grammatically correct
version to be consistent with the way in which it is most commonly
used.
> There are three occurrences of "non-plain-text" that you changed to
> "non-plain text". This feels wrong, since to me the hyphen ties stronger
> than the space. I would read that as meaning something like "compound text".
> I'd suggest that you rewrite those sentences to avoid the construct.
>
Agreed - rewriting makes sense. None of the alternatives that I found
for the construct appeared any better.
> You could add some of the considerations that led to your choice of words
> to the commit message, as well as "Author:", "Reviewed-By:" and
> "Discussion:" tags (see other commit messages). It would save the
> committer some keystrokes.
Will do. Thank you for the suggestions.
Regards,
--
Karen
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-11 15:16 Karen Jex <karenhjex@gmail.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-11 15:16 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
> > My understanding is/was that plaintext is data meant for encryption, after which it becomes ciphertext. Cleartext is data not meant for encryption.
>
> That's my understanding as well, but it's not standardized anywhere and
> scanning relevant RFC's didn't provide any real guidance.
>
> > If we tidy this up, consider adding glossary entries.
>
> +1
I can attempt to split out cleartext and plaintext entries if there's
appetite for that, but I suspect that may actually confuse things
rather than clarifying them. Instead, I propose the following glossary
entries to define the way in which we're using the terms:
plain text
Unformatted, human-readable text that consists of a sequence of
printable characters in a character encoding such as UTF-8.
cleartext
Unencrypted data; data that exists in an unprotected, readable format
during storage or transmission. Sometimes used as a synonym for
plaintext; the input to an encryption algorithm.
>
> > There are three occurrences of "non-plain-text" that you changed to
> > "non-plain text". This feels wrong, since to me the hyphen ties stronger
> > than the space. I would read that as meaning something like "compound text".
> > I'd suggest that you rewrite those sentences to avoid the construct.
>
> non-plain-text was never good for non-native speakers, and this didn't improve
> it. I agree with trying to rewrite the sentences to avoid this construct.
>
Agreed - I'll find alternative wording.
Regards,
--
Karen
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-12 09:11 Daniel Gustafsson <daniel@yesql.se>
parent: Karen Jex <karenhjex@gmail.com>
0 siblings, 1 reply; 21+ messages in thread
From: Daniel Gustafsson @ 2026-11-12 09:11 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; +Cc: Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
> On 11 Nov 2026, at 16:16, Karen Jex <karenhjex@gmail.com> wrote:
> I can attempt to split out cleartext and plaintext entries if there's
> appetite for that, but I suspect that may actually confuse things
> rather than clarifying them.
Agreed; we should write the docs for postgres users, knowledge of terminology
in cryptography should not be a prerequisite.
> Instead, I propose the following glossary
> entries to define the way in which we're using the terms:
>
> plain text
> Unformatted, human-readable text that consists of a sequence of
> printable characters in a character encoding such as UTF-8.
>
> cleartext
> Unencrypted data; data that exists in an unprotected, readable format
> during storage or transmission. Sometimes used as a synonym for
> plaintext; the input to an encryption algorithm.
Sounds good. I was trying to make the cleartext entry specify that it is
generally data which is intended as input to processing, but I wasn't
particularly successful in creating anything which reads better than what you
have above.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-12 16:24 Karen Jex <karenhjex@gmail.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-12 16:24 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
> > Instead, I propose the following glossary
> > entries to define the way in which we're using the terms:
> >
> > plain text
> > Unformatted, human-readable text that consists of a sequence of
> > printable characters in a character encoding such as UTF-8.
> >
> > cleartext
> > Unencrypted data; data that exists in an unprotected, readable format
> > during storage or transmission. Sometimes used as a synonym for
> > plaintext; the input to an encryption algorithm.
>
> Sounds good. I was trying to make the cleartext entry specify that it is
> generally data which is intended as input to processing, but I wasn't
> particularly successful in creating anything which reads better than what you
> have above.
I've created a V2 patch (attached) including the glossary terms, and
with a verbose commit message as suggested by Laurenz.
> I ran a grep on the docs and found the same occurences. I agree with your changes Karen.
Thank you for the review, Xavier.
And thank you, all, for the helpful discussion and suggestions.
Regards,
--
Karen
Attachments:
v2-0001-Doc-standardise-cleartext-and-plain-text-terms.patch (application/octet-stream, 22.7K) download
From 45cfab5980099ea0e25ae2e84e451331cf6b14b9 Mon Sep 17 00:00:00 2001
From: Karen Jex <karenhjex@gmail.com>
Date: Tue, 10 Nov 2026 17:09:48 +0100
Subject: [PATCH v2] Doc: standardise cleartext and plain text terms
Replace variations of "plain text", plaintext, plain-text, "clear text",
cleartext and clear-text with either "plain text" or cleartext depending on
context.
Use cleartext to refer to unencrypted data in storage or transmission.
Use cleartext instead of plaintext because; it is consistent with the
AuthenticationCleartextPassword server message, it is the term most used
throughout the Postgres docs, and it is different enough from "plain text" not
to cause confusion.
Treat cleartext as a synonym for plaintext. Although not entirely accurate from
a cryptography point of view, where plaintext is defined as the input to a data
encrpytion algorythm or the output of a decryption process, the terms are used
synonymously in many places, and are likely to be understood as synonyms by the
majority of Postgres users.
Use "plain text" to refer to unformatted, human-readable text. This was
selected instead of the hyphenated plain-text because "plain text" is the
standard form across the majority of technical documentation. This is the case
even when it is used as an adjective, for example: "a plain text file".
Rewrite sentences that contain the construct "non-plain-text" in order to
remain consistent and avoid ambiguity.
Add glossary entries to define the terms used.
Author: Karen Jex <karenhjex@gmail.com>
Discussion: https://www.postgresql.org/message-id/CAOpR_fbRg0O_rsrkoJjnPe9aR7ChFuVgABe1rhwq%3D5EzPxt1GA%40mail.gmail.com
---
doc/src/sgml/catalogs.sgml | 2 +-
doc/src/sgml/client-auth.sgml | 16 ++++++++--------
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/dblink.sgml | 4 ++--
doc/src/sgml/docguide.sgml | 2 +-
doc/src/sgml/func/func-trigger.sgml | 4 ++--
doc/src/sgml/glossary.sgml | 21 +++++++++++++++++++++
doc/src/sgml/libpq.sgml | 4 ++--
doc/src/sgml/maintenance.sgml | 2 +-
doc/src/sgml/passwordcheck.sgml | 2 +-
doc/src/sgml/pgcrypto.sgml | 8 ++++----
doc/src/sgml/postgres-fdw.sgml | 4 ++--
doc/src/sgml/protocol.sgml | 6 +++---
doc/src/sgml/ref/pg_dump.sgml | 11 ++++++-----
doc/src/sgml/ref/pg_restore.sgml | 7 ++++---
doc/src/sgml/ref/psql-ref.sgml | 4 ++--
16 files changed, 61 insertions(+), 38 deletions(-)
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 78cce7e370d..942e7fbefee 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8030,7 +8030,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
<para>
Access to the column <structfield>subconninfo</structfield> is revoked from
- normal users, because it could contain plain-text passwords.
+ normal users, because it could contain cleartext passwords.
</para>
<table>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 873ddd8f068..b7211b3cf71 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -549,7 +549,7 @@ include_dir <replaceable>directory</replaceable>
<para>
Require the client to supply an unencrypted password for
authentication.
- Since the password is sent in clear text over the
+ Since the password is sent in cleartext over the
network, this should not be used on untrusted networks.
See <xref linkend="auth-password"/> for details.
</para>
@@ -652,7 +652,7 @@ include_dir <replaceable>directory</replaceable>
<listitem>
<para>
Authorize and optionally authenticate using a third-party OAuth 2.0
- identity provider. Since the bearer token is sent in clear text over
+ identity provider. Since the bearer token is sent in cleartext over
the network, this should not be used on untrusted networks. See
<xref linkend="auth-oauth"/> for details.
</para>
@@ -1258,7 +1258,7 @@ omicron bryanh guest1
<para>
The method <literal>md5</literal> uses a custom less secure challenge-response
mechanism. It prevents password sniffing and avoids storing passwords
- on the server in plain text but provides no protection if an attacker
+ on the server in cleartext but provides no protection if an attacker
manages to steal the password hash from the server. Also, the MD5 hash
algorithm is nowadays no longer considered secure against determined
attacks.
@@ -1286,7 +1286,7 @@ omicron bryanh guest1
<term><literal>password</literal></term>
<listitem>
<para>
- The method <literal>password</literal> sends the password in clear-text and is
+ The method <literal>password</literal> sends the password in cleartext and is
therefore vulnerable to password <quote>sniffing</quote> attacks. It should
always be avoided if possible. If the connection is protected by SSL
encryption then <literal>password</literal> can be used safely, though.
@@ -1320,15 +1320,15 @@ omicron bryanh guest1
the <literal>scram-sha-256</literal> setting, then it can be used for the
authentication methods <literal>scram-sha-256</literal>
and <literal>password</literal> (but password transmission will be in
- plain text in the latter case). The authentication method
+ cleartext in the latter case). The authentication method
specification <literal>md5</literal> will automatically switch to using
the <literal>scram-sha-256</literal> method in this case, as explained
above, so it will also work. If a password was encrypted using
the <literal>md5</literal> setting, then it can be used only for
the <literal>md5</literal> and <literal>password</literal> authentication
- method specifications (again, with the password transmitted in plain text
+ method specifications (again, with the password transmitted in cleartext
in the latter case). (Previous PostgreSQL releases supported storing the
- password on the server in plain text. This is no longer possible.) To
+ password on the server in cleartext. This is no longer possible.) To
check the currently stored password hashes, see the system
catalog <literal>pg_authid</literal>.
</para>
@@ -2344,7 +2344,7 @@ host ... ldap ldapbasedn="dc=example,dc=net"
which are a type of access token used with OAuth 2.0 where the token is an
opaque string. The format of the access token is implementation specific
and is chosen by each authorization server. The bearer token is sent
- in clear-text, and is vulnerable to network sniffing. For this reason
+ in cleartext, and is vulnerable to network sniffing. For this reason
OAuth should only be used over SSL connections.
</para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index a6a2df177f2..a3f5f816356 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -8646,7 +8646,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a '
</para>
<para>
Logged statements might reveal sensitive data and even contain
- plaintext passwords.
+ cleartext passwords.
</para>
</note>
</listitem>
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index fc496b74288..9120295d019 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -157,9 +157,9 @@ dblink_connect(text connname, text connstr) returns text
authentication to connect to the remote database. It can be specified
for a foreign server or a user mapping. A user mapping setting overrides
the foreign server setting. With SCRAM pass-through authentication,
- <filename>dblink</filename> uses SCRAM-hashed secrets instead of plain-text
+ <filename>dblink</filename> uses SCRAM-hashed secrets instead of cleartext
user passwords to connect to the remote server. This avoids storing
- plain-text user passwords in PostgreSQL system catalogs.
+ cleartext user passwords in PostgreSQL system catalogs.
See the documentation of the equivalent <link
linkend="postgres-fdw-option-use-scram-passthrough"><literal>use_scram_passthrough</literal></link>
option of postgres_fdw for further details and restrictions.
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index a91b386817c..866f4a6ce51 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -30,7 +30,7 @@
</listitem>
</itemizedlist>
- Additionally, a number of plain-text <filename>README</filename> files can
+ Additionally, a number of plain text <filename>README</filename> files can
be found throughout the <productname>PostgreSQL</productname> source tree,
documenting various implementation issues.
</para>
diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml
index 94b40adbdb8..a212fcadfc5 100644
--- a/doc/src/sgml/func/func-trigger.sgml
+++ b/doc/src/sgml/func/func-trigger.sgml
@@ -60,7 +60,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is specified by name as a trigger argument. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
@@ -79,7 +79,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is taken from a <type>regconfig</type> column of the table. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index d28a3729188..c9f323d716f 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -434,6 +434,17 @@
<glosssee otherterm="glossary-relation" />
</glossentry>
+ <glossentry>
+ <glossterm>Cleartext</glossterm>
+ <glossdef>
+ <para>
+ Unencrypted data; data that exists in an unprotected, readable format
+ during storage or transmission. Sometimes used as a synonym for
+ plaintext; the input to an encryption algorithm.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-client">
<glossterm>Client (process)</glossterm>
<glossdef>
@@ -1362,6 +1373,16 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>Plain text</glossterm>
+ <glossdef>
+ <para>
+ Unformatted, human-readable text that consists of a sequence of printable
+ characters in a character encoding such as UTF-8.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-postmaster">
<glossterm>Postmaster (process)</glossterm>
<glossdef>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index b213a266cb2..3caaea91137 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1330,7 +1330,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<term><literal>password</literal></term>
<listitem>
<para>
- The server must request plaintext password authentication.
+ The server must request cleartext password authentication.
</para>
</listitem>
</varlistentry>
@@ -1851,7 +1851,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
start SSL handshake directly after establishing the TCP/IP
connection. This is only allowed with
<literal>sslmode=require</literal> or higher, because the weaker
- settings could lead to unintended fallback to plaintext
+ settings could lead to unintended fallback to cleartext
authentication when the server does not support direct SSL
handshake.
</para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index e3f5cedd589..e3cc7ad01db 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1291,7 +1291,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<para>
The server log can contain sensitive information and needs to be protected,
no matter how or where it is stored, or the destination to which it is routed.
- For example, some DDL statements might contain plaintext passwords or other
+ For example, some DDL statements might contain cleartext passwords or other
authentication details. Logged statements at the <literal>ERROR</literal>
level might show the SQL source code for applications
and might also contain some parts of data rows. Recording data, events and
diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml
index 7ea32410463..d8b061738e4 100644
--- a/doc/src/sgml/passwordcheck.sgml
+++ b/doc/src/sgml/passwordcheck.sgml
@@ -55,7 +55,7 @@
<para>
Alternatively, you could modify <filename>passwordcheck</filename>
to reject pre-encrypted passwords, but forcing users to set their
- passwords in clear text carries its own security risks.
+ passwords in cleartext carries its own security risks.
</para>
</caution>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 00a35f3715c..b1ef6075e40 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -980,19 +980,19 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt
created when the <literal>cipher-algo</literal> was unavailable under the
OpenSSL configuration in use. Such faulty messages do not require the
correct decryption key when <literal>ignore-cipher-failure</literal> is
- enabled, so there is no guarantee that the decrypted plaintext actually
+ enabled, so there is no guarantee that the decrypted cleartext actually
originated from a holder of the key.
</para>
<para>
Contrast the case of a message which was correctly encrypted, but the cipher
that produced it is unavailable under the current <productname>OpenSSL</productname>
- configuration. Recovering such plaintext via <filename>pgcrypto</filename>
+ configuration. Recovering such cleartext via <filename>pgcrypto</filename>
requires making the actual cipher available to OpenSSL by, for example,
enabling the appropriate provider. <literal>ignore-cipher-failure</literal>
is not necessary or helpful for that scenario. If <quote>decryption</quote>
of a correctly encrypted message with this option happens to pass PGP
integrity checks, that result is coincidental and does not make the
- recovered plaintext trustworthy.
+ recovered cleartext trustworthy.
</para>
<literallayout>
Values: 0, 1
@@ -1338,7 +1338,7 @@ fips_mode() returns boolean
All <filename>pgcrypto</filename> functions run inside the database server.
That means that all
the data and passwords move between <filename>pgcrypto</filename> and client
- applications in clear text. Thus you must:
+ applications in cleartext. Thus you must:
</para>
<orderedlist>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 01577d8d69b..cab065405b2 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -815,8 +815,8 @@ OPTIONS (ADD password_required 'false');
A user mapping setting overrides the foreign server setting.
With SCRAM pass-through authentication,
<filename>postgres_fdw</filename> uses SCRAM-hashed secrets instead of
- plain-text user passwords to connect to the remote server. This
- avoids storing plain-text user passwords in PostgreSQL system
+ cleartext user passwords to connect to the remote server. This
+ avoids storing cleartext user passwords in PostgreSQL system
catalogs.
</para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 541673eb282..50ce1cbdb32 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -471,7 +471,7 @@
<listitem>
<para>
The frontend must now send a PasswordMessage containing the
- password in clear-text form. If
+ password in cleartext form. If
this is the correct password, the server responds with an
AuthenticationOk, otherwise it responds with an ErrorResponse.
</para>
@@ -2087,7 +2087,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<note>
<para>
The bearer token is sent across the connection, as part of the client
- initial response, and grants access to the database like a clear-text
+ initial response, and grants access to the database like a cleartext
password. On an unencrypted connection it can be captured by network
sniffing. For this reason <literal>OAUTHBEARER</literal> should only be
used over SSL connections.
@@ -3923,7 +3923,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32(3)</term>
<listitem>
<para>
- Specifies that a clear-text password is required.
+ Specifies that a cleartext password is required.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 774be23b4f9..75e76f676c1 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -56,7 +56,7 @@ PostgreSQL documentation
<para>
Dumps can be output in script or archive file formats. Script
- dumps are plain-text files containing the SQL commands required
+ dumps are plain text files containing the SQL commands required
to reconstruct the database to the state it was in at the time it was
saved. To restore from such a script, feed it to <xref
linkend="app-psql"/>. Script files
@@ -101,7 +101,8 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Dumps in formats other than plain
+ text can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
@@ -315,7 +316,7 @@ PostgreSQL documentation
<term><literal>plain</literal></term>
<listitem>
<para>
- Output a plain-text <acronym>SQL</acronym> script file (the default).
+ Output a plain text <acronym>SQL</acronym> script file (the default).
</para>
</listitem>
</varlistentry>
@@ -1236,7 +1237,7 @@ PostgreSQL documentation
<para>
Use the provided string as the <application>psql</application>
<command>\restrict</command> key in the dump output. This can only be
- specified for plain-text dumps, i.e., when <option>--format</option> is
+ specified for plain text dumps, i.e., when <option>--format</option> is
set to <literal>plain</literal> or the <option>--format</option> option
is omitted. If no restrict key is specified,
<application>pg_dump</application> will generate a random one as
@@ -1740,7 +1741,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para>
It is generally recommended to use the <option>-X</option>
(<option>--no-psqlrc</option>) option when restoring a database from a
- plain-text <application>pg_dump</application> script to ensure a clean
+ plain text <application>pg_dump</application> script to ensure a clean
restore process and prevent potential conflicts with
non-default <application>psql</application> configurations.
</para>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 98d7456e83b..bff18277c2b 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -39,8 +39,8 @@ PostgreSQL documentation
<para>
<application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive
- created by <xref linkend="app-pgdump"/> in one of the non-plain-text
- formats. It will issue the commands necessary to reconstruct the
+ created by <xref linkend="app-pgdump"/> in a format other than plain text.
+ It will issue the commands necessary to reconstruct the
database to the state it was in at the time it was saved. The
archive files also allow <application>pg_restore</application> to
be selective about what is restored, or even to reorder the items
@@ -74,7 +74,8 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Dumps in formats other than plain
+ text can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 4058caf061b..b0f86e931ab 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3587,7 +3587,7 @@ SELECT $1 \parse stmt1
restricted mode. The key may contain only alphanumeric characters.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
@@ -3856,7 +3856,7 @@ SELECT 1 \bind \sendpipeline
<command>\restrict</command> when restricted mode was entered.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
--
2.50.1 (Apple Git-155)
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-12 16:37 Karen Jex <karenhjex@gmail.com>
parent: Karen Jex <karenhjex@gmail.com>
0 siblings, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-12 16:37 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
>
> I've created a V2 patch (attached) including the glossary terms, and
> with a verbose commit message as suggested by Laurenz.
Apologies, I managed to introduce a couple of typos into my commit
message. V3 patch attached with a correction.
Attachments:
v3-0001-Doc-standardise-cleartext-and-plain-text-terms.patch (application/octet-stream, 22.7K) download
From f884d5595cc102507fe000fa2829b6152579ba68 Mon Sep 17 00:00:00 2001
From: Karen Jex <karenhjex@gmail.com>
Date: Tue, 10 Nov 2026 17:09:48 +0100
Subject: [PATCH v3] Doc: standardise cleartext and plain text terms
Replace variations of "plain text", plaintext, plain-text, "clear text",
cleartext and clear-text with either "plain text" or cleartext depending on
context.
Use cleartext to refer to unencrypted data in storage or transmission.
Use cleartext instead of plaintext because; it is consistent with the
AuthenticationCleartextPassword server message, it is the term most used
throughout the Postgres docs, and it is different enough from "plain text" not
to cause confusion.
Treat cleartext as a synonym for plaintext. Although not entirely accurate from
a cryptography point of view, where plaintext is defined as the input to a data
encryption algorithm or the output of a decryption process, the terms are used
synonymously in many places, and are likely to be understood as synonyms by the
majority of Postgres users.
Use "plain text" to refer to unformatted, human-readable text. This was
selected instead of the hyphenated plain-text because "plain text" is the
standard form across the majority of technical documentation. This is the case
even when it is used as an adjective, for example: "a plain text file".
Rewrite sentences that contain the construct "non-plain-text" in order to
remain consistent and avoid ambiguity.
Add glossary entries to define the terms used.
Author: Karen Jex <karenhjex@gmail.com>
Discussion: https://www.postgresql.org/message-id/CAOpR_fbRg0O_rsrkoJjnPe9aR7ChFuVgABe1rhwq%3D5EzPxt1GA%40mail.gmail.com
---
doc/src/sgml/catalogs.sgml | 2 +-
doc/src/sgml/client-auth.sgml | 16 ++++++++--------
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/dblink.sgml | 4 ++--
doc/src/sgml/docguide.sgml | 2 +-
doc/src/sgml/func/func-trigger.sgml | 4 ++--
doc/src/sgml/glossary.sgml | 21 +++++++++++++++++++++
doc/src/sgml/libpq.sgml | 4 ++--
doc/src/sgml/maintenance.sgml | 2 +-
doc/src/sgml/passwordcheck.sgml | 2 +-
doc/src/sgml/pgcrypto.sgml | 8 ++++----
doc/src/sgml/postgres-fdw.sgml | 4 ++--
doc/src/sgml/protocol.sgml | 6 +++---
doc/src/sgml/ref/pg_dump.sgml | 11 ++++++-----
doc/src/sgml/ref/pg_restore.sgml | 7 ++++---
doc/src/sgml/ref/psql-ref.sgml | 4 ++--
16 files changed, 61 insertions(+), 38 deletions(-)
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 78cce7e370d..942e7fbefee 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8030,7 +8030,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
<para>
Access to the column <structfield>subconninfo</structfield> is revoked from
- normal users, because it could contain plain-text passwords.
+ normal users, because it could contain cleartext passwords.
</para>
<table>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 873ddd8f068..b7211b3cf71 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -549,7 +549,7 @@ include_dir <replaceable>directory</replaceable>
<para>
Require the client to supply an unencrypted password for
authentication.
- Since the password is sent in clear text over the
+ Since the password is sent in cleartext over the
network, this should not be used on untrusted networks.
See <xref linkend="auth-password"/> for details.
</para>
@@ -652,7 +652,7 @@ include_dir <replaceable>directory</replaceable>
<listitem>
<para>
Authorize and optionally authenticate using a third-party OAuth 2.0
- identity provider. Since the bearer token is sent in clear text over
+ identity provider. Since the bearer token is sent in cleartext over
the network, this should not be used on untrusted networks. See
<xref linkend="auth-oauth"/> for details.
</para>
@@ -1258,7 +1258,7 @@ omicron bryanh guest1
<para>
The method <literal>md5</literal> uses a custom less secure challenge-response
mechanism. It prevents password sniffing and avoids storing passwords
- on the server in plain text but provides no protection if an attacker
+ on the server in cleartext but provides no protection if an attacker
manages to steal the password hash from the server. Also, the MD5 hash
algorithm is nowadays no longer considered secure against determined
attacks.
@@ -1286,7 +1286,7 @@ omicron bryanh guest1
<term><literal>password</literal></term>
<listitem>
<para>
- The method <literal>password</literal> sends the password in clear-text and is
+ The method <literal>password</literal> sends the password in cleartext and is
therefore vulnerable to password <quote>sniffing</quote> attacks. It should
always be avoided if possible. If the connection is protected by SSL
encryption then <literal>password</literal> can be used safely, though.
@@ -1320,15 +1320,15 @@ omicron bryanh guest1
the <literal>scram-sha-256</literal> setting, then it can be used for the
authentication methods <literal>scram-sha-256</literal>
and <literal>password</literal> (but password transmission will be in
- plain text in the latter case). The authentication method
+ cleartext in the latter case). The authentication method
specification <literal>md5</literal> will automatically switch to using
the <literal>scram-sha-256</literal> method in this case, as explained
above, so it will also work. If a password was encrypted using
the <literal>md5</literal> setting, then it can be used only for
the <literal>md5</literal> and <literal>password</literal> authentication
- method specifications (again, with the password transmitted in plain text
+ method specifications (again, with the password transmitted in cleartext
in the latter case). (Previous PostgreSQL releases supported storing the
- password on the server in plain text. This is no longer possible.) To
+ password on the server in cleartext. This is no longer possible.) To
check the currently stored password hashes, see the system
catalog <literal>pg_authid</literal>.
</para>
@@ -2344,7 +2344,7 @@ host ... ldap ldapbasedn="dc=example,dc=net"
which are a type of access token used with OAuth 2.0 where the token is an
opaque string. The format of the access token is implementation specific
and is chosen by each authorization server. The bearer token is sent
- in clear-text, and is vulnerable to network sniffing. For this reason
+ in cleartext, and is vulnerable to network sniffing. For this reason
OAuth should only be used over SSL connections.
</para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index a6a2df177f2..a3f5f816356 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -8646,7 +8646,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a '
</para>
<para>
Logged statements might reveal sensitive data and even contain
- plaintext passwords.
+ cleartext passwords.
</para>
</note>
</listitem>
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index fc496b74288..9120295d019 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -157,9 +157,9 @@ dblink_connect(text connname, text connstr) returns text
authentication to connect to the remote database. It can be specified
for a foreign server or a user mapping. A user mapping setting overrides
the foreign server setting. With SCRAM pass-through authentication,
- <filename>dblink</filename> uses SCRAM-hashed secrets instead of plain-text
+ <filename>dblink</filename> uses SCRAM-hashed secrets instead of cleartext
user passwords to connect to the remote server. This avoids storing
- plain-text user passwords in PostgreSQL system catalogs.
+ cleartext user passwords in PostgreSQL system catalogs.
See the documentation of the equivalent <link
linkend="postgres-fdw-option-use-scram-passthrough"><literal>use_scram_passthrough</literal></link>
option of postgres_fdw for further details and restrictions.
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index a91b386817c..866f4a6ce51 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -30,7 +30,7 @@
</listitem>
</itemizedlist>
- Additionally, a number of plain-text <filename>README</filename> files can
+ Additionally, a number of plain text <filename>README</filename> files can
be found throughout the <productname>PostgreSQL</productname> source tree,
documenting various implementation issues.
</para>
diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml
index 94b40adbdb8..a212fcadfc5 100644
--- a/doc/src/sgml/func/func-trigger.sgml
+++ b/doc/src/sgml/func/func-trigger.sgml
@@ -60,7 +60,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is specified by name as a trigger argument. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
@@ -79,7 +79,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is taken from a <type>regconfig</type> column of the table. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index d28a3729188..c9f323d716f 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -434,6 +434,17 @@
<glosssee otherterm="glossary-relation" />
</glossentry>
+ <glossentry>
+ <glossterm>Cleartext</glossterm>
+ <glossdef>
+ <para>
+ Unencrypted data; data that exists in an unprotected, readable format
+ during storage or transmission. Sometimes used as a synonym for
+ plaintext; the input to an encryption algorithm.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-client">
<glossterm>Client (process)</glossterm>
<glossdef>
@@ -1362,6 +1373,16 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>Plain text</glossterm>
+ <glossdef>
+ <para>
+ Unformatted, human-readable text that consists of a sequence of printable
+ characters in a character encoding such as UTF-8.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-postmaster">
<glossterm>Postmaster (process)</glossterm>
<glossdef>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index b213a266cb2..3caaea91137 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1330,7 +1330,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<term><literal>password</literal></term>
<listitem>
<para>
- The server must request plaintext password authentication.
+ The server must request cleartext password authentication.
</para>
</listitem>
</varlistentry>
@@ -1851,7 +1851,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
start SSL handshake directly after establishing the TCP/IP
connection. This is only allowed with
<literal>sslmode=require</literal> or higher, because the weaker
- settings could lead to unintended fallback to plaintext
+ settings could lead to unintended fallback to cleartext
authentication when the server does not support direct SSL
handshake.
</para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index e3f5cedd589..e3cc7ad01db 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1291,7 +1291,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<para>
The server log can contain sensitive information and needs to be protected,
no matter how or where it is stored, or the destination to which it is routed.
- For example, some DDL statements might contain plaintext passwords or other
+ For example, some DDL statements might contain cleartext passwords or other
authentication details. Logged statements at the <literal>ERROR</literal>
level might show the SQL source code for applications
and might also contain some parts of data rows. Recording data, events and
diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml
index 7ea32410463..d8b061738e4 100644
--- a/doc/src/sgml/passwordcheck.sgml
+++ b/doc/src/sgml/passwordcheck.sgml
@@ -55,7 +55,7 @@
<para>
Alternatively, you could modify <filename>passwordcheck</filename>
to reject pre-encrypted passwords, but forcing users to set their
- passwords in clear text carries its own security risks.
+ passwords in cleartext carries its own security risks.
</para>
</caution>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 00a35f3715c..b1ef6075e40 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -980,19 +980,19 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt
created when the <literal>cipher-algo</literal> was unavailable under the
OpenSSL configuration in use. Such faulty messages do not require the
correct decryption key when <literal>ignore-cipher-failure</literal> is
- enabled, so there is no guarantee that the decrypted plaintext actually
+ enabled, so there is no guarantee that the decrypted cleartext actually
originated from a holder of the key.
</para>
<para>
Contrast the case of a message which was correctly encrypted, but the cipher
that produced it is unavailable under the current <productname>OpenSSL</productname>
- configuration. Recovering such plaintext via <filename>pgcrypto</filename>
+ configuration. Recovering such cleartext via <filename>pgcrypto</filename>
requires making the actual cipher available to OpenSSL by, for example,
enabling the appropriate provider. <literal>ignore-cipher-failure</literal>
is not necessary or helpful for that scenario. If <quote>decryption</quote>
of a correctly encrypted message with this option happens to pass PGP
integrity checks, that result is coincidental and does not make the
- recovered plaintext trustworthy.
+ recovered cleartext trustworthy.
</para>
<literallayout>
Values: 0, 1
@@ -1338,7 +1338,7 @@ fips_mode() returns boolean
All <filename>pgcrypto</filename> functions run inside the database server.
That means that all
the data and passwords move between <filename>pgcrypto</filename> and client
- applications in clear text. Thus you must:
+ applications in cleartext. Thus you must:
</para>
<orderedlist>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 01577d8d69b..cab065405b2 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -815,8 +815,8 @@ OPTIONS (ADD password_required 'false');
A user mapping setting overrides the foreign server setting.
With SCRAM pass-through authentication,
<filename>postgres_fdw</filename> uses SCRAM-hashed secrets instead of
- plain-text user passwords to connect to the remote server. This
- avoids storing plain-text user passwords in PostgreSQL system
+ cleartext user passwords to connect to the remote server. This
+ avoids storing cleartext user passwords in PostgreSQL system
catalogs.
</para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 541673eb282..50ce1cbdb32 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -471,7 +471,7 @@
<listitem>
<para>
The frontend must now send a PasswordMessage containing the
- password in clear-text form. If
+ password in cleartext form. If
this is the correct password, the server responds with an
AuthenticationOk, otherwise it responds with an ErrorResponse.
</para>
@@ -2087,7 +2087,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<note>
<para>
The bearer token is sent across the connection, as part of the client
- initial response, and grants access to the database like a clear-text
+ initial response, and grants access to the database like a cleartext
password. On an unencrypted connection it can be captured by network
sniffing. For this reason <literal>OAUTHBEARER</literal> should only be
used over SSL connections.
@@ -3923,7 +3923,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32(3)</term>
<listitem>
<para>
- Specifies that a clear-text password is required.
+ Specifies that a cleartext password is required.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 774be23b4f9..75e76f676c1 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -56,7 +56,7 @@ PostgreSQL documentation
<para>
Dumps can be output in script or archive file formats. Script
- dumps are plain-text files containing the SQL commands required
+ dumps are plain text files containing the SQL commands required
to reconstruct the database to the state it was in at the time it was
saved. To restore from such a script, feed it to <xref
linkend="app-psql"/>. Script files
@@ -101,7 +101,8 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Dumps in formats other than plain
+ text can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
@@ -315,7 +316,7 @@ PostgreSQL documentation
<term><literal>plain</literal></term>
<listitem>
<para>
- Output a plain-text <acronym>SQL</acronym> script file (the default).
+ Output a plain text <acronym>SQL</acronym> script file (the default).
</para>
</listitem>
</varlistentry>
@@ -1236,7 +1237,7 @@ PostgreSQL documentation
<para>
Use the provided string as the <application>psql</application>
<command>\restrict</command> key in the dump output. This can only be
- specified for plain-text dumps, i.e., when <option>--format</option> is
+ specified for plain text dumps, i.e., when <option>--format</option> is
set to <literal>plain</literal> or the <option>--format</option> option
is omitted. If no restrict key is specified,
<application>pg_dump</application> will generate a random one as
@@ -1740,7 +1741,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para>
It is generally recommended to use the <option>-X</option>
(<option>--no-psqlrc</option>) option when restoring a database from a
- plain-text <application>pg_dump</application> script to ensure a clean
+ plain text <application>pg_dump</application> script to ensure a clean
restore process and prevent potential conflicts with
non-default <application>psql</application> configurations.
</para>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 98d7456e83b..bff18277c2b 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -39,8 +39,8 @@ PostgreSQL documentation
<para>
<application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive
- created by <xref linkend="app-pgdump"/> in one of the non-plain-text
- formats. It will issue the commands necessary to reconstruct the
+ created by <xref linkend="app-pgdump"/> in a format other than plain text.
+ It will issue the commands necessary to reconstruct the
database to the state it was in at the time it was saved. The
archive files also allow <application>pg_restore</application> to
be selective about what is restored, or even to reorder the items
@@ -74,7 +74,8 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Dumps in formats other than plain
+ text can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 4058caf061b..b0f86e931ab 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3587,7 +3587,7 @@ SELECT $1 \parse stmt1
restricted mode. The key may contain only alphanumeric characters.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
@@ -3856,7 +3856,7 @@ SELECT 1 \bind \sendpipeline
<command>\restrict</command> when restricted mode was entered.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
--
2.50.1 (Apple Git-155)
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-13 08:44 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Karen Jex <karenhjex@gmail.com>
0 siblings, 1 reply; 21+ messages in thread
From: Laurenz Albe @ 2026-11-13 08:44 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
On Thu, 2026-11-12 at 17:37 +0100, Karen Jex wrote:
> >
> > I've created a V2 patch (attached) including the glossary terms, and
> > with a verbose commit message as suggested by Laurenz.
>
> Apologies, I managed to introduce a couple of typos into my commit
> message. V3 patch attached with a correction.
The patch looks good to me.
One sentence in the commit message struck me as weird:
> Use cleartext instead of plaintext because; it is consistent [...]
I guess that you intend the semicolon as starting an enumeration,
but this is a usage I have never seen before.
However, the committer will adapt the commit message anyway, so
(from my point of view) there is no need for another version.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-13 09:14 Karen Jex <karenhjex@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-13 09:14 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
Le ven. 13 nov. 2026 à 09:44, Laurenz Albe <laurenz.albe@cybertec.at> a écrit :
>
> On Thu, 2026-11-12 at 17:37 +0100, Karen Jex wrote:
> > >
> > > I've created a V2 patch (attached) including the glossary terms, and
> > > with a verbose commit message as suggested by Laurenz.
> >
> > Apologies, I managed to introduce a couple of typos into my commit
> > message. V3 patch attached with a correction.
>
> The patch looks good to me.
Thank you for the review.
>
> One sentence in the commit message struck me as weird:
>
> > Use cleartext instead of plaintext because; it is consistent [...]
>
> I guess that you intend the semicolon as starting an enumeration,
> but this is a usage I have never seen before.
> However, the committer will adapt the commit message anyway, so
> (from my point of view) there is no need for another version.
>
Good catch - the semicolon is an error. As suggested, I won't create a
new version just to change that.
Commitfest entry: https://commitfest.postgresql.org/patch/7630/
Best regards
--
Karen
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-16 09:22 Daniel Gustafsson <daniel@yesql.se>
parent: Karen Jex <karenhjex@gmail.com>
0 siblings, 1 reply; 21+ messages in thread
From: Daniel Gustafsson @ 2026-11-16 09:22 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
> On 13 Nov 2026, at 10:14, Karen Jex <karenhjex@gmail.com> wrote:
> Commitfest entry: https://commitfest.postgresql.org/patch/7630/
Thanks for the new version, I think this is pretty much done, just a few small
comments from reviewing it again:
user passwords to connect to the remote server. This avoids storing
- plain-text user passwords in PostgreSQL system catalogs.
+ cleartext user passwords in PostgreSQL system catalogs.
..and:
- plain-text user passwords to connect to the remote server. This
- avoids storing plain-text user passwords in PostgreSQL system
+ cleartext user passwords to connect to the remote server. This
+ avoids storing cleartext user passwords in PostgreSQL system
I think there is potential for additional cleanup here since it is the storage
system we are referring to and not an inherent quality of a specific password.
Something like the below (though I don't particularly like the double "in", but
I fail at english today) would be an improvement I think.
"This avoids storing user passwords in cleartext in PostgreSQL system
catalogs."
+ <glossentry>
+ <glossterm>Cleartext</glossterm>
+ <glossdef>
+ <para>
+ Unencrypted data; data that exists in an unprotected, readable format
+ during storage or transmission. Sometimes used as a synonym for
+ plaintext; the input to an encryption algorithm.
+ </para>
+ </glossdef>
+ </glossentry>
All data is readable, shouldn't this be specified as "human-readable" to make
it clear?
+ <glossentry>
+ <glossterm>Plain text</glossterm>
+ <glossdef>
+ <para>
+ Unformatted, human-readable text that consists of a sequence of printable
+ characters in a character encoding such as UTF-8.
+ </para>
+ </glossdef>
+ </glossentry>
The UTF-8 part seems distracting and potentially confusing, I think ending the
sentence on "printable characters." would be better.
Attachec v4 have the above changes plus a needed rebase since the pg_dump hunk
didn't apply anymore.
--
Daniel Gustafsson
Attachments:
v4-0001-doc-Standardise-cleartext-and-plain-text-terms.patch (application/octet-stream, 22.2K) download
From 221fdeec0a30f119ef8889b6fca3b1f0393c451e Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Mon, 16 Nov 2026 09:57:35 +0100
Subject: [PATCH v4] doc: Standardise cleartext and plain text terms
Replace variations of "plain text", plaintext, plain-text, "clear text",
cleartext and clear-text with either "plain text" or cleartext depending
on context.
Use cleartext to refer to unencrypted data in storage or transmission.
Use cleartext instead of plaintext because it is consistent with the
AuthenticationCleartextPassword server message, it is the term most used
throughout the Postgres docs, and it is different enough from "plain text"
not to cause confusion.
Treat cleartext as a synonym for plaintext. Although not entirely accurate
from a cryptography point of view, where plaintext is defined as the input
to a data encryption algorithm or the output of a decryption process, the
terms are used synonymously in many places, and are likely to be understood
as synonyms by the majority of Postgres users.
Use "plain text" to refer to unformatted, human-readable text. This was
selected instead of the hyphenated plain-text because "plain text" is the
standard form across the majority of technical documentation. This is the
case even when it is used as an adjective, for example: "a plain text file".
Rewrite sentences that contain the construct "non-plain-text" in order to
remain consistent and avoid ambiguity.
Add glossary entries to define the terms used.
Author: Karen Jex <karenhjex@gmail.com>
Reviewed-by: Laurenz Albe <laurenz.albe@cybertec.at>
Reviewed-by: Xavier Fischer <xavier_fischer@hotmail.fr>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Discussion: https://postgr.es/m/D7B95A7B-88B8-43E6-9DFB-2261B0849337@yesql.se
---
doc/src/sgml/catalogs.sgml | 2 +-
doc/src/sgml/client-auth.sgml | 16 ++++++++--------
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/dblink.sgml | 4 ++--
doc/src/sgml/docguide.sgml | 2 +-
doc/src/sgml/func/func-trigger.sgml | 4 ++--
doc/src/sgml/glossary.sgml | 21 +++++++++++++++++++++
doc/src/sgml/libpq.sgml | 4 ++--
doc/src/sgml/maintenance.sgml | 2 +-
doc/src/sgml/passwordcheck.sgml | 2 +-
doc/src/sgml/pgcrypto.sgml | 8 ++++----
doc/src/sgml/postgres-fdw.sgml | 4 ++--
doc/src/sgml/protocol.sgml | 6 +++---
doc/src/sgml/ref/pg_dump.sgml | 9 +++++----
doc/src/sgml/ref/pg_restore.sgml | 7 ++++---
doc/src/sgml/ref/psql-ref.sgml | 4 ++--
16 files changed, 60 insertions(+), 37 deletions(-)
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 07ba05dccd9..742388d355b 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8049,7 +8049,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
<para>
Access to the column <structfield>subconninfo</structfield> is revoked from
- normal users, because it could contain plain-text passwords.
+ normal users, because it could contain cleartext passwords.
</para>
<table>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 873ddd8f068..b7211b3cf71 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -549,7 +549,7 @@ include_dir <replaceable>directory</replaceable>
<para>
Require the client to supply an unencrypted password for
authentication.
- Since the password is sent in clear text over the
+ Since the password is sent in cleartext over the
network, this should not be used on untrusted networks.
See <xref linkend="auth-password"/> for details.
</para>
@@ -652,7 +652,7 @@ include_dir <replaceable>directory</replaceable>
<listitem>
<para>
Authorize and optionally authenticate using a third-party OAuth 2.0
- identity provider. Since the bearer token is sent in clear text over
+ identity provider. Since the bearer token is sent in cleartext over
the network, this should not be used on untrusted networks. See
<xref linkend="auth-oauth"/> for details.
</para>
@@ -1258,7 +1258,7 @@ omicron bryanh guest1
<para>
The method <literal>md5</literal> uses a custom less secure challenge-response
mechanism. It prevents password sniffing and avoids storing passwords
- on the server in plain text but provides no protection if an attacker
+ on the server in cleartext but provides no protection if an attacker
manages to steal the password hash from the server. Also, the MD5 hash
algorithm is nowadays no longer considered secure against determined
attacks.
@@ -1286,7 +1286,7 @@ omicron bryanh guest1
<term><literal>password</literal></term>
<listitem>
<para>
- The method <literal>password</literal> sends the password in clear-text and is
+ The method <literal>password</literal> sends the password in cleartext and is
therefore vulnerable to password <quote>sniffing</quote> attacks. It should
always be avoided if possible. If the connection is protected by SSL
encryption then <literal>password</literal> can be used safely, though.
@@ -1320,15 +1320,15 @@ omicron bryanh guest1
the <literal>scram-sha-256</literal> setting, then it can be used for the
authentication methods <literal>scram-sha-256</literal>
and <literal>password</literal> (but password transmission will be in
- plain text in the latter case). The authentication method
+ cleartext in the latter case). The authentication method
specification <literal>md5</literal> will automatically switch to using
the <literal>scram-sha-256</literal> method in this case, as explained
above, so it will also work. If a password was encrypted using
the <literal>md5</literal> setting, then it can be used only for
the <literal>md5</literal> and <literal>password</literal> authentication
- method specifications (again, with the password transmitted in plain text
+ method specifications (again, with the password transmitted in cleartext
in the latter case). (Previous PostgreSQL releases supported storing the
- password on the server in plain text. This is no longer possible.) To
+ password on the server in cleartext. This is no longer possible.) To
check the currently stored password hashes, see the system
catalog <literal>pg_authid</literal>.
</para>
@@ -2344,7 +2344,7 @@ host ... ldap ldapbasedn="dc=example,dc=net"
which are a type of access token used with OAuth 2.0 where the token is an
opaque string. The format of the access token is implementation specific
and is chosen by each authorization server. The bearer token is sent
- in clear-text, and is vulnerable to network sniffing. For this reason
+ in cleartext, and is vulnerable to network sniffing. For this reason
OAuth should only be used over SSL connections.
</para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 7018ca1e3ea..f987aba0ac3 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -8646,7 +8646,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a '
</para>
<para>
Logged statements might reveal sensitive data and even contain
- plaintext passwords.
+ cleartext passwords.
</para>
</note>
</listitem>
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index fc496b74288..4ea2b122840 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -157,9 +157,9 @@ dblink_connect(text connname, text connstr) returns text
authentication to connect to the remote database. It can be specified
for a foreign server or a user mapping. A user mapping setting overrides
the foreign server setting. With SCRAM pass-through authentication,
- <filename>dblink</filename> uses SCRAM-hashed secrets instead of plain-text
+ <filename>dblink</filename> uses SCRAM-hashed secrets instead of cleartext
user passwords to connect to the remote server. This avoids storing
- plain-text user passwords in PostgreSQL system catalogs.
+ storing user passwords in cleartext in PostgreSQL system catalogs.
See the documentation of the equivalent <link
linkend="postgres-fdw-option-use-scram-passthrough"><literal>use_scram_passthrough</literal></link>
option of postgres_fdw for further details and restrictions.
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index a91b386817c..866f4a6ce51 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -30,7 +30,7 @@
</listitem>
</itemizedlist>
- Additionally, a number of plain-text <filename>README</filename> files can
+ Additionally, a number of plain text <filename>README</filename> files can
be found throughout the <productname>PostgreSQL</productname> source tree,
documenting various implementation issues.
</para>
diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml
index 94b40adbdb8..a212fcadfc5 100644
--- a/doc/src/sgml/func/func-trigger.sgml
+++ b/doc/src/sgml/func/func-trigger.sgml
@@ -60,7 +60,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is specified by name as a trigger argument. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
@@ -79,7 +79,7 @@
</para>
<para>
Automatically updates a <type>tsvector</type> column from associated
- plain-text document column(s). The text search configuration to use
+ plain text document column(s). The text search configuration to use
is taken from a <type>regconfig</type> column of the table. See
<xref linkend="textsearch-update-triggers"/> for details.
</para>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index d28a3729188..c44eaec8d82 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -434,6 +434,17 @@
<glosssee otherterm="glossary-relation" />
</glossentry>
+ <glossentry>
+ <glossterm>Cleartext</glossterm>
+ <glossdef>
+ <para>
+ Unencrypted data; data that exists in an unprotected, human-readable
+ format during storage or transmission. Sometimes used as a synonym for
+ plaintext; the input to an encryption algorithm.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-client">
<glossterm>Client (process)</glossterm>
<glossdef>
@@ -1362,6 +1373,16 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>Plain text</glossterm>
+ <glossdef>
+ <para>
+ Unformatted, human-readable text that consists of a sequence of printable
+ characters.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id="glossary-postmaster">
<glossterm>Postmaster (process)</glossterm>
<glossdef>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index b213a266cb2..3caaea91137 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1330,7 +1330,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<term><literal>password</literal></term>
<listitem>
<para>
- The server must request plaintext password authentication.
+ The server must request cleartext password authentication.
</para>
</listitem>
</varlistentry>
@@ -1851,7 +1851,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
start SSL handshake directly after establishing the TCP/IP
connection. This is only allowed with
<literal>sslmode=require</literal> or higher, because the weaker
- settings could lead to unintended fallback to plaintext
+ settings could lead to unintended fallback to cleartext
authentication when the server does not support direct SSL
handshake.
</para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index e3f5cedd589..e3cc7ad01db 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1291,7 +1291,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<para>
The server log can contain sensitive information and needs to be protected,
no matter how or where it is stored, or the destination to which it is routed.
- For example, some DDL statements might contain plaintext passwords or other
+ For example, some DDL statements might contain cleartext passwords or other
authentication details. Logged statements at the <literal>ERROR</literal>
level might show the SQL source code for applications
and might also contain some parts of data rows. Recording data, events and
diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml
index 7ea32410463..d8b061738e4 100644
--- a/doc/src/sgml/passwordcheck.sgml
+++ b/doc/src/sgml/passwordcheck.sgml
@@ -55,7 +55,7 @@
<para>
Alternatively, you could modify <filename>passwordcheck</filename>
to reject pre-encrypted passwords, but forcing users to set their
- passwords in clear text carries its own security risks.
+ passwords in cleartext carries its own security risks.
</para>
</caution>
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 00a35f3715c..b1ef6075e40 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -980,19 +980,19 @@ Applies to: pgp_sym_encrypt, pgp_pub_encrypt
created when the <literal>cipher-algo</literal> was unavailable under the
OpenSSL configuration in use. Such faulty messages do not require the
correct decryption key when <literal>ignore-cipher-failure</literal> is
- enabled, so there is no guarantee that the decrypted plaintext actually
+ enabled, so there is no guarantee that the decrypted cleartext actually
originated from a holder of the key.
</para>
<para>
Contrast the case of a message which was correctly encrypted, but the cipher
that produced it is unavailable under the current <productname>OpenSSL</productname>
- configuration. Recovering such plaintext via <filename>pgcrypto</filename>
+ configuration. Recovering such cleartext via <filename>pgcrypto</filename>
requires making the actual cipher available to OpenSSL by, for example,
enabling the appropriate provider. <literal>ignore-cipher-failure</literal>
is not necessary or helpful for that scenario. If <quote>decryption</quote>
of a correctly encrypted message with this option happens to pass PGP
integrity checks, that result is coincidental and does not make the
- recovered plaintext trustworthy.
+ recovered cleartext trustworthy.
</para>
<literallayout>
Values: 0, 1
@@ -1338,7 +1338,7 @@ fips_mode() returns boolean
All <filename>pgcrypto</filename> functions run inside the database server.
That means that all
the data and passwords move between <filename>pgcrypto</filename> and client
- applications in clear text. Thus you must:
+ applications in cleartext. Thus you must:
</para>
<orderedlist>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 01577d8d69b..4b799d3369c 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -815,8 +815,8 @@ OPTIONS (ADD password_required 'false');
A user mapping setting overrides the foreign server setting.
With SCRAM pass-through authentication,
<filename>postgres_fdw</filename> uses SCRAM-hashed secrets instead of
- plain-text user passwords to connect to the remote server. This
- avoids storing plain-text user passwords in PostgreSQL system
+ cleartext user passwords to connect to the remote server. This
+ avoids storing user passwords in cleartext in PostgreSQL system
catalogs.
</para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 541673eb282..50ce1cbdb32 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -471,7 +471,7 @@
<listitem>
<para>
The frontend must now send a PasswordMessage containing the
- password in clear-text form. If
+ password in cleartext form. If
this is the correct password, the server responds with an
AuthenticationOk, otherwise it responds with an ErrorResponse.
</para>
@@ -2087,7 +2087,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<note>
<para>
The bearer token is sent across the connection, as part of the client
- initial response, and grants access to the database like a clear-text
+ initial response, and grants access to the database like a cleartext
password. On an unencrypted connection it can be captured by network
sniffing. For this reason <literal>OAUTHBEARER</literal> should only be
used over SSL connections.
@@ -3923,7 +3923,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term>Int32(3)</term>
<listitem>
<para>
- Specifies that a clear-text password is required.
+ Specifies that a cleartext password is required.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 3c97facb657..951de54e77f 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -56,7 +56,7 @@ PostgreSQL documentation
<para>
Dumps can be output in script or archive file formats. Script
- dumps are plain-text files containing the SQL commands required
+ dumps are plain text files containing the SQL commands required
to reconstruct the database to the state it was in at the time it was
saved. To restore from such a script, feed it to <xref
linkend="app-psql"/>. Script files
@@ -101,7 +101,8 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Dumps in formats other than plain
+ text can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
@@ -315,7 +316,7 @@ PostgreSQL documentation
<term><literal>plain</literal></term>
<listitem>
<para>
- Output a plain-text <acronym>SQL</acronym> script file (the default).
+ Output a plain text <acronym>SQL</acronym> script file (the default).
</para>
</listitem>
</varlistentry>
@@ -1738,7 +1739,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para>
It is generally recommended to use the <option>-X</option>
(<option>--no-psqlrc</option>) option when restoring a database from a
- plain-text <application>pg_dump</application> script to ensure a clean
+ plain text <application>pg_dump</application> script to ensure a clean
restore process and prevent potential conflicts with
non-default <application>psql</application> configurations.
</para>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 98d7456e83b..bff18277c2b 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -39,8 +39,8 @@ PostgreSQL documentation
<para>
<application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive
- created by <xref linkend="app-pgdump"/> in one of the non-plain-text
- formats. It will issue the commands necessary to reconstruct the
+ created by <xref linkend="app-pgdump"/> in a format other than plain text.
+ It will issue the commands necessary to reconstruct the
database to the state it was in at the time it was saved. The
archive files also allow <application>pg_restore</application> to
be selective about what is restored, or even to reorder the items
@@ -74,7 +74,8 @@ PostgreSQL documentation
Restoring a dump causes the destination to execute arbitrary code of the
source superusers' choice. Partial dumps and partial restores do not limit
that. If the source superusers are not trusted, the dumped SQL statements
- must be inspected before restoring. Non-plain-text dumps can be inspected
+ must be inspected before restoring. Dumps in formats other than plain
+ text can be inspected
by using <application>pg_restore</application>'s <option>--file</option>
option. Note that the client running the dump and restore need not trust
the source or destination superusers.
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 4058caf061b..b0f86e931ab 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -3587,7 +3587,7 @@ SELECT $1 \parse stmt1
restricted mode. The key may contain only alphanumeric characters.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
@@ -3856,7 +3856,7 @@ SELECT 1 \bind \sendpipeline
<command>\restrict</command> when restricted mode was entered.
</para>
<para>
- This command is primarily intended for use in plain-text dumps
+ This command is primarily intended for use in plain text dumps
generated by <application>pg_dump</application>,
<application>pg_dumpall</application>, and
<application>pg_restore</application>, but it may be useful elsewhere.
--
2.39.3 (Apple Git-146)
=
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-17 08:49 Karen Jex <karenhjex@gmail.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 21+ messages in thread
From: Karen Jex @ 2026-11-17 08:49 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Laurenz Albe <laurenz.albe@cybertec.at>; Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
Le lun. 16 nov. 2026 à 10:22, Daniel Gustafsson <daniel@yesql.se> a écrit :
>
> > On 13 Nov 2026, at 10:14, Karen Jex <karenhjex@gmail.com> wrote:
>
> > Commitfest entry: https://commitfest.postgresql.org/patch/7630/
>
> Thanks for the new version, I think this is pretty much done, just a few small
> comments from reviewing it again:
>
> user passwords to connect to the remote server. This avoids storing
> - plain-text user passwords in PostgreSQL system catalogs.
> + cleartext user passwords in PostgreSQL system catalogs.
>
> ..and:
>
> - plain-text user passwords to connect to the remote server. This
> - avoids storing plain-text user passwords in PostgreSQL system
> + cleartext user passwords to connect to the remote server. This
> + avoids storing cleartext user passwords in PostgreSQL system
>
> I think there is potential for additional cleanup here since it is the storage
> system we are referring to and not an inherent quality of a specific password.
> Something like the below (though I don't particularly like the double "in", but
> I fail at english today) would be an improvement I think.
>
> "This avoids storing user passwords in cleartext in PostgreSQL system
> catalogs."
+1 This makes it clearer. I don't mind the double "in" - I can't think
of a better alternative.
>
> Attachec v4 have the above changes plus a needed rebase since the pg_dump hunk
> didn't apply anymore.
Thank you for doing this. I agree with all of your changes.
--
Karen
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-17 20:34 Peter Smith <smithpb2250@gmail.com>
parent: Karen Jex <karenhjex@gmail.com>
0 siblings, 1 reply; 21+ messages in thread
From: Peter Smith @ 2026-11-17 20:34 UTC (permalink / raw)
To: Karen Jex <karenhjex@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Laurenz Albe <laurenz.albe@cybertec.at>; Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
On Tue, Nov 17, 2026 at 7:52 PM Karen Jex <karenhjex@gmail.com> wrote:
>
> Le lun. 16 nov. 2026 à 10:22, Daniel Gustafsson <daniel@yesql.se> a écrit :
> >
> > > On 13 Nov 2026, at 10:14, Karen Jex <karenhjex@gmail.com> wrote:
> >
> > > Commitfest entry: https://commitfest.postgresql.org/patch/7630/
> >
> > Thanks for the new version, I think this is pretty much done, just a few small
> > comments from reviewing it again:
> >
> > user passwords to connect to the remote server. This avoids storing
> > - plain-text user passwords in PostgreSQL system catalogs.
> > + cleartext user passwords in PostgreSQL system catalogs.
> >
> > ..and:
> >
> > - plain-text user passwords to connect to the remote server. This
> > - avoids storing plain-text user passwords in PostgreSQL system
> > + cleartext user passwords to connect to the remote server. This
> > + avoids storing cleartext user passwords in PostgreSQL system
> >
> > I think there is potential for additional cleanup here since it is the storage
> > system we are referring to and not an inherent quality of a specific password.
> > Something like the below (though I don't particularly like the double "in", but
> > I fail at english today) would be an improvement I think.
> >
> > "This avoids storing user passwords in cleartext in PostgreSQL system
> > catalogs."
>
> +1 This makes it clearer. I don't mind the double "in" - I can't think
> of a better alternative.
>
How about.
"This avoids storing user passwords as cleartext in PostgreSQL system catalogs."
======
Kind Regards,
Peter Smith.
Fujitsu Australia
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc..
@ 2026-11-17 20:57 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Smith <smithpb2250@gmail.com>
0 siblings, 0 replies; 21+ messages in thread
From: Daniel Gustafsson @ 2026-11-17 20:57 UTC (permalink / raw)
To: Peter Smith <smithpb2250@gmail.com>; +Cc: Karen Jex <karenhjex@gmail.com>; Laurenz Albe <laurenz.albe@cybertec.at>; Peter Eisentraut <peter@eisentraut.org>; David E. Wheeler <david@justatheory.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>; xavier_fischer@hotmail.fr
> On 17 Nov 2026, at 21:34, Peter Smith <smithpb2250@gmail.com> wrote:
> On Tue, Nov 17, 2026 at 7:52 PM Karen Jex <karenhjex@gmail.com> wrote:
>>
>> Le lun. 16 nov. 2026 à 10:22, Daniel Gustafsson <daniel@yesql.se> a écrit :
>>> "This avoids storing user passwords in cleartext in PostgreSQL system
>>> catalogs."
>>
>> +1 This makes it clearer. I don't mind the double "in" - I can't think
>> of a better alternative.
>
> How about.
>
> "This avoids storing user passwords as cleartext in PostgreSQL system catalogs."
Thats a good suggestion, I'll go with that.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 21+ messages in thread
end of thread, other threads:[~2026-11-17 20:57 UTC | newest]
Thread overview: 21+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-11-06 13:41 Good beginner doc-hacking task: clear-text vs. cleartext vs. clear text vs. plaintext etc.. Daniel Gustafsson <daniel@yesql.se>
2026-11-06 14:44 ` Karen Jex <karenjex@hotmail.com>
2026-11-06 14:49 ` David E. Wheeler <david@justatheory.com>
2026-11-06 19:16 ` Karen Jex <karenhjex@gmail.com>
2026-11-10 16:30 ` Karen Jex <karenhjex@gmail.com>
2026-11-10 19:29 ` Xavier Fischer <xavier_fischer@hotmail.fr>
2026-11-10 20:56 ` Xavier Fischer <xavier_fischer@hotmail.fr>
2026-11-11 07:22 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-11-11 14:35 ` Karen Jex <karenhjex@gmail.com>
2026-11-11 10:58 ` Peter Eisentraut <peter@eisentraut.org>
2026-11-11 11:43 ` Daniel Gustafsson <daniel@yesql.se>
2026-11-11 15:16 ` Karen Jex <karenhjex@gmail.com>
2026-11-12 09:11 ` Daniel Gustafsson <daniel@yesql.se>
2026-11-12 16:24 ` Karen Jex <karenhjex@gmail.com>
2026-11-12 16:37 ` Karen Jex <karenhjex@gmail.com>
2026-11-13 08:44 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-11-13 09:14 ` Karen Jex <karenhjex@gmail.com>
2026-11-16 09:22 ` Daniel Gustafsson <daniel@yesql.se>
2026-11-17 08:49 ` Karen Jex <karenhjex@gmail.com>
2026-11-17 20:34 ` Peter Smith <smithpb2250@gmail.com>
2026-11-17 20:57 ` Daniel Gustafsson <daniel@yesql.se>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox