rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: update CREATE RULE ref page's hoary discussion of views. 

This text left one with the impression that an ON SELECT rule could
be attached to a plain table, which has not been true since commit
264c06820 (meaning the text was already misleading when written,
evidently by me in 96bd67f61).  However, it didn't get really bad
until b23cd185f removed the convert-a-table-to-a-view logic, which
had made it possible for scripts that thought they were attaching
ON SELECTs to tables to still work.

Rewrite into a form that makes it clear that an ON SELECT rule
is better regarded as an implementation detail of a view.
Pre-v16, point out that adding ON SELECT to a table actually
converts it to a view.

Per bug #18178 from Joshua Uyehara.  Back-patch to all supported
branches.

Discussion: https://postgr.es/m/18178-05534d7064044d2d@postgresql.org
This commit is contained in:
Tom Lane 2023-11-03 11:48:23 -04:00
parent 36c32af79e
commit f53f83b33e
1 changed files with 11 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/src/sgml/ref/create_rule.sgml
View File

@ -59,15 +59,17 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS
</para> </para>
<para> <para>
Presently, <literal>ON SELECT</literal> rules must be unconditional Presently, <literal>ON SELECT</literal> rules can only be attached
<literal>INSTEAD</literal> rules and must have actions that consist to views. (Attaching one to a table converts the table into a view.)
of a single <command>SELECT</command> command. Thus, an Such a rule must be named <literal>"_RETURN"</literal>,
<literal>ON SELECT</literal> rule effectively turns the table into must be an unconditional <literal>INSTEAD</literal> rule, and must have
a view, whose visible contents are the rows returned by the rule's an action that consists of a single <command>SELECT</command> command.
<command>SELECT</command> command rather than whatever had been This command defines the visible contents of the view. (The view
stored in the table (if anything). It is considered better style itself is basically a dummy table with no storage.) It's best to
to write a <command>CREATE VIEW</command> command than to create a regard such a rule as an implementation detail. While a view can be
real table and define an <literal>ON SELECT</literal> rule for it. redefined via <literal>CREATE OR REPLACE RULE "_RETURN" AS
...</literal>, it's better style to use <literal>CREATE OR REPLACE
VIEW</literal>.
</para> </para>
<para> <para>