Doc: improve and centralize the documentation for OID alias types.

Previously, a lot of information about type regclass existed only
in the discussion of the sequence functions.  Maybe that made sense
in the beginning, because I think originally those were the only
functions taking regclass.  But it doesn't make sense anymore.
Move that material to the "Object Identifier Types" section in
datatype.sgml, generalize it to talk about the other reg* types
as well, and add more examples.

Per bug #16991 from Federico Caselli.

Discussion: https://postgr.es/m/16991-bcaeaafa17e0a723@postgresql.org

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 7c341c8e3fa6d29578746c22fd4637ed0926ede2..0e8ef958a93e11704fca600717deaec376684ba0 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -4632,7 +4632,8 @@ INSERT INTO mytable VALUES(-1);  -- fails
     PostgreSQL as primary keys for various
     system tables.
     Type oid represents an object identifier.  There are also
-    several alias types for oid named regsomething.
+    several alias types for oid, each
+    named regsomething.
      shows an
     overview.
    
@@ -4780,10 +4781,14 @@ SELECT * FROM pg_attribute
     
 
    
-    All of the OID alias types for objects grouped by namespace accept
-    schema-qualified names, and will
+    All of the OID alias types for objects that are grouped by namespace
+    accept schema-qualified names, and will
     display schema-qualified names on output if the object would not
     be found in the current search path without being qualified.
+    For example, myschema.mytable is acceptable input
+    for regclass (if there is such a table).  That value
+    might be output as myschema.mytable, or
+    just mytable, depending on the current search path.
     The regproc and regoper alias types will only
     accept input names that are unique (not overloaded), so they are
     of limited use; for most uses regprocedure or
@@ -4792,6 +4797,87 @@ SELECT * FROM pg_attribute
     operand.
    
 
+   
+    The input functions for these types allow whitespace between tokens,
+    and will fold upper-case letters to lower case, except within double
+    quotes; this is done to make the syntax rules similar to the way
+    object names are written in SQL.  Conversely, the output functions
+    will use double quotes if needed to make the output be a valid SQL
+    identifier.  For example, the OID of a function
+    named Foo (with upper case F)
+    taking two integer arguments could be entered as
+    ' "Foo" ( int, integer ) '::regprocedure.  The
+    output would look like "Foo"(integer,integer).
+    Both the function name and the argument type names could be
+    schema-qualified, too.
+   
+
+   
+    Many built-in PostgreSQL functions accept
+    the OID of a table, or another kind of database object, and for
+    convenience are declared as taking regclass (or the
+    appropriate OID alias type).  This means you do not have to look up
+    the object's OID by hand, but can just enter its name as a string
+    literal.  For example, the nextval(regclass) function
+    takes a sequence relation's OID, so you could call it like this:
+
+nextval('foo')              operates on sequence foo
+nextval('FOO')              same as above
+nextval('"Foo"')            operates on sequence Foo
+nextval('myschema.foo')     operates on myschema.foo
+nextval('"myschema".foo')   same as above
+nextval('foo')              searches search path for foo
+
+   
+
+   
+    
+     When you write the argument of such a function as an unadorned
+     literal string, it becomes a constant of type regclass
+     (or the appropriate type).
+     Since this is really just an OID, it will track the originally
+     identified object despite later renaming, schema reassignment,
+     etc.  This early binding behavior is usually desirable for
+     object references in column defaults and views.  But sometimes you might
+     want late binding where the object reference is resolved
+     at run time.  To get late-binding behavior, force the constant to be
+     stored as a text constant instead of regclass:
+
+nextval('foo'::text)      foo is looked up at runtime
+
+     The to_regclass() function and its siblings
+     can also be used to perform run-time lookups.  See
+     .
+    
+   
+
+   
+    Another practical example of use of regclass
+    is to look up the OID of a table listed in
+    the information_schema views, which don't supply
+    such OIDs directly.  One might for example wish to call
+    the pg_relation_size() function, which requires
+    the table OID.  Taking the above rules into account, the correct way
+    to do that is
+
+SELECT table_schema, table_name,
+       pg_relation_size((quote_ident(table_schema) || '.' ||
+                         quote_ident(table_name))::regclass)
+FROM information_schema.tables
+WHERE ...
+
+    The quote_ident() function will take care of
+    double-quoting the identifiers where needed.  The seemingly easier
+
+SELECT pg_relation_size(table_name)
+FROM information_schema.tables
+WHERE ...
+
+    is not recommended, because it will fail for
+    tables that are outside your search path or have names that require
+    quoting.
+   
+
    
     An additional property of most of the OID alias types is the creation of
     dependencies.  If a
