Hi,
I have made various, mostly unrelated to each other,
small improvements to the documentation. These
are usually in the areas of plpgsql, schemas, and permissions.
Most change 1 lines, but some supply short overviews.
"Short" is subjective, so if these need to be
broken into different threads or different
commitfest entries let me know. I'm starting
simple and submitting a single patch.
Attached: various_doc_patches_v1.patch
Regards,
Karl <k...@karlpinc.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 6bc1b215db..ea70dd3597 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -10,7 +10,27 @@
<para>
There are many configuration parameters that affect the behavior of
- the database system. In the first section of this chapter we
+ the database system.
+ A single master list of all parameters and their characteristics is not
+ provided in the documentation.
+ The pg_settings view into the system catalogs can provide such summaries,
+ e.g:
+ </para>
+
+<programlisting>
+-- Describe all configuration parameters.
+SELECT name, short_desc FROM pg_settings ORDER BY name;
+
+-- Show the current configuration of the connected database and session.
+SELECT name, setting, unit FROM pg_settings ORDER BY name;
+
+-- Show the means available to change the setting; whether the setting is
+-- per-cluster, per-database, per-session, etc.
+SELECT name, context FROM pg_settings ORDER BY name;
+</programlisting>
+
+ <para>
+ In the first section of this chapter we
describe how to interact with configuration parameters. The subsequent sections
discuss each parameter in detail.
</para>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 8d32a8c9c5..91cc1e5cb0 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -4754,6 +4754,17 @@ INSERT INTO mytable VALUES(-1); -- fails
signed-versus-unsigned confusion if you do this.)
</para>
+ <indexterm zone="datatype-oid">
+ <primary>oidvector</primary>
+ </indexterm>
+
+ <para>
+ The legacy <type>oidvector</type> type can be cast to an array of OIDs,
+ and vice versa, for examination and manipulation.
+ The resultant array of OIDs, unlike a typical array, is indexed
+ zero-relative.
+ </para>
+
<para>
The OID alias types have no operations of their own except
for specialized input and output routines. These routines are able
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 075ff32991..df8a373652 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3106,12 +3106,12 @@ SHOW search_path;
<para>
The first schema in the search path that exists is the default
location for creating new objects. That is the reason that by
- default objects are created in the public schema. When objects
- are referenced in any other context without schema qualification
- (table modification, data modification, or query commands) the
- search path is traversed until a matching object is found.
- Therefore, in the default configuration, any unqualified access
- again can only refer to the public schema.
+ default objects are created in the public schema.
+ When objects are referenced in a context without schema qualification
+ (table modification, data modification, or query commands) the search path
+ is traversed until a matching object is found.
+ Therefore, again, in the default configuration, any unqualified access
+ refers only to objects in the public schema.
</para>
<para>
@@ -3162,6 +3162,53 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
</para>
</sect2>
+ <sect2 id="ddl-schema-resolution">
+ <title>Schema Resolution</title>
+
+ <indexterm>
+ <primary>schema</primary>
+ <secondary>resolution</secondary>
+ </indexterm>
+
+ <para>
+ Schema resolution happens when SQL is run.
+
+ Exactly what this means is usually obvious; using an unqualified table
+ name when creating a table creates the table in the first schema of the
+ search path in effect, the current search path is used to find
+ unqualified table names when executing a <literal>SELECT</literal>, and so forth.
+ But there are less obvious implications when it comes to statements
+ that manipulate <link linkend="ddl-others">database objects</link>:
+ tables, triggers, functions and the like.
+ </para>
+
+ <para>
+ Most SQL expressions appearing within the statements that manipulate
+ database objects are resolved at the time of manipulation.
+ Consider the creation of tables and triggers.
+ The schemas of foreign key table references, the functions and operators
+ used in table and column constraint expressions, table partition
+ expressions, and so forth are resolved at the time of table creation.
+ So is the schema of the function named when a trigger is created.
+ These already-resolved tables, functions, operators,
+ etc. need <emphasis>not</emphasis> be in the search path when the
+ constraints or triggers are executed, when the content of the table is
+ modified and the data validation occurs.
+ This is just as if all the objects were fully schema qualified in the
+ SQL that created the table, trigger, or other database object.
+ </para>
+
+ <para>
+ But functions are different.
+ The point of function creation is to store code for execution later.
+ Schemas are resolved within a function body when the function is called,
+ not when the function is created.
+ This has implications for function behavior consistency and
+ <link linkend="sql-createfunction-security">security</link>.
+ For these reasons function bodies can have their own search paths.
+ </para>
+ </sect2>
+
<sect2 id="ddl-schemas-priv">
<title>Schemas and Privileges</title>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index f55e901c7e..00acf501ee 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -672,7 +672,7 @@ DECLARE
</sect2>
<sect2 id="plpgsql-declaration-type">
- <title>Copying Types</title>
+ <title>Referencing the Type of Columns and Variables</title>
<synopsis>
<replaceable>variable</replaceable>%TYPE
@@ -1126,7 +1126,7 @@ PERFORM create_mv('cs_session_page_requests_mv', my_query);
</sect2>
<sect2 id="plpgsql-statements-sql-onerow">
- <title>Executing a Command with a Single-Row Result</title>
+ <title>Saving a Single-Row Command Result</title>
<indexterm zone="plpgsql-statements-sql-onerow">
<primary>SELECT INTO</primary>
@@ -2756,7 +2756,7 @@ NOTICE: row = {10,11,12}
</sect2>
<sect2 id="plpgsql-error-trapping">
- <title>Trapping Errors</title>
+ <title>Exceptions and Error Trapping</title>
<indexterm>
<primary>exceptions</primary>
@@ -2765,8 +2765,11 @@ NOTICE: row = {10,11,12}
<para>
By default, any error occurring in a <application>PL/pgSQL</application>
- function aborts execution of the function and the
- surrounding transaction. You can trap errors and recover
+ function aborts execution of the function and the surrounding
+ transaction.
+ You can raise an exception and throw an error
+ with <link linkend="plpgsql-statements-raise">RAISE EXCEPTION ...</link>.
+ You can trap errors and recover
from them by using a <command>BEGIN</command> block with an
<literal>EXCEPTION</literal> clause. The syntax is an extension of the
normal syntax for a <command>BEGIN</command> block:
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 27c1f3d703..425eac3b61 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -9,9 +9,23 @@
either a database user, or a group of database users, depending on how
the role is set up. Roles can own database objects (for example, tables
and functions) and can assign privileges on those objects to other roles to
- control who has access to which objects. Furthermore, it is possible
- to grant <firstterm>membership</firstterm> in a role to another role, thus
- allowing the member role to use privileges assigned to another role.
+ control who has access to which objects.
+ </para>
+
+ <para>
+ It is possible to grant <firstterm>membership</firstterm> in a role to
+ another role, thus allowing the member role to use the privileges assigned
+ to another role.
+ This can happen automatically, if the role given membership has
+ the <literal>INHERIT</literal> attribute, or manually, via a <literal>SET
+ ROLE</literal> to the granted role.
+ But it is important to distinguish between privileges, which are assigned
+ with <literal>GRANT</literal>, and role attributes,
+ like <literal>INHERIT</literal>, <literal>SUPERUSER</literal>, and
+ <literal>CREATEDB</literal>, which are assigned with <literal>CREATE
+ ROLE</literal> or <literal>ALTER ROLE</literal>.
+ Privileges may be inherited, role attributes cannot and are only effective
+ when <literal>SET ROLE</literal> changes the current role.
</para>
<para>
