Subject: PostgreSQL 17 release announcement draft

From: "Jonathan S. Katz" <[email-masked]>
Date: Wed, 4 Sep 2024 17:05:00 -0400

Hi,

Attached is the draft of the PostgreSQL 17 release announcement. This is 
a draft of the text that will go into the press kit, with the key 
portions to review starting from the top of the document, up until the 
"About PostgreSQL" section.

Please provide feedback on content accuracy, notable omissions or items 
that should be excluded, or if an explanation is unclear and needs 
better phrasing. On the last point, I'm looking to ensure the wording is 
clear and is easy to translate into different languages.

Based on feedback, I'll be posting a revision once a day (if there's 
feedback) until the review cut-off. We'll have to freeze the 
announcement by Mon, Sep 9 @ 12:00 UTC so we can begin the translation 
process.

Thank you for your help with the release process!

Jonathan

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 5 Sep 2024 11:22:33 +0200

> "About PostgreSQL" section.

I noticed that we don't yet have a list of major features in the PG17 
release notes.  We should probably put that in soon, so that what we 
list there and what is in the announcement are consistent.

On the actual list, there will be lots of opinions to be had, but I'll 
just offer one:  I don't think the MERGE RETURNING clause deserves twice 
as much space as incremental backup.

---

From: Alicja Kucharczyk <[email-masked]>
Date: Thu, 5 Sep 2024 11:42:21 +0200

śr., 4 wrz 2024 o 23:05 Jonathan S. Katz <[email-masked]> napisał(a):

> On the last point, I'm looking to ensure the wording is

As a non-native speaker, I found the wording and syntax easy to understand,
and the acronyms are well-explained. In my opinion, this should make
translation into different languages relatively straightforward. The only
word that might pose a challenge is "debuts," as it's not commonly used,
but most online translators do a good job of conveying its meaning.
Overall, I believe the text is clear and effective.

---

From: Robert Haas <[email-masked]>
Date: Thu, 5 Sep 2024 12:04:05 -0400

> list there and what is in the announcement are consistent.

+1.

> as much space as incremental backup.

I agree with that, although obviously I'm biased.

I also feel like this whole thing could just be shorter. If it were
half as long and mentioned fewer things and those more briefly, would
we be worse off? I think we might be better off, because it just feels
wordy to me right now. For example:

