(doc patch) psql version compatibility
Hi,
I didn't understand the current wording of the NOTES section in
psql(1) on which major versions psql is compatible with, so here's a
patch to make that more explicit.
Christoph
Attachments:
0001-psql-ref.sgml-Be-more-specific-about-major-versions-.patchtext/x-diff; charset=us-asciiDownload
From 89f947c215c679004e1f3fbf88751fe527e16f91 Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Tue, 6 Sep 2022 13:21:48 +0200
Subject: [PATCH] psql-ref.sgml: Be more specific about major versions support
The old wording only mentioned \d, but in practise even `psql -l` would
fail for pre-9.2 servers, so be more clear about the version range.
---
doc/src/sgml/ref/psql-ref.sgml | 13 ++++++-------
1 file changed, 6 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 186f8c506a..09e3da7c24 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -4946,20 +4946,19 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
<itemizedlist>
<listitem>
- <para><application>psql</application> works best with servers of the same
- or an older major version. Backslash commands are particularly likely
+ <para><application>psql</application> works with servers of the same
+ or an older major version, back to 9.2. Backslash commands are particularly likely
to fail if the server is of a newer version than <application>psql</application>
- itself. However, backslash commands of the <literal>\d</literal> family should
- work with servers of versions back to 9.2, though not necessarily with
- servers newer than <application>psql</application> itself. The general
+ itself, or older than 9.2. The general
functionality of running SQL commands and displaying query results
- should also work with servers of a newer major version, but this cannot
+ should also work with servers of a other major versions, but this cannot
be guaranteed in all cases.
</para>
<para>
If you want to use <application>psql</application> to connect to several
servers of different major versions, it is recommended that you use the
- newest version of <application>psql</application>. Alternatively, you
+ newest version of <application>psql</application>. (To connect to pre-9.2 servers,
+ use <application>psql</application> 14 or earlier.) Alternatively, you
can keep around a copy of <application>psql</application> from each
major version and be sure to use the version that matches the
respective server. But in practice, this additional complication should
--
2.35.1
Christoph Berg <myon@debian.org> writes:
I didn't understand the current wording of the NOTES section in
psql(1) on which major versions psql is compatible with, so here's a
patch to make that more explicit.
This seems both very repetitive and incorrect in detail.
Some operations will work fine with older servers, some won't.
I don't think that we want to undertake documenting exactly
which commands work how far back, so my inclination is to
add a nonspecific disclaimer along the lines of
Some commands may not work with very old servers (before 9.2).
regards, tom lane
Re: Tom Lane
Christoph Berg <myon@debian.org> writes:
I didn't understand the current wording of the NOTES section in
psql(1) on which major versions psql is compatible with, so here's a
patch to make that more explicit.This seems both very repetitive and incorrect in detail.
Meh, I tried to preserve as much of the original text as reasonable,
but we can strip it down further.
Some operations will work fine with older servers, some won't.
I don't think that we want to undertake documenting exactly
which commands work how far back, so my inclination is to
add a nonspecific disclaimer along the lines ofSome commands may not work with very old servers (before 9.2).
I'd like it do say "it works with 9.2" when that's what the code is
implementing.
How about this?
<para><application>psql</application> works with servers of the same
or an older major version, back to 9.2. The general
functionality of running SQL commands and displaying query results
should also work with servers of other major versions, but
backslash commands are particularly likely to fail.
</para>
<para>
If you want to use <application>psql</application> to connect to several
servers of different major versions, it is recommended that you use the
newest version of <application>psql</application>. (To connect to pre-9.2 servers,
use <application>psql</application> 14 or earlier.)
</para>
Christoph
Attachments:
0001-psql-ref.sgml-Be-more-specific-about-major-versions-.patchtext/x-diff; charset=us-asciiDownload
From 2d83aaec5f398de041467b4fe78731401847d6a5 Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Tue, 6 Sep 2022 13:21:48 +0200
Subject: [PATCH] psql-ref.sgml: Be more specific about major versions support
Explicitly say which version range we are supporting.
---
doc/src/sgml/ref/psql-ref.sgml | 19 ++++++-------------
1 file changed, 6 insertions(+), 13 deletions(-)
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 186f8c506a..9e972f0c48 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -4946,24 +4946,17 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
<itemizedlist>
<listitem>
- <para><application>psql</application> works best with servers of the same
- or an older major version. Backslash commands are particularly likely
- to fail if the server is of a newer version than <application>psql</application>
- itself. However, backslash commands of the <literal>\d</literal> family should
- work with servers of versions back to 9.2, though not necessarily with
- servers newer than <application>psql</application> itself. The general
+ <para><application>psql</application> works with servers of the same
+ or an older major version, back to 9.2. The general
functionality of running SQL commands and displaying query results
- should also work with servers of a newer major version, but this cannot
- be guaranteed in all cases.
+ should also work with servers of other major versions, but
+ backslash commands are particularly likely to fail.
</para>
<para>
If you want to use <application>psql</application> to connect to several
servers of different major versions, it is recommended that you use the
- newest version of <application>psql</application>. Alternatively, you
- can keep around a copy of <application>psql</application> from each
- major version and be sure to use the version that matches the
- respective server. But in practice, this additional complication should
- not be necessary.
+ newest version of <application>psql</application>. (To connect to pre-9.2 servers,
+ use <application>psql</application> 14 or earlier.)
</para>
</listitem>
--
2.35.1