Обсуждение: BUG #13495: Postgres documentation consistently teaches 'bad' practice

The following bug has been logged on the website:

Bug reference:      13495
Logged by:          Graeme Bell
Email address:      grb@skogoglandskap.no
PostgreSQL version: 9.3.9
Operating system:   Linux
Description:

Relates to a current thread on pgsql-performance.

The postgres documentation presently teaches bad practice to new programmers
by failing to use function volatility categories in examples throughout
most/all of the documentation.

Consequently, many new and existing PG users are writing code that performs
poorly and doesn't scale at all, and don't even know it.

For example: count the uses of volatility classes on these pages.

http://www.postgresql.org/docs/9.3/static/plpgsql-structure.html

http://www.postgresql.org/docs/9.3/static/plpgsql-declarations.html#PLPGSQL-DECLARATION-PARAMETERS

Proposed solution:

This issue is absolutely critical for performance and scalability of code,
therefore all of the PG example functions, particularly in the first few
chapters of the documentation, could be altered to demonstrate  correctly
written code in terms of good practice for performance and scability.

My feeling is that good practice should be naturally  acquired by the reader
as they read the first 20 pages of the manual.

On 2015-07-09 09:52:59 +0000, grb@skogoglandskap.no wrote:
> Relates to a current thread on pgsql-performance.

Can we please, please, not spread the discussion out any further. It's
bad enough that we're already discussing on separate threads on -bugs
and -performance.

> This issue is absolutely critical for performance and scalability of code,

Pft. In most cases it doesn't actually matter that much because the
contained query are the expensive stuff. It's just when you do lots of
very short and cheap things that it has such a big effect.  Usually the
effect on the planner is bigger.

That said, I don't mind improving the docs here, they're not easy to
grasp. But it probably shouldn't be in plpgsql's docs, but rather the
general function ones.