Thread: BUG #13495: Postgres documentation consistently teaches 'bad' practice
BUG #13495: Postgres documentation consistently teaches 'bad' practice
From
grb@skogoglandskap.no
Date:
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.