diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 7c341c8e3fa..0e8ef958a93 100644 --- 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,20 +4887,14 @@ 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. + 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.) - - - 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. - - - Another identifier type used by the system is xid, or transaction (abbreviated xact) identifier. This is the data type of the system columns diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 5ae8abff0ce..c60d98360ff 100644 --- 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 nextvalregclass 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.