From f53f83b33e4203ec181c93b7fa5a2e9c70e73c31 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 3 Nov 2023 11:48:23 -0400 Subject: [PATCH] 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 --- doc/src/sgml/ref/create_rule.sgml | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/ref/create_rule.sgml b/doc/src/sgml/ref/create_rule.sgml index dbf4c93784..76029abf51 100644 --- a/doc/src/sgml/ref/create_rule.sgml +++ b/doc/src/sgml/ref/create_rule.sgml @@ -59,15 +59,17 @@ CREATE [ OR REPLACE ] RULE name AS - Presently, ON SELECT rules must be unconditional - INSTEAD rules and must have actions that consist - of a single SELECT command. Thus, an - ON SELECT rule effectively turns the table into - a view, whose visible contents are the rows returned by the rule's - SELECT command rather than whatever had been - stored in the table (if anything). It is considered better style - to write a CREATE VIEW command than to create a - real table and define an ON SELECT rule for it. + Presently, ON SELECT rules can only be attached + to views. (Attaching one to a table converts the table into a view.) + Such a rule must be named "_RETURN", + must be an unconditional INSTEAD rule, and must have + an action that consists of a single SELECT command. + This command defines the visible contents of the view. (The view + itself is basically a dummy table with no storage.) It's best to + regard such a rule as an implementation detail. While a view can be + redefined via CREATE OR REPLACE RULE "_RETURN" AS + ..., it's better style to use CREATE OR REPLACE + VIEW.