@@ -4801,19 +4887,13 @@ SELECT * FROM pg_attribute
     expression nextval('my_seq'::regclass),
     PostgreSQL
     understands that the default expression depends on the sequence
-    my_seq; the system will not let the sequence be dropped
-    without first removing the default expression.
-    regrole is the only exception for the property. Constants of this
-    type are not allowed in such expressions.
-   
-
-   
-   
-    The OID alias types do not completely follow transaction isolation
-    rules. The planner also treats them as simple constants, which may
-    result in sub-optimal planning.
+    my_seq, so the system will not let the sequence
+    be dropped without first removing the default expression.  The
+    alternative of nextval('my_seq'::text) does not
+    create a dependency.
+    (regrole is an exception to this property. Constants of this
+    type are not allowed in stored expressions.)
    
-   
 
    
     Another identifier type used by the system is xid, or transaction

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 5ae8abff0ce4c6cd9c6073550e64d447b086aad2..c60d98360ff898723cc3acf2f63fa8b51bc4a361 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -14429,8 +14429,9 @@ SELECT xmltable.*
     table_to_xml maps the content of the named
     table, passed as parameter table.  The
     regclass type accepts strings identifying tables using the
-    usual notation, including optional schema qualifications and
-    double quotes.  query_to_xml executes the
+    usual notation, including optional schema qualification and
+    double quotes (see  for details).
+    query_to_xml executes the
     query whose text is passed as parameter
     query and maps the result set.
     cursor_to_xml fetches the indicated number of
@@ -17316,49 +17317,9 @@ SELECT setval('myseq', 42, false);    Next nextval
    a regclass argument, which is simply the OID of the sequence in the
    pg_class system catalog.  You do not have to look up the
    OID by hand, however, since the regclass data type's input
-   converter will do the work for you.  Just write the sequence name enclosed
-   in single quotes so that it looks like a literal constant.  For
-   compatibility with the handling of ordinary
-   SQL names, the string will be converted to lower case
-   unless it contains double quotes around the sequence name.  Thus:
-
-nextval('foo')      operates on sequence foo
-nextval('FOO')      operates on sequence foo
-nextval('"Foo"')    operates on sequence Foo
-
-   The sequence name can be schema-qualified if necessary:
-
-nextval('myschema.foo')     operates on myschema.foo
-nextval('"myschema".foo')   same as above
-nextval('foo')              searches search path for foo
-
-   See  for more information about
-   regclass.
+   converter will do the work for you.  See 
+   for details.
   
-
-  
-   
-    When you write the argument of a sequence function as an unadorned
-    literal string, it becomes a constant of type regclass.
-    Since this is really just an OID, it will track the originally
-    identified sequence despite later renaming, schema reassignment,
-    etc.  This early binding behavior is usually desirable for
-    sequence references in column defaults and views.  But sometimes you might
-    want late binding where the sequence reference is resolved
-    at run time.  To get late-binding behavior, force the constant to be
-    stored as a text constant instead of regclass:
-
-nextval('foo'::text)      foo is looked up at runtime
-
-   
-
-   
-    Of course, the argument of a sequence function can be an expression
-    as well as a constant.  If it is a text expression then the implicit
-    coercion will result in a run-time lookup.
-   
-  
-
  
 
 
@@ -26474,11 +26435,8 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
     regclass argument, which is simply the OID of the table or index
     in the pg_class system catalog.  You do not have to look up
     the OID by hand, however, since the regclass data type's input
-    converter will do the work for you.  Just write the table name enclosed in
-    single quotes so that it looks like a literal constant.  For compatibility
-    with the handling of ordinary SQL names, the string
-    will be converted to lower case unless it contains double quotes around
-    the table name.
+    converter will do the work for you.  See 
+    for details.