BUG #7846: Documentation: Should FOUND be documented as an output of UPDATE statement?

[m***@fontling.com]

The following bug has been logged on the website:

Bug reference: 7846
Logged by: Mike Sherrill
Email address: ***@fontling.com
PostgreSQL version: 9.1.6
Operating system: Ubuntu Linux 12.04
Description:

Documentation for the SQL UPDATE statement doesn't mention that it sets the
FOUND variable. (Refer to sql-update.html, "Outputs".) That behavior *is*
documented, but only in plpgsql-statements.html (Basic Statements, section
39.5.5).

I understand the difference between a SQL statement and a PL/PGSQL
statement. But if I were looking for the effects and side-effects of an
UPDATE statement, I'd go to the docs for UPDATE, not for PL/PGSQL basic
statements. I think that's what most people would do, especially if they
didn't have prior knowledge of the FOUND variable.

[Kevin Grittner]

Post by m***@fontling.com
Documentation for the SQL UPDATE statement doesn't mention that
it sets the FOUND variable. (Refer to sql-update.html,
"Outputs".) That behavior *is* documented, but only in
plpgsql-statements.html (Basic Statements, section 39.5.5).
I understand the difference between a SQL statement and a
PL/PGSQL statement. But if I were looking for the effects and
side-effects of an UPDATE statement, I'd go to the docs for
UPDATE, not for PL/PGSQL basic statements. I think that's what
most people would do, especially if they didn't have prior
knowledge of the FOUND variable.

Outside of plpgsql there isn't any FOUND variable to set.  If we
did what you suggest, I think we'd get bug reports about this:

test=# update t set amt = 2 where id = 1;
UPDATE 1
test=# select found;
ERROR:  column "found" does not exist
LINE 1: select found;
               ^

plpgsql creates a FOUND variable and sets it based on the rows
affected by various statements. Besides that, with all the various
PLs that are supported in PostgreSQL, littering the documention of
each SQL statement with details of how that statement is supported
in each PL would get really messy really quickly.

-Kevin