A foundational feature of PostgreSQL is
[vacuum](https://www.postgresql.org/docs/17/routine-vacuuming.html),
which is used to reclaim storage from data that was marked as removed.
Reducing resources required for vacuuming directly helps other areas
of PostgreSQL, particularly on very busy systems. PostgreSQL 17
introduces a new internal memory structure for vacuum that's shown up
to a 20x reduction in memory and improvements in overall vacuuming
speed. This release also removes the  `1GB` limit on the memory it can
use (controlled by
[`maintenance_work_mem`](https://www.postgresql.org/docs/17/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM)),
letting users apply more resources to vacuuming, which is beneficial
for systems with lots of changes.

It seems to me that the first two sentences could just be completely
nuked, and everything from "letting users" to the end could also be
nuked. At least to me, all of that stuff reads as unnecessarily
filler. I'm not at all sure that removing the 1GB limit on
maintenance_work_mem is important enough that it needs to be in the
release announcement -- I agree it's a good improvement, but to have
it be one of the first things in the press release seems like an odd
choice from my perspective. Nobody's going to look back on this
release years from now and say "oh, that was the release where could
finally set maintenance_work_mem=4GB, that was so much better". If
they think about VACUUM, they'll think about the 20x memory reduction
stuff which made the ability to configure values larger than 1GB
irrelevant in the first place. So I'd probably delete the part about
lifting the 1GB cap entirely. But even if you don't do that, the
paragraph could be half as long without losing anything, from my
perspective.

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

---

From: Andrew Atkinson <[email-masked]>
Date: Thu, 5 Sep 2024 11:49:29 -0500

Hi Jonathan. Do you want change proposals here as text snippets in emails?
It seems the patch process isn't used here.

If so, here's an attempted reduction that echoes what Robert said. I also
thought explaining Vacuum wouldn't be necessary for this audience, so less
lead-in could work. Is the benefit to end users that there is less memory
and CPU needed by vacuum, thus more CPU and memory is available to their
foreground workload?

Original:
> A foundational feature of PostgreSQL is [vacuum](
https://www.postgresql.org/docs/17/routine-vacuuming.html), which is used
to reclaim storage from data that was marked as removed. Reducing resources
required for vacuuming directly helps other areas of PostgreSQL,
particularly on very busy systems. PostgreSQL 17 introduces a new internal
memory structure for vacuum that's shown up to a 20x reduction in memory
and improvements in overall vacuuming speed.

Proposed:
The PostgreSQL [vacuum](
https://www.postgresql.org/docs/17/routine-vacuuming.html) process is
critical for healthy operations, requiring server instance resources to
operate. With PostgreSQL 17, a new internal memory structure for vacuum was
used that consumes up to 20x less memory. This improves vacuum speed and
also reduces the use of shared resources, making more available for your
workload.

Something along those lines, where the benefit to the user is they could
expect more CPU/mem etc. available for their SQL operations, right?  This
could be something folks want to benchmark as well as a reason to upgrade,
at least for Vacuum-intensive workloads, high UPDATE and DELETE operations
etc.

On Thu, Sep 5, 2024 at 11:04 AM Robert Haas <[email-masked]> wrote:

> [`maintenance_work_mem`](
> https://www.postgresql.org/docs/17/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM)
> ),

---

From: Andrew Atkinson <[email-masked]>
Date: Thu, 5 Sep 2024 11:58:54 -0500

The write operations seem to be under-sold here! These seem very exciting
and would be beneficial to all Postgres databases I've worked on.

Is this a fair way to reduce the three items mentioned, as much as
possible? I'm not proposing they change, but just sort of pushing on
building down the items tied to their benefit to the end user as much as
possible. Possibly shortening them and making them punchier will help.

Faster Write throughput:
- "Fewer WAL locks shorter lock lengths" (check this, I'm making it up, but
I'm wondering if it's fewer WAL locks, or the locks are held for less
time), thus better throughput
- "Faster Sequential scans"  - is the benefit that they're faster?
- "Faster ANALYZE"  - is it that ANALYZE runs faster on 17 vs. the same
operation on 16?

The last point "Allowing extensions to be integrated further." I didn't
grab on to as much. I'm wondering if it's something like "new write
operation APIs are now available for extension creators" or something like
that?

---

From: Andrew Atkinson <[email-masked]>
Date: Thu, 5 Sep 2024 13:44:30 -0500

Additional chunk:

Proposed:
PostgreSQL 17 improves the performance of queries with `IN` clauses that
use [B-tree](
https://www.postgresql.org/docs/17/indexes-types.html#INDEXES-TYPES-BTREE)
indexes, the default index method in PostgreSQL). Support for parallel
index builds were added for [BRIN](
https://www.postgresql.org/docs/17/brin.html) indexing.

PostgreSQL 17 leverages the constraints you've defined. The query planner
removes redundant `IS NOT NULL` statements when a column has a `NOT NULL`
constraint, and skips over `IS NULL` clauses for columns with an `IS NOT
NULL` constraint.

On Thu, Sep 5, 2024 at 11:58 AM Andrew Atkinson <[email-masked]>
wrote:

> - "Fewer WAL locks shorter lock lengths" (check this, I'm making it up,
> but I'm wondering if it's fewer WAL locks, or the locks are held for less
>> Hi Jonathan. Do you want change proposals here as text snippets in
>> emails? It seems the patch process isn't used here.
>>
>> https://www.postgresql.org/docs/17/routine-vacuuming.html), which is
>> used to reclaim storage from data that was marked as removed. Reducing
>> resources required for vacuuming directly helps other areas of PostgreSQL,

---

From: Andrew Atkinson <[email-masked]>
Date: Thu, 5 Sep 2024 14:21:09 -0500

I'll send one more bigger email. I also have made these as comments in a
google doc I'm happy to add anyone to if they're interested. Let me know.

> PostgreSQL 17 extends its performance gains to query execution. Planner
statistics help PostgreSQL to determine the best way to search for data,
and PostgreSQL 17 can now use planner statistics and the sort order [common
table expressions](https://www.postgresql.org/docs/17/queries-with.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/queries-with.html&sa=D&source=docs&ust=1725564996929209&usg=AOvVaw1sY98EkQgjdM1C3TnVJWeu>)
([`WITH` queries](https://www.postgresql.org/docs/17/queries-with.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/queries-with.html&sa=D&source=docs&ust=1725564996929307&usg=AOvVaw04OERMJyQuT64QbaPrZ2xa>))
to further speed up queries.

Was that meant to be the sort order "from" CTEs? Maybe a missing "From"?

> to support more expressive JSON processing capabilities and
implementation of the SQL/JSON standard.

Was that meant to be something like "and to expand the implementation" of
or "an expanded implementation"?

> "with an emphasis of converting JSON data to a native PostgreSQL data
type"

Was that meant to be an emphasis "*on" and not "of"* ?

> For the merge section, here's a proposed reworked version:

PostgreSQL 17 provides expanded control over `MERGE` behavior, including a
new `merge_action` function that describes how a row was modified.

PostgreSQL 17 provides new capabilities and performance improvements for
bulk data loading and exporting. This includes improving exports of large
rows by up to 2x using the [`COPY`](
https://www.postgresql.org/docs/17/sql-copy.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/sql-copy.html&sa=D&source=docs&ust=1725566138606705&usg=AOvVaw02c3_7C8miH9bXrt4qopvi>)
command, and performance improvements for cases when the source and
destination encodings match. A new option `ON_ERROR` was added which can be
used to allow imports to continue even when errors happen for inserts.

> For the predefined role, something to consider would be using action
verbs. I don't know if this seems too inconsistent though. It makes it
easier to write. For example:

Use the new `pg_maintain` [predefined role](
https://www.postgresql.org/docs/17/predefined-roles.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/predefined-roles.html&sa=D&source=docs&ust=1725566387873658&usg=AOvVaw2EZeIkeRHXpUh5Kg4WDg1v>)
to grant permissions for maintenance operations.

> For the EXPLAIN enhancements:

PostgreSQL 17 [`EXPLAIN`](
https://www.postgresql.org/docs/17/sql-explain.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/sql-explain.html&sa=D&source=docs&ust=1725566534658961&usg=AOvVaw24h7LPwl2fAuT8qeYJn37n>)
now shows the time spent for I/O block reads and writes, and includes two
new options: `SERIALIZE` and `MEMORY`, useful for seeing the time spent in
data conversion for network transmission, and how much memory was used.

That's all I've got.

This is an exciting release! Nice work!

On Thu, Sep 5, 2024 at 1:44 PM Andrew Atkinson <[email-masked]>
wrote:

>>> If so, here's an attempted reduction that echoes what Robert said. I
>>> also thought explaining Vacuum wouldn't be necessary for this audience, so
>>> less lead-in could work. Is the benefit to end users that there is less
>>> memory and CPU needed by vacuum, thus more CPU and memory is available to
>>> their foreground workload?
>>>
>>> Original:

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Fri, 6 Sep 2024 13:03:29 -0400

> google doc I'm happy to add anyone to if they're interested. Let me know.

Thank you everyone for your feedback. I've attached the updated draft 
incorporating what was said. A few general comments:

* I took to heart "make the explanations shorter" and trimmed quite a 
bit. However, given the GA announcement is for a more general audience, 
there are concepts that are unfamiliar to general users that deserve 
clarification or additional context. For example, for many of our users, 
vacuum isn't typically noticed (or even considered) until something goes 
wrong, but they'll still benefit from overall changes. Similarly, the 
phrase "sequential scan" may not mean anything, but a user may know that 
creating an index will "speed up a query."

* One pattern that we measured is that when we made the GA announcement 
a "springboard" to learn about the new features (including more info), 
we did see better engagement with the release and the features 
themselves. I'd like to err on the side of discoverability, particularly 
of features that our users can directly try out.

Please see v2 attached. As per original note, please provide feedback 
before Mon, Sep 9 @ 12:00 UTC so we can begin the translation process.

Thanks,

Jonathan

---

From: Adrian Klaver <[email-masked]>
Date: Fri, 6 Sep 2024 10:28:54 -0700

> before Mon, Sep 9 @ 12:00 UTC so we can begin the translation process.

A quick read through found:

"... the 
[`pg_combinebackup`](https://www.postgresql.org/docs/17/app-pgcombinebackup.html) 

or the backup restoration process."

I'm guessing that is "... for the backup restoration process."

-- 
Adrian Klaver
[email-masked]

---

From: Andrew Atkinson <[email-masked]>
Date: Fri, 6 Sep 2024 13:02:15 -0500

This is looking crisper. Nice edits! I did one more read through and have
minor comments and suggestions.

----------------------

> "PostgreSQL 17 introduces a new internal memory structure for vacuum
was used that consumes up to 20x less memory"

Small typo, I think "that" was missed:

PostgreSQL 17 introduces a new internal memory structure for vacuum that
consumes up to 20x less memory.

----------------------

> "and PostgreSQL 17 adds to its implementation SQL/JSON standard."

is this missing "of the" ?

and PostgreSQL 17 adds to its implementation "of" the SQL/JSON standard.

----------------------

"exporting,including"

add space after "exporting", assuming this was copied correctly from the
source file into google docs (which it may not have been) :)

----------------------

This is in the realm of personal preference/suggestion. The word
"federated" is complex and I kind of understand it, but prefer simpler
terminology. Here's a suggestion:

"This release expands on functionality for managing data in partitions or
federated on remote PostgreSQL instances."

Alternative: "This release expands on functionality for managing data in
partitions or data spread out between local and remote PostgreSQL
instances."

----------------------

Suggestion: both "converts" and "creates" verbs are used in the docs
to describe pg_createsubscriber. I like the verb "convert" because I think
it speaks more to the purpose of being run on a physical replica, then
turning it into a logical replication based instance as a subscriber.

With that said, my suggested alternative is:

PostgreSQL 17 introduces the
[`pg_createsubscriber`](
https://www.postgresql.org/docs/17/app-pgcreatesubscriber.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/app-pgcreatesubscriber.html&sa=D&source=docs&ust=1725648382497019&usg=AOvVaw10GiAnqcr6CzI8aKBzY8HH>
)
command-line tool which can be used to convert a physical replica into a
logical replica.

----------------------

> "which allows you to give users permission to execute maintenance
operations."

Suggested simplifications:

which gives users the permissions needed to perform maintenance operations.

which provides permissions for maintenance operations.

----------------------

> "the [`pg_combinebackup`](
https://www.postgresql.org/docs/17/app-pgcombinebackup.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/app-pgcombinebackup.html&sa=D&source=docs&ust=1725648572427605&usg=AOvVaw3eS-RM3R5GOIoUEt2x1cx7>
)
or the backup restoration process"

I thought the "or" here was maybe a mistake. Maybe it was meant to be "of".
With that said, I pulled in the verb "reconstruct" the docs use. It's a fun
verb and I know it coudl be translated to Spanish as reconstruir :)

Suggestion:
the [`pg_combinebackup`](
https://www.postgresql.org/docs/17/app-pgcombinebackup.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/app-pgcombinebackup.html&sa=D&source=docs&ust=1725648572427650&usg=AOvVaw2oXig2TjB3naa0s-U5z45S>
)
tool to reconstruct a full backup.

----------------------

> "reports the [progress of vacuuming indexes](
https://www.postgresql.org/docs/17/progress-reporting.html#VACUUM-PROGRESS-REPORTING
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/progress-reporting.html%23VACUUM-PROGRESS-REPORTING&sa=D&source=docs&ust=1725648678260693&usg=AOvVaw2M2U_9jfkP2SmYOZmN3dc7>
),
and adds the [`pg_wait_events`](
https://www.postgresql.org/docs/17/view-pg-wait-events.html
<https://www.google.com/url?q=https://www.postgresql.org/docs/17/view-pg-wait-events.html&sa=D&source=docs&ust=1725648678260725&usg=AOvVaw170rrczhgv92ZWo5icxcG5>
)

For the system views, is the standard to refer to them without using the
words system view? If so, it's fine here. If not, I think it's missing that.

Suggestion: "adds the `pg_wait_events` system view" (or "view")

----------------------

"Many other new features and improvements have been added to PostgreSQL 17.
Many
of these may also be helpful for your use cases."

Recommend consolidating these two sentences.

----------------------

"## Licence" is the british english spelling intended here?

----------------------

Looks great! I even learned about more new features in this revised
version! I checked the links and saw "17" everywhere I'd expect to see it.

On Fri, Sep 6, 2024 at 12:28 PM Adrian Klaver <[email-masked]>
wrote:

> [`pg_combinebackup`](
> https://www.postgresql.org/docs/17/app-pgcombinebackup.html)
>

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Sat, 7 Sep 2024 14:44:05 -0400

On 9/6/24 2:02 PM, Andrew Atkinson wrote:
> This is looking crisper. Nice edits! I did one more read through and 
> have minor comments and suggestions.
Thanks Andy and Adrian (and Robert and Peter and Alicja). Here is the 
latest draft, based on your feedback.

Thanks,

Jonathan

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Mon, 9 Sep 2024 10:51:23 -0400

> latest draft, based on your feedback.

Thank you everyone for your feedback on the PG17 release GA 
announcement. The content is now frozen and we've begun the translation 
process. You can view the canonical copy here:

https://git.postgresql.org/gitweb/?p=press.git;a=blob_plain;f=releases/17/release.en.md;hb=HEAD

Thanks,

Jonathan