Version 5, this time with attachments.
Changed word order in a sentence:
v5-0012-Explain-role-management.patch
Added a hyperlink:
v5-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch
Added 3 index entries:
v5-0014-Add-index-entries-for-parallel-safety.patch
> On Mon, 25 Sep 2023 23:37:44 -0500
> "Karl O. Pinc" <k...@karlpinc.com> wrote:
>
> > > On Mon, 25 Sep 2023 17:55:59 -0500
> > > "Karl O. Pinc" <k...@karlpinc.com> wrote:
> > >
> > > > On Mon, 25 Sep 2023 14:14:37 +0200
> > > > Daniel Gustafsson <dan...@yesql.se> wrote:
> > >
> > > > > Once done you can do "git format-patch origin/master -v 1"
> > > > > which will generate a set of n patches named v1-0001 through
> > > > > v1-000n.
>
> > > > I am not particularly confident in the top-line commit
> > > > descriptions.
> > >
> > > > The bulk of the commit descriptions are very wordy
> > >
> > > > Listing all the attachments here for future discussion:
v5-0001-Change-section-heading-to-better-reflect-saving-a.patch
v5-0002-Change-section-heading-to-better-describe-referen.patch
v5-0003-Better-section-heading-for-plpgsql-exception-trap.patch
v5-0004-Describe-how-to-raise-an-exception-in-the-excepti.patch
v5-0005-Improve-sentences-in-overview-of-system-configura.patch
v5-0006-Provide-examples-of-listing-all-settings.patch
v5-0007-Cleanup-summary-of-role-powers.patch
v5-0008-Explain-the-difference-between-role-attributes-an.patch
v5-0009-Document-the-oidvector-type.patch
v5-0010-Improve-sentences-about-the-significance-of-the-s.patch
v5-0011-Add-a-sub-section-to-describe-schema-resolution.patch
v5-0012-Explain-role-management.patch
v5-0013-Hyperlink-from-CREATE-FUNCTION-reference-page-to-.patch
v5-0014-Add-index-entries-for-parallel-safety.patch
Regards,
Karl <k...@karlpinc.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
>From 122665c4155698abe88e2bd17639a991791b94e3 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 15:49:30 -0500
Subject: [PATCH v5 01/14] Change section heading to better reflect saving a
result in variable(s)
The current section title of "Executing a Command with a Single-Row
Result" does not reflect what the section is really about. Other
sections make clear how to _execute_ commands, single-row result or not.
What this section is about is how to _save_ a single row of results into
variable(s).
It would be nice to talk about saving results into variables in the
section heading but I couldn't come up with anything pithy. "Saving a
Single-Row of a Command's Result" seems good enough, especially since
there's few other places to save results other than in variables.
---
doc/src/sgml/plpgsql.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index f55e901c7e..8747e84245 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -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 of a Command's Result</title>
<indexterm zone="plpgsql-statements-sql-onerow">
<primary>SELECT INTO</primary>
--
2.30.2
>From 4de4a31d41124dfa793cc5cce0516673811ea414 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 15:52:21 -0500
Subject: [PATCH v5 02/14] Change section heading to better describe reference
of existing types
The section heading of "Copying Types" does not reflect what the
section is about. It is not about making copies of data types but
about using the data type of existing columns (or rows) in new type
declarations without having to know what the existing type is.
"Re-Using the Type of Columns and Variables" seems adequate. Getting
something in there about declartions seems too wordy. I thought
perhaps "Referencing" instead of "Re-Using", but "referencing" isn't
perfect and "re-using" is generic enough, shorter, and simpler to read.
---
doc/src/sgml/plpgsql.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 8747e84245..874578265e 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>Re-Using the Type of Columns and Variables</title>
<synopsis>
<replaceable>variable</replaceable>%TYPE
--
2.30.2
>From 80c2b8ef7ad6e610f5c7bdc61b827983a87110e2 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 16:03:29 -0500
Subject: [PATCH v5 03/14] Better section heading for plpgsql exception
trapping
The docs seem to use "error" and "exception" interchangeably, perhaps
50% each. But they never say that the are the same thing, and in the
larger world they are not. Errors tend to be something that drop on
the floor and usually halt execution whereas exceptions can be trapped
and give the programmer more control over the flow of the program.
(Although, to be fair, exceptions are a subset of errors.) "Trapping
Errors" is not a good section title for these reasons, and because
when it comes to programmatically raising errors in Pl/PgSQL you
don't, you raise exceptions. The current section heading does not
stand out in a scan of the table of contents when you're looking for
exception handling, IMHO.
"Error Processing and Trapping Exceptions" is a little long but it
does accurately reflect that the section is about how Pl/PgSQL behaves
under error conditions with quite a lot about how the programmer can
trap exceptions, affect the program's flow of control, and process
information about errors. The "Exception" is at the end, and so
stands out after the section title is read. (At least, according to
my understanding, the end of a sentence is the most memorable.) I
left "Error" in the title since the word "error" is used so frequently
in the docs, and the section is also about what happens when there is
any sort of PG error, not just those raised in user code. Error comes
first to stand upon a visual scan of the table of contents.
---
doc/src/sgml/plpgsql.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 874578265e..127dd1b337 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2756,7 +2756,7 @@ NOTICE: row = {10,11,12}
</sect2>
<sect2 id="plpgsql-error-trapping">
- <title>Trapping Errors</title>
+ <title>Error Processing and Trapping Exceptions</title>
<indexterm>
<primary>exceptions</primary>
--
2.30.2
>From fcc7f8289c078ac0e7174ce16a030c11a163a1db Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 16:03:59 -0500
Subject: [PATCH v5 04/14] Describe how to raise an exception in the exception
section
Most of this section is about managing program control flow, but the
section does not mention how to raise an exception anywhere. This new
sentence says how, and provides a link into the section on raising
exceptions for those who want to know more.
Line break after end of sentence to simplify reading of future patches.
---
doc/src/sgml/plpgsql.sgml | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 127dd1b337..54402752b2 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -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:
--
2.30.2
>From 1b798d07c6a44855cb3e6e67809f41acd9282ab2 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Mon, 25 Sep 2023 15:32:23 -0500
Subject: [PATCH v5 05/14] Improve sentences in overview of system
configuration parameters
Get rid of "we" wording. Remove extra words in sentences.
Line break after end of each sentence to ease future patch reading.
---
doc/src/sgml/config.sgml | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 6bc1b215db..97f9838bfb 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -10,9 +10,10 @@
<para>
There are many configuration parameters that affect the behavior of
- the database system. In the first section of this chapter we
- describe how to interact with configuration parameters. The subsequent sections
- discuss each parameter in detail.
+ the database system.
+ The first section of this chapter describes how to interact with
+ configuration parameters.
+ Subsequent sections discuss each parameter in detail.
</para>
<sect1 id="config-setting">
--
2.30.2
>From 7a48244dd5bee61e1c3e9dd3854e214b034ab02e Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Mon, 25 Sep 2023 15:36:23 -0500
Subject: [PATCH v5 06/14] Provide examples of listing all settings
This commit is problematic in that it does something that is not done
elsewhere in the documentation, it provides example SELECTs as a
stand-in for a regular tabular documentation element. It is almost
something that should go in its own appendix, but I don't think that
is warranted. Likewise, I think that having another tabular
documentation element that must be maintained and kept up-to-date is
also not appropriate.
It is useful to have tabular overviews of all available system
settings, as is having an overview of the setting values of your
particular cluster. This commit is an attempt in that direction.
---
doc/src/sgml/config.sgml | 37 +++++++++++++++++++++++++++++++++++++
1 file changed, 37 insertions(+)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 97f9838bfb..0af4e6dcae 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11,6 +11,43 @@
<para>
There are many configuration parameters that affect the behavior of
the database system.
+ A single master list of all parameters and their characteristics is not
+ provided in this document.
+ Use the <link linkend="bookindex">index</link> (or web search) to find
+ configuration parameter documentation by name.
+ </para>
+
+ <indexterm>
+ <primary>pg_settings</primary>
+ <secondary>example queries</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>configuration</primary>
+ <secondary>query the current settings</secondary>
+ </indexterm>
+
+ <para>
+ The <link linkend="view-pg-settings">pg_settings</link>
+ <link linkend="tutorial-views">view</link> into
+ the <link linkend="catalogs">system catalogs</link> provides summaries of
+ all, or selected, configuration parameters, 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 cluster, 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>
The first section of this chapter describes how to interact with
configuration parameters.
Subsequent sections discuss each parameter in detail.
--
2.30.2
>From a9ec4dce44fd3fa59a9de4704c4d7f255ac2b1e8 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Mon, 25 Sep 2023 16:39:02 -0500
Subject: [PATCH v5 07/14] Cleanup summary of role powers.
Make sentences shorter. Explain privileges v.s. permissions.
This commit assumes that there is a distinction in the PostgreSQL
vocabulary between role privileges and permissions. Privileges being
a specific Postgres term for powers granted to roles via GRANT.
Permissions being abilities to perform specific operations that comes
with privileges, but also with role attributes like CREATEDB. So
permissions are a broader category than privileges, in terms of where
they come from. As well as being a narrower category in another
sense, in that some privileges, like object ownership, carry with them
a swath of individual permissions/abilities, like USAGE.
It seems a useful distinction to make, in terms of thinking about how
object access works. Essential in fact, since both privileges
(e.g. ownership) and role attributes (e.g. SUPERUSER) give roles
abilities, aka permissions (e.g. SELECT). Without the distinction you
can't describe role inheritance (attributes don't, privileges do) or
discuss the source of particular access rights. If access rights, aka
permissions, aka "abilities to do things", are the same as privileges
how come some privileges convey multiple abilities, abilities that
have their own names; how can you get an ability via a role attribute
but not have the privilege? It seems most clear to, conceptually at
least, have a separate set of permissions (abilities) that come via
privileges granted to roles and role attributes assigned to roles.
So, I'm not sure my choice of vocabulary is perfect. One might use
"rights" or some other word rather than "permissions". But I think
that there should be a clear distinction between the 3 concepts of
granted privileges, role attributes, and permissions to perform
specific operations.
I also would argue that it is not necessary to scour the existing
documentation and patch to obtain perfect consistency in vocabulary
usage. The existing wording seems acceptable in practice and I don't
see anyone who's read what's already there to be confused by the
changes presented here.
---
doc/src/sgml/user-manag.sgml | 13 ++++++++-----
1 file changed, 8 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 27c1f3d703..492325e8a2 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -7,11 +7,14 @@
<productname>PostgreSQL</productname> manages database access permissions
using the concept of <firstterm>roles</firstterm>. A role can be thought of as
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.
+ the role is set up.
+ Roles can own database objects (for example, tables and functions).
+ They can assign privileges on the owned objects, and thus the permissions
+ the privileges carry, to other roles.
+ Roles therefore control who has what access to which objects.
+ 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.
</para>
<para>
--
2.30.2
>From d09293d321a614095cd1fa3fb949b18190c0130d Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Mon, 25 Sep 2023 17:18:58 -0500
Subject: [PATCH v5 08/14] Explain the difference between role attributes and
role privileges
All of the information presented here is present elsewhere in the
documentation, but scattered about. It is useful to have a summary;
one place where the interactions between INHERIT, the other role
attributes, and granting of privileges with roles is explained.
Otherwise, it is hard to synthesize this out of bits and pieces
mentioned elsewhere.
---
doc/src/sgml/user-manag.sgml | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 492325e8a2..4a26ede8fb 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -12,9 +12,37 @@
They can assign privileges on the owned objects, and thus the permissions
the privileges carry, to other roles.
Roles therefore control who has what access to which objects.
+ </para>
+
+ <indexterm>
+ <primary>role</primary>
+ <secondary>inheriting permissions</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>role</primary>
+ <secondary>attributes</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>role</primary>
+ <secondary>current role</secondary>
+ </indexterm>
+
+ <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 acquisition of privilege 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>
--
2.30.2
>From 2f4ff2b80572db32428a2284279673f9497ad40f Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 16:36:36 -0500
Subject: [PATCH v5 09/14] Document the oidvector type
The oidvector type is used in pg_proc.proargtypes, and perhaps
elsewhere in the catalogs. But there is no documentation on how to
get oids out of a oidvector or otherwise manipulate the data type for
those who wish to do so. This seems the only place where such
documentation would go.
---
doc/src/sgml/datatype.sgml | 11 +++++++++++
1 file changed, 11 insertions(+)
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
--
2.30.2
>From c012c0261053ea80a657d53ca0b4bea069c9bc91 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 16:39:24 -0500
Subject: [PATCH v5 10/14] Improve sentences about the significance of the
search path's first schema
These two sentences have extra words, and can be improved with small
word re-ordering. The word "again" could probably be removed as well
but it reads ok with it and it does not hurt to pound the point into
the reader's brain.
Note however that the original last sentence still isn't 100% correct,
because the default configuration includes "$user" at the start of the
search path. So if an object is in the user's schema an unqualified
mention refers to something in the user's schema. Hence, the
qualification that comes after the semicolon. I thought about a
separate sentence, but the 2 parts are closely intertwined. So,
semicolon. It's all kind of a lot. But, although I do believe in
removing extra content from sentences to make them shorter, more
clear, and memorable, I do think it's ok to repeat things when writing
narrative. And the existing documentation is going for repetition so I
stuck with that.
Line break after each end of sentence to improve readability of future
patches.
---
doc/src/sgml/ddl.sgml | 14 ++++++++------
1 file changed, 8 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 075ff32991..ee30b7b575 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3106,12 +3106,14 @@ 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 name
+ refers to an object in the public schema; unless, given the default search
+ path, there is an object with that name accessible in the schema having
+ the name of the current user.
</para>
<para>
--
2.30.2
>From b3e4455b15a1a5b2dac454058fbca1d1fd4811c8 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 24 Sep 2023 16:59:03 -0500
Subject: [PATCH v5 11/14] Add a sub-section to describe schema resolution
There are some subtleties to schema resolution. At first glance it
seems like schema resolution is "for runtime", i.e. it matters when
querying or altering database data. But it takes a little bit of
thought to reason through what schema resolution means for DDL. It is
almost surprising that the search path in effect at DDL time persists,
in a sense, in a useful way, regardless of the search path in effect
during "regular" database use.
This explanation also sheds light on the use of CREATE OR REPLACE
sorts of syntaxes, and what gets changed when such syntax is used and
what does not, and why. At least for those who do not poke about in
the system catalogs and understand the oid relationships.
Using the word "manipulate" is a bit awkward, but is what I came up
with and I believe is made clear. Maybe there's better phrasing.
Lead the reader through the implications of the search path in a DDL
context so they can better reason about the best search path to use in
their problem domain and better understand why PG behaves as it does.
The whole thing is a little bit wordy and repeats some information
present in other sections. But this allows the new section to stand
on its own.
---
doc/src/sgml/ddl.sgml | 48 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 48 insertions(+)
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index ee30b7b575..6fc6c37b1d 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3164,6 +3164,54 @@ 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>
--
2.30.2
>From 9d7b98d2f0441ee62a65fd48124ac0f362a43050 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sat, 30 Sep 2023 19:29:46 -0500
Subject: [PATCH v5 12/14] Explain role management
It is non-obvious how the permission mechanisms control how
roles are managed, and can be difficult to find the place in
the documentation that describes the details. When you do,
the details are mixed in with other details un-related to
setting up a management structure for roles.
It is worth providing a concise summary of how roles are managed,
alongside other high-level information related to roles.
---
doc/src/sgml/user-manag.sgml | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 4a26ede8fb..b3422ec4f0 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -52,6 +52,15 @@
there are only roles. Any role can act as a user, a group, or both.
</para>
+ <para>
+ The managment of most database objects is by way of granting some role
+ ownership, but roles don't have owners.
+ Instead, roles are <link linkend="role-creation">managed</link> by
+ those roles having the <literal>CREATEROLE</literal> attribute, that
+ are also granted <literal>ADMIN</literal> privileges to the roles
+ which are managed.
+ </para>
+
<para>
This chapter describes how to create and manage roles.
More information about the effects of role privileges on various
--
2.30.2
>From 8e0fd522780311b116e17cb6b8814aa43a374277 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 1 Oct 2023 17:52:22 -0500
Subject: [PATCH v5 13/14] Hyperlink from CREATE FUNCTION reference page to
parallel safety page
Is is nice to have a link in the reference material to a full discussion.
---
doc/src/sgml/ref/create_function.sgml | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index 863d99d1fc..eb16e8adc0 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -429,7 +429,8 @@ CREATE [ OR REPLACE ] FUNCTION
<listitem>
<para><literal>PARALLEL UNSAFE</literal> indicates that the function
- can't be executed in parallel mode and the presence of such a
+ can't be executed in <link linkend="parallel-labeling">parallel
+ mode</link> and the presence of such a
function in an SQL statement forces a serial execution plan. This is
the default. <literal>PARALLEL RESTRICTED</literal> indicates that
the function can be executed in parallel mode, but the execution is
--
2.30.2
>From c5f9c0beb5710401dfe727ed4e97fd3ffb149247 Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <k...@karlpinc.com>
Date: Sun, 1 Oct 2023 18:06:54 -0500
Subject: [PATCH v5 14/14] Add index entries for parallel safety
Always nice to index things, and safety is important.
---
doc/src/sgml/parallel.sgml | 10 ++++++++++
doc/src/sgml/ref/create_function.sgml | 6 ++++++
2 files changed, 16 insertions(+)
diff --git a/doc/src/sgml/parallel.sgml b/doc/src/sgml/parallel.sgml
index 5acc9537d6..d523592b2a 100644
--- a/doc/src/sgml/parallel.sgml
+++ b/doc/src/sgml/parallel.sgml
@@ -523,6 +523,16 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
</listitem>
</itemizedlist>
+ <indexterm>
+ <primary>parallel safety</primary>
+ <secondary>functions</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>parallel safety</primary>
+ <secondary>aggregates</secondary>
+ </indexterm>
+
<sect2 id="parallel-labeling">
<title>Parallel Labeling for Functions and Aggregates</title>
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index eb16e8adc0..419e9b7284 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -428,6 +428,12 @@ CREATE [ OR REPLACE ] FUNCTION
<term><literal>PARALLEL</literal></term>
<listitem>
+
+ <indexterm>
+ <primary>parallel safety</primary>
+ <secondary>functions</secondary>
+ </indexterm>
+
<para><literal>PARALLEL UNSAFE</literal> indicates that the function
can't be executed in <link linkend="parallel-labeling">parallel
mode</link> and the presence of such a
--
2.30.2
