Document DELETE/UPDATE command tag vs triggers

Hi list,

Currently the documentation for DELETE and UPDATE doesn't mention that
the number returned in the command tag is affected by triggers which
may suppress the change.

Worse, it currently states "If count is 0, no rows matched the
condition" which is incorrect -- the condition may have matched rows,
but the trigger might be suppressing the updates.

The new text says:

The <replaceable class="parameter">count</replaceable> is the number
of rows updated, including matched rows whose values did not change.
Note that the number may be less than the number of rows that matched
the <replaceable class="parameter">condition</replaceable> when
updates were suppressed by a <literal>BEFORE UPDATE</> trigger. If
<replaceable class="parameter">count</replaceable> is 0, no rows were
updated by the query (this is not considered an error).

Patch attached.

Regards,
Marti

On Sat, Sep 17, 2011 at 22:43, Marti Raudsepp <marti(at)juffo(dot)org> wrote:
> Currently the documentation for DELETE and UPDATE doesn't mention that
> the number returned in the command tag is affected by triggers which
> may suppress the change.

Bump! What's the right procedure for submitting documentation patches?
The CommitFest app doesn't have a "documentation" category.

Regards,
Marti

On 25.09.2011 16:12, Marti Raudsepp wrote:
> Bump! What's the right procedure for submitting documentation patches?
> The CommitFest app doesn't have a "documentation" category.

Feel free to add one. The categories, or topics, are editable: click on
the "CommitFest Topics" link near the top-right corner, next to the "New
Patch" link. Then "New Topic".

--
Heikki Linnakangas
EnterpriseDB http://www.enterprisedb.com

On Sun, Sep 25, 2011 at 9:35 AM, Heikki Linnakangas
<heikki(dot)linnakangas(at)enterprisedb(dot)com> wrote:
> On 25.09.2011 16:12, Marti Raudsepp wrote:
>>
>> Bump! What's the right procedure for submitting documentation patches?
>> The CommitFest app doesn't have a "documentation" category.
>
> Feel free to add one. The categories, or topics, are editable: click on the
> "CommitFest Topics" link near the top-right corner, next to the "New Patch"
> link. Then "New Topic".

Committed.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Mon, Oct 10, 2011 at 19:58, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> Committed.

Thanks!

Do you think it should be backported to earlier versions too? As it
stands, the documentation is misleading.

Regards,
Marti

On Wed, Oct 12, 2011 at 4:39 AM, Marti Raudsepp <marti(at)juffo(dot)org> wrote:
> On Mon, Oct 10, 2011 at 19:58, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> Committed.
>
> Thanks!
>
> Do you think it should be backported to earlier versions too? As it
> stands, the documentation is misleading.

Well, I committed about five doc patches that day, and I had to decide
for each one whether it was worth back-patching, and if so whether it
was worth back-patching all the way or just to 9.1. (We typically
back-patch things to all applicable versions or not at all, but for
doc changes sometimes we go back exactly one release so that it will
make its way onto the most current version of the web site docs a
little bit more quickly.) I decided against back-patching this one,
on the theory that we make many documentation improvements over the
course of every major release cycle, and back-patching all of them
creates more work for translators than can really be justified by the
small number of people who read older versions of the documentation.
It's an arguable point, of course, and I wouldn't have objected if
someone else had chosen differently.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas wrote:
> On Wed, Oct 12, 2011 at 4:39 AM, Marti Raudsepp <marti(at)juffo(dot)org> wrote:
> > On Mon, Oct 10, 2011 at 19:58, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> >> Committed.
> >
> > Thanks!
> >
> > Do you think it should be backported to earlier versions too? As it
> > stands, the documentation is misleading.
>
> Well, I committed about five doc patches that day, and I had to decide
> for each one whether it was worth back-patching, and if so whether it
> was worth back-patching all the way or just to 9.1. (We typically
> back-patch things to all applicable versions or not at all, but for
> doc changes sometimes we go back exactly one release so that it will
> make its way onto the most current version of the web site docs a
> little bit more quickly.) I decided against back-patching this one,
> on the theory that we make many documentation improvements over the
> course of every major release cycle, and back-patching all of them
> creates more work for translators than can really be justified by the
> small number of people who read older versions of the documentation.
> It's an arguable point, of course, and I wouldn't have objected if
> someone else had chosen differently.

I agree with your analysis.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

On Wed, Oct 12, 2011 at 19:48, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> Well, I committed about five doc patches that day, and I had to decide
> for each one whether it was worth back-patching,

> I decided against back-patching this one

Sounds fair.

For what it's worth, I wasn't doubting your judgement. Just that it
wasn't clear to me whether you had considered backpatching or not.

Regards,
Marti

On Wed, Oct 12, 2011 at 2:27 PM, Marti Raudsepp <marti(at)juffo(dot)org> wrote:
> On Wed, Oct 12, 2011 at 19:48, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> Well, I committed about five doc patches that day, and I had to decide
>> for each one whether it was worth back-patching,
>
>> I decided against back-patching this one
>
> Sounds fair.
>
> For what it's worth, I wasn't doubting your judgement. Just that it
> wasn't clear to me whether you had considered backpatching or not.

Hmm, I probably could've clarified that in my email instead of just
saying "Committed". Will try to remember that next time.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company