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

The following bug has been logged on the website:

Bug reference:      7846
Logged by:          Mike Sherrill
Email address:      mike@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.

"mike@fontling.com" <mike@fontling.com> wrote:=0A=0A> Documentation for the=
 SQL UPDATE statement doesn't mention that=0A> it sets the FOUND variable. =
(Refer to sql-update.html,=0A> "Outputs".) That behavior *is* documented, b=
ut only in=0A> plpgsql-statements.html (Basic Statements, section 39.5.5).=
=0A>=0A> I understand the difference between a SQL statement and a=0A> PL/P=
GSQL statement. But if I were looking for the effects and=0A> side-effects =
of an UPDATE statement, I'd go to the docs for=0A> UPDATE, not for PL/PGSQL=
 basic statements. I think that's what=0A> most people would do, especially=
 if they didn't have prior=0A> knowledge of the FOUND variable.=0A=0AOutsid=
e of plpgsql there isn't any FOUND variable to set.=A0 If we=0Adid what you=
 suggest, I think we'd get bug reports about this:=0A=0Atest=3D# update t s=
et amt =3D 2 where id =3D 1;=0AUPDATE 1=0Atest=3D# select found;=0AERROR:=
=A0 column "found" does not exist=0ALINE 1: select found;=0A=A0=A0=A0=A0=A0=
=A0=A0=A0=A0=A0=A0=A0=A0=A0 ^=0A=0Aplpgsql creates a FOUND variable and set=
s it based on the rows=0Aaffected by various statements. Besides that, with=
 all the various=0APLs that are supported in PostgreSQL, littering the docu=
mention of=0Aeach SQL statement with details of how that statement is suppo=
rted=0Ain each PL would get really messy really quickly.=0A=0A-Kevin