doc - add missing documentation for "acldefault"
I couldn't find the documentation. Attached patch adds one.
Probably this function should have been named pg_*. Too late.
--
Fabien.
Attachments:
doc-acldefault-1.patchtext/plain; name=doc-acldefault-1.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index edc9be92a6..0e5f8b914b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -16398,6 +16398,12 @@ SET search_path TO <replaceable>schema</replaceable> <optional>, <replaceable>sc
</thead>
<tbody>
+ <row>
+ <entry><literal><function>acldefault</function>(<parameter>type</parameter>,
+ <parameter>oid</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>default hardcoded access privileges for an object belonging to <parameter>oid</parameter></entry>
+ </row>
<row>
<entry><literal><function>has_any_column_privilege</function>(<parameter>user</parameter>,
<parameter>table</parameter>,
@@ -16605,6 +16611,9 @@ SET search_path TO <replaceable>schema</replaceable> <optional>, <replaceable>sc
</tgroup>
</table>
+ <indexterm>
+ <primary>acldefault</primary>
+ </indexterm>
<indexterm>
<primary>has_any_column_privilege</primary>
</indexterm>
@@ -16648,6 +16657,27 @@ SET search_path TO <replaceable>schema</replaceable> <optional>, <replaceable>sc
<primary>row_security_active</primary>
</indexterm>
+ <para>
+ <function>acldefault</function> returns the hardcoded default access privileges
+ for an object of <parameter>type</parameter> belonging to role <parameter>oid</parameter>.
+ Type is a <type>CHAR</type>, use
+ 'c' for <literal>COLUMN</literal>,
+ 'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
+ 's' for <literal>SEQUENCE</literal>,
+ 'd' for <literal>DATABASE</literal>,
+ 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
+ 'l' for <literal>LANGUAGE</literal>,
+ 'L' for <literal>LARGE OBJECT</literal>,
+ 'n' for <literal>SCHEMA</literal>,
+ 't' for <literal>TABLESPACE</literal>,
+ 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
+ 'S' for <literal>FOREIGN SERVER</literal>,
+ 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
+ Default access permissions are described in
+ <xref linkend="sql-grant"/> and can be overwritten with
+ <xref linkend="sql-alterdefaultprivileges"/>.
+ </para>
+
<para>
<function>has_table_privilege</function> checks whether a user
can access a table in a particular way. The user can be
Fabien,
On 01.08.2018 15:28, Fabien COELHO wrote:
I couldn't find the documentation. Attached patch adds one.
Probably this function should have been named pg_*. Too late.
I think this is intentionally hidden function, like others started with
acl*.
postgres=# \df acl*
List of fun
�� Schema�� |��� Name���� | Result data type |
------------+-------------+------------------+----------------------------------
�pg_catalog | aclcontains | boolean��������� | aclitem[], aclitem
�pg_catalog | acldefault� | aclitem[]������� | "char", oid
�pg_catalog | aclexplode� | SETOF record���� | acl aclitem[], OUT
grantor oid, O
�pg_catalog | aclinsert�� | aclitem[]������� | aclitem[], aclitem
�pg_catalog | aclitemeq�� | boolean��������� | aclitem, aclitem
�pg_catalog | aclitemin�� | aclitem��������� | cstring
�pg_catalog | aclitemout� | cstring��������� | aclitem
�pg_catalog | aclremove�� | aclitem[]������� | aclitem[], aclitem
-----
Pavel Luzanov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
Hello Pavel,
I couldn't find the documentation. Attached patch adds one.
Probably this function should have been named pg_*. Too late.
I think this is intentionally hidden function, like others started with acl*.
Yep, I thought of that.
However, the point of having hidden and/or undocumented functions fails
me: they are hard/impossible to find if you do not know they exist from
the start, and if you ever find one you do not know what they do without
reading the source code in detail, eg to know what to give arguments to
get an answer.
So I assumed that it was more lazyness and could be remedied with a doc
patch for the one function I read. Maybe it would make sense to document
the others as well, which are more straightforward.
Also, that does not explain why they do not use a "pg_" prefix, which is
already a way of saying "this is an internal-purpose function". So I would
be in favor of prefixing them with pg_: as it is an undocumented feature,
there would not be a compatibility break, somehow:-)
postgres=# \df acl*
List of fun
�� Schema�� |��� Name���� | Result data type |
------------+-------------+------------------+----------------------------------
�pg_catalog | aclcontains | boolean��������� | aclitem[], aclitem
�pg_catalog | acldefault� | aclitem[]������� | "char", oid
�pg_catalog | aclexplode� | SETOF record���� | acl aclitem[], OUT grantor
oid, O
�pg_catalog | aclinsert�� | aclitem[]������� | aclitem[], aclitem
�pg_catalog | aclitemeq�� | boolean��������� | aclitem, aclitem
�pg_catalog | aclitemin�� | aclitem��������� | cstring
�pg_catalog | aclitemout� | cstring��������� | aclitem
�pg_catalog | aclremove�� | aclitem[]������� | aclitem[], aclitem
--
Fabien.
Hello Fabien,
However, the point of having hidden and/or undocumented functions
fails me: they are hard/impossible to find if you do not know they
exist from
the start, and if you ever find one you do not know what they do
without reading the source code in detail, eg to know what to give
arguments to get an answer.
At first, we must decide in which cases users will use them.
And I don't see such cases.
I must to know how to grant privileges, how to revoke them and how to
check existing priveleges.
All theese tasks documented in GRANT, REVOKE commands and system catalog
descriptions.
Your's patch from another thread closes the last hole - describing
default privileges in various psql commands.
-----
Pavel Luzanov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
On Wed, Aug 01, 2018 at 04:41:44PM +0300, Pavel Luzanov wrote:
postgres=# \df acl*
List of fun
�� Schema�� |��� Name���� | Result data type |
------------+-------------+------------------+----------------------------------
�pg_catalog | aclcontains | boolean��������� | aclitem[], aclitem
�pg_catalog | acldefault� | aclitem[]������� | "char", oid
�pg_catalog | aclexplode� | SETOF record���� | acl aclitem[], OUT grantor
oid, O
�pg_catalog | aclinsert�� | aclitem[]������� | aclitem[], aclitem
�pg_catalog | aclitemeq�� | boolean��������� | aclitem, aclitem
�pg_catalog | aclitemin�� | aclitem��������� | cstring
�pg_catalog | aclitemout� | cstring��������� | aclitem
�pg_catalog | aclremove�� | aclitem[]������� | aclitem[], aclitem
Some of them are definitely internal. For example, aclitemin and
aclitemout are input and output functions respectively of the aclitem
data type. I think they don't need to be documented and shouldn't have
"pg_" prefix as they was created to maintenance aclitem data type.
--
Arthur Zakirov
Postgres Professional: http://www.postgrespro.com
Russian Postgres Company
Hello,
However, the point of having hidden and/or undocumented functions fails me:
they are hard/impossible to find if you do not know they exist from
the start, and if you ever find one you do not know what they do without
reading the source code in detail, eg to know what to give arguments to get
an answer.
At first, we must decide in which cases users will use them. And I don't
see such cases. I must to know how to grant privileges, how to revoke
them and how to check existing priveleges. All theese tasks documented
in GRANT, REVOKE commands and system catalog descriptions.
These are end-user needs.
There are also other needs, such as devs. I see no reason to make the
developer work harder by not providing documentation about available
functions. Tom mention the "acldefault" function that I did not know
existed, and I have read the doc!
So I'm still favorable to documenting all functions:-)
Maybe there could be a special section about special/internal functions,
separate from functions which are more of interest to the end-user? But
for me this is already the purpose of the "System information" sections in
the documentation. Maybe there could be another sub-section about aclitem
related functions in the "System information" section for these.
Your's patch from another thread closes the last hole - describing default
privileges in various psql commands.
Yep.
--
Fabien.
postgres=# \df acl*
List of fun
�� Schema�� |��� Name���� | Result data type |
------------+-------------+------------------+----------------------------------
�pg_catalog | aclcontains | boolean��������� | aclitem[], aclitem
�pg_catalog | acldefault� | aclitem[]������� | "char", oid
�pg_catalog | aclexplode� | SETOF record���� | acl aclitem[], OUT grantor
oid, O
�pg_catalog | aclinsert�� | aclitem[]������� | aclitem[], aclitem
�pg_catalog | aclitemeq�� | boolean��������� | aclitem, aclitem
�pg_catalog | aclitemin�� | aclitem��������� | cstring
�pg_catalog | aclitemout� | cstring��������� | aclitem
�pg_catalog | aclremove�� | aclitem[]������� | aclitem[], aclitemSome of them are definitely internal. For example, aclitemin and
aclitemout are input and output functions respectively of the aclitem
data type. I think they don't need to be documented and shouldn't have
"pg_" prefix as they was created to maintenance aclitem data type.
Indeed, some are internal for managing the type itself. Maybe that
encompasses also "aclitemeq", not sure. I would see no harm in having them
documented though.
ISTM that acl{contains,default,explode,insert,remove} deserve a real doc.
--
Fabien.
Here is a version of the patch which documents briefly all aclitem-related
functions, in a separate table.
--
Fabien.
Attachments:
doc-acldefault-2.patchtext/plain; name=doc-acldefault-2.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index edc9be92a6..c81e5aa1b4 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -16829,6 +16829,151 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
be specified by name or by OID.
</para>
+ <para>
+ <xref linkend="functions-aclitem-table"/> shows functions to
+ manage the <type>aclitem</type> type, the internal representation of access
+ privileges.
+ An <type>aclitem</type> entry describes the permissions of a grantee,
+ whether they are grantable or not, and which grantor granted them.
+ For instance, <literal>calvin=r*w/hobbes</literal> tells that
+ role <literal>calvin</literal> has
+ grantable privilege <literal>SELECT</literal> (<literal>r*</literal>)
+ and non-grantable privilege <literal>UPDATE</literal> (<literal>w</literal>)
+ granted by role <literal>hobbes</literal>.
+ An empty grantee stands for <literal>PUBLIC</literal>.
+ </para>
+
+ <table id="functions-aclitem-table">
+ <title><type>aclitem</type> Management Functions</title>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal><function>aclcontains</function>(<parameter>acls</parameter>, <parameter>acl</parameter>)</literal></entry>
+ <entry><type>boolean</type></entry>
+ <entry>tell whether privilege <parameter>acl</parameter> is contained within <parameter>acls</parameter></entry>
+ </row>
+ <row>
+ <entry><literal><function>acldefault</function>(<parameter>type</parameter>,
+ <parameter>oid</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>default hardcoded access privileges for an object belonging to <parameter>oid</parameter></entry>
+ </row>
+ <row>
+ <entry><literal><function>aclexplode</function>(<parameter>acls</parameter>)</literal></entry>
+ <entry><type>setof record</type></entry>
+ <entry>show <type>aclitem</type> array <parameter>acls</parameter> as tuples</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclinsert</function>(<parameter>acls</parameter>, <parameter>acl</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>add <parameter>acl</parameter> to <parameter>acls</parameter></entry>
+ </row>
+ <row>
+ <entry><literal><function>aclitemeq</function>(<parameter>acl1</parameter>, <parameter>acl2</parameter>)</literal></entry>
+ <entry><type>boolean</type></entry>
+ <entry>tell whether two <type>aclitem</type>s are equal</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclitemin</function>(<parameter>cstring</parameter>)</literal></entry>
+ <entry><type>aclitem</type></entry>
+ <entry>internal <type>aclitem</type> type input function</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclitemout</function>(<parameter>acl</parameter>)</literal></entry>
+ <entry><type>cstring</type></entry>
+ <entry>internal <type>aclitem</type> type output function</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclremove</function>(<parameter>acls</parameter>, <parameter>acl</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>remove <parameter>acl</parameter> from <parameter>acls</parameter></entry>
+ </row>
+ <row>
+ <entry><literal><function>hash_aclitem</function>(<parameter>acl</parameter>)</literal></entry>
+ <entry><type>int</type></entry>
+ <entry>internal <type>aclitem</type> hashing function</entry>
+ </row>
+ <row>
+ <entry><literal><function>makeaclitem</function>(<parameter>grantee</parameter>, <parameter>grantor</parameter>, <parameter>privilege</parameter>, <parameter>grantable</parameter>)</literal></entry>
+ <entry><type>aclitem</type></entry>
+ <entry>build an <type>aclitem</type> from input</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <indexterm>
+ <primary>aclitem</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclcontains</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclinsert</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclremove</primary>
+ </indexterm>
+ <indexterm>
+ <primary>acldefault</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclexplode</primary>
+ </indexterm>
+ <indexterm>
+ <primary>makeaclitem</primary>
+ </indexterm>
+
+ <para>
+ <function>acldefault</function> returns the hardcoded default access privileges
+ for an object of <parameter>type</parameter> belonging to role <parameter>oid</parameter>.
+ Type is a <type>CHAR</type>, use
+ 'c' for <literal>COLUMN</literal>,
+ 'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
+ 's' for <literal>SEQUENCE</literal>,
+ 'd' for <literal>DATABASE</literal>,
+ 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
+ 'l' for <literal>LANGUAGE</literal>,
+ 'L' for <literal>LARGE OBJECT</literal>,
+ 'n' for <literal>SCHEMA</literal>,
+ 't' for <literal>TABLESPACE</literal>,
+ 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
+ 'S' for <literal>FOREIGN SERVER</literal>,
+ 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
+ Default access privileges are described in
+ <xref linkend="sql-grant"/> and can be overwritten with
+ <xref linkend="sql-alterdefaultprivileges"/>.
+ </para>
+
+ <para>
+ <function>aclexplode</function> shows a set of record describing
+ <type>aclitem</type> array <parameter>acls</parameter>.
+ Output columns are grantor <type>oid</type>,
+ grantee <type>OID</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
+ granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
+ and whether the prilivege is grantable as <type>boolean</type>.
+ <function>makeaclitem</function> performs the inverse operation.
+ </para>
+
+ <para>
+ <function>aclinsert</function>, <function>aclremove</function> and
+ <function>aclcontains</function> allow to insert/remove/check whether
+ a privilege described by an <type>aclitem</type>
+ into/from/is contained by an array of <type>aclitem</type>.
+ </para>
+
+ <para>
+ <function>aclitemin</function>,
+ <function>aclitemout</function>,
+ <function>aclitemeq</function> and
+ <function>hash_aclitem</function>
+ are internal functions to input, output, compare and hash
+ an <type>aclitem</type>.
+ </para>
+
<para>
<xref linkend="functions-info-schema-table"/> shows functions that
determine whether a certain object is <firstterm>visible</firstterm> in the
On 08/03/2018 09:04 AM, Fabien COELHO wrote:
Here is a version of the patch which documents briefly all aclitem-related
functions, in a separate table.
I claimed this patch for review and commit. Comments:
---
* There is a comment in src/backend/utils/adt/acl.c noting that
acldefault is "not documented for general use" which needs adjustment
* It makes no sense to me to document purely internal functions, e.g.
aclitemin/out. If we are going to do that we should do it universally,
which is not true currently, and IMHO makes no sense anyway.
* I do believe aclitemeq() has utility outside internal purposes.
* The <indexterm> section is incomplete
* Interestingly (since that is what started this thread apparently) I
found myself questioning whether acldefault() is really worth
documenting since the result will be misleading if the defaults have
been altered via SQL.
---
Attached patch addresses those items and does a bit of reordering and
editorialization. If there are no objections I will commit it this way
in a day or two.
Thanks,
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development
Attachments:
doc-acldefault-jec01.patchtext/x-patch; name=doc-acldefault-jec01.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4331beb..cea674e 100644
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
*************** SELECT has_function_privilege('joeuser',
*** 16893,16898 ****
--- 16893,17032 ----
be specified by name or by OID.
</para>
+ <para>
+ <xref linkend="functions-aclitem-table"/> shows functions to
+ manage the <type>aclitem</type> type, the internal representation of access
+ privileges.
+ An <type>aclitem</type> entry describes the permissions of a grantee,
+ whether they are grantable or not, and which grantor granted them.
+ For instance, <literal>calvin=r*w/hobbes</literal> tells that
+ role <literal>calvin</literal> has
+ grantable privilege <literal>SELECT</literal> (<literal>r*</literal>)
+ and non-grantable privilege <literal>UPDATE</literal> (<literal>w</literal>)
+ granted by role <literal>hobbes</literal>.
+ An empty grantee stands for <literal>PUBLIC</literal>.
+ </para>
+
+ <table id="functions-aclitem-table">
+ <title><type>aclitem</type> Management Functions</title>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal><function>acldefault</function>(<parameter>type</parameter>,
+ <parameter>ownerId</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>get the hardcoded default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
+ </row>
+ <row>
+ <entry><literal><function>aclinsert</function>(<parameter>aclitem[]</parameter>, <parameter>aclitem</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>add element <parameter>aclitem</parameter> to <parameter>aclitem[]</parameter> array</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclremove</function>(<parameter>aclitem[]</parameter>, <parameter>aclitem</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>remove element <parameter>aclitem</parameter> from <parameter>aclitem[]</parameter> array</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclitemeq</function>(<parameter>aclitem1</parameter>, <parameter>aclitem2</parameter>)</literal></entry>
+ <entry><type>boolean</type></entry>
+ <entry>test whether two <type>aclitem</type> elements are equal</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclcontains</function>(<parameter>aclitem[]</parameter>, <parameter>aclitem</parameter>)</literal></entry>
+ <entry><type>boolean</type></entry>
+ <entry>test whether element <parameter>aclitem</parameter> is contained within <parameter>aclitem[]</parameter> array</entry>
+ </row>
+ <row>
+ <entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry>
+ <entry><type>setof record</type></entry>
+ <entry>get <type>aclitem</type> array as tuples</entry>
+ </row>
+ <row>
+ <entry><literal><function>makeaclitem</function>(<parameter>grantee</parameter>, <parameter>grantor</parameter>, <parameter>privilege</parameter>, <parameter>grantable</parameter>)</literal></entry>
+ <entry><type>aclitem</type></entry>
+ <entry>build an <type>aclitem</type> from input</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <indexterm>
+ <primary>aclitem</primary>
+ </indexterm>
+ <indexterm>
+ <primary>acldefault</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclinsert</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclremove</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclitemeq</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclcontains</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclexplode</primary>
+ </indexterm>
+ <indexterm>
+ <primary>makeaclitem</primary>
+ </indexterm>
+
+ <para>
+ <function>acldefault</function> returns the hardcoded default access privileges
+ for an object of <parameter>type</parameter> belonging to role <parameter>ownerId</parameter>.
+ Notice that these are used in the absence of any pg_default_acl
+ (<xref linkend="catalog-pg-default-acl"/>) entry. Default access privileges are described in
+ <xref linkend="sql-grant"/> and can be overwritten with
+ <xref linkend="sql-alterdefaultprivileges"/>. In other words, this function will return
+ results which may be misleading when the defaults have been overridden.
+ Type is a <type>CHAR</type>, use
+ 'c' for <literal>COLUMN</literal>,
+ 'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
+ 's' for <literal>SEQUENCE</literal>,
+ 'd' for <literal>DATABASE</literal>,
+ 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
+ 'l' for <literal>LANGUAGE</literal>,
+ 'L' for <literal>LARGE OBJECT</literal>,
+ 'n' for <literal>SCHEMA</literal>,
+ 't' for <literal>TABLESPACE</literal>,
+ 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
+ 'S' for <literal>FOREIGN SERVER</literal>,
+ 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
+ </para>
+
+ <para>
+ <function>aclinsert</function> and <function>aclremove</function>
+ allow to insertion/removal of a privilege described by an
+ <type>aclitem</type> into/from an array of <type>aclitem</type>.
+ </para>
+
+ <para>
+ <function>aclitemeq</function> checks for equality of two
+ <type>aclitem</type> elements.
+ </para>
+
+ <para>
+ <function>aclcontains</function> checks if an <type>aclitem</type>
+ element is present in an array of <type>aclitem</type>.
+ </para>
+
+ <para>
+ <function>aclexplode</function> returns an <type>aclitem</type> array
+ as a set rows. Output columns are grantor <type>oid</type>,
+ grantee <type>oid</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
+ granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
+ and whether the prilivege is grantable as <type>boolean</type>.
+ <function>makeaclitem</function> performs the inverse operation.
+ </para>
+
<para>
<xref linkend="functions-info-schema-table"/> shows functions that
determine whether a certain object is <firstterm>visible</firstterm> in the
diff --git a/src/backend/utils/adt/acl.c b/src/backend/utils/adt/acl.c
index a45e093..d5285e2 100644
*** a/src/backend/utils/adt/acl.c
--- b/src/backend/utils/adt/acl.c
*************** acldefault(ObjectType objtype, Oid owner
*** 855,862 ****
/*
* SQL-accessible version of acldefault(). Hackish mapping from "char" type to
! * OBJECT_* values, but it's only used in the information schema, not
! * documented for general use.
*/
Datum
acldefault_sql(PG_FUNCTION_ARGS)
--- 855,861 ----
/*
* SQL-accessible version of acldefault(). Hackish mapping from "char" type to
! * OBJECT_* values.
*/
Datum
acldefault_sql(PG_FUNCTION_ARGS)
Joe Conway <mail@joeconway.com> writes:
* I do believe aclitemeq() has utility outside internal purposes.
Our normal policy is that we do not document functions that are meant to
be invoked through operators. The \df output saying that is sufficient:
# \df+ aclitemeq
List of functions
Schema | Name | Result data type | Argument data types | Type | Volatility | Parallel | Owner | Security | Access privileges | Language | Source code | Description
------------+-----------+------------------+---------------------+------+------------+----------+----------+----------+-------------------+----------+-------------+------------------------------
pg_catalog | aclitemeq | boolean | aclitem, aclitem | func | immutable | safe | postgres | invoker | | internal | aclitem_eq | implementation of = operator
(1 row)
I would strongly object to ignoring that policy in just one place.
Actually, it appears that most of these functions have associated
operators:
# select oid::regoperator, oprcode from pg_operator where oprright = 'aclitem'::regtype;
oid | oprcode
-----------------------+-------------
+(aclitem[],aclitem) | aclinsert
-(aclitem[],aclitem) | aclremove
@>(aclitem[],aclitem) | aclcontains
=(aclitem,aclitem) | aclitemeq
~(aclitem[],aclitem) | aclcontains
(5 rows)
So maybe what we really need is a table of operators not functions.
However, I don't object to documenting any function that has its
own pg_description string.
regards, tom lane
On 09/19/2018 10:54 AM, Tom Lane wrote:
Joe Conway <mail@joeconway.com> writes:
* I do believe aclitemeq() has utility outside internal purposes.
Our normal policy is that we do not document functions that are meant to
be invoked through operators. The \df output saying that is sufficient:
<snip>
I would strongly object to ignoring that policy in just one place.
Ok, fair enough.
Actually, it appears that most of these functions have associated
operators:# select oid::regoperator, oprcode from pg_operator where oprright = 'aclitem'::regtype;
oid | oprcode
-----------------------+-------------
+(aclitem[],aclitem) | aclinsert
-(aclitem[],aclitem) | aclremove
@>(aclitem[],aclitem) | aclcontains
=(aclitem,aclitem) | aclitemeq
~(aclitem[],aclitem) | aclcontains
(5 rows)So maybe what we really need is a table of operators not functions.
Good idea -- I will take a look at that.
However, I don't object to documenting any function that has its
own pg_description string.
Ok.
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development
Hello,
Our normal policy is that we do not document functions that are meant to
be invoked through operators. The \df output saying that is sufficient:
The output of \df is one thing, but I was looking at pg online
documentation and hoping to find things as well.
\dfS returns nearly 3000 results, it is not really pratical unless you
already know what you are looking for, eg the name of the function...
I would strongly object to ignoring that policy in just one place.
Ok, fair enough.
Actually, it appears that most of these functions have associated
operators:# select oid::regoperator, oprcode from pg_operator where oprright = 'aclitem'::regtype;
oid | oprcode
-----------------------+-------------
+(aclitem[],aclitem) | aclinsert
-(aclitem[],aclitem) | aclremove
@>(aclitem[],aclitem) | aclcontains
=(aclitem,aclitem) | aclitemeq
~(aclitem[],aclitem) | aclcontains
(5 rows)So maybe what we really need is a table of operators not functions.
Good idea -- I will take a look at that.
My initial complaint is that I did not know that there was an "acldefault"
function while I was looking for that kind of thing. ISTM that this one
should be kept explicitely in the doc.
I'm okay with documenting operators instead of the basic undelying
functions and skipping type management (in/out) functions, though.
--
Fabien.
On 9/19/18, Tom Lane <tgl@sss.pgh.pa.us> wrote:
However, I don't object to documenting any function that has its
own pg_description string.
Speaking of, that description string seems to have been neglected.
I've attached a remedy for that.
-John Naylor
Attachments:
acldefault-description-string.patchtext/x-patch; charset=US-ASCII; name=acldefault-description-string.patchDownload
diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 860571440a..6b7088b9ce 100644
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -2073,7 +2073,7 @@
{ oid => '1365', descr => 'make ACL item',
proname => 'makeaclitem', prorettype => 'aclitem',
proargtypes => 'oid oid text bool', prosrc => 'makeaclitem' },
-{ oid => '3943', descr => 'TODO',
+{ oid => '3943', descr => 'show default privileges, for use by the information schema',
proname => 'acldefault', prorettype => '_aclitem', proargtypes => 'char oid',
prosrc => 'acldefault_sql' },
{ oid => '1689',
On 09/19/2018 12:30 PM, John Naylor wrote:
On 9/19/18, Tom Lane <tgl@sss.pgh.pa.us> wrote:
However, I don't object to documenting any function that has its
own pg_description string.Speaking of, that description string seems to have been neglected.
I've attached a remedy for that.
Thanks, will take care of it.
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development
On 09/19/2018 11:18 AM, Joe Conway wrote:
On 09/19/2018 10:54 AM, Tom Lane wrote:
Joe Conway <mail@joeconway.com> writes:
* I do believe aclitemeq() has utility outside internal purposes.
Our normal policy is that we do not document functions that are meant to
be invoked through operators. The \df output saying that is sufficient:<snip>
I would strongly object to ignoring that policy in just one place.
Ok, fair enough.
Actually, it appears that most of these functions have associated
operators:# select oid::regoperator, oprcode from pg_operator where oprright = 'aclitem'::regtype;
oid | oprcode
-----------------------+-------------
+(aclitem[],aclitem) | aclinsert
-(aclitem[],aclitem) | aclremove
@>(aclitem[],aclitem) | aclcontains
=(aclitem,aclitem) | aclitemeq
~(aclitem[],aclitem) | aclcontains
(5 rows)So maybe what we really need is a table of operators not functions.
Good idea -- I will take a look at that.
However, I don't object to documenting any function that has its
own pg_description string.
Ok, so the attached version refactors/splits the group into two tables
-- operators and functions.
It drops aclinsert and aclremove entirely due to the fact that they no
longer do anything useful, to wit:
-----
Datum
aclinsert(PG_FUNCTION_ARGS)
{
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
errmsg("aclinsert is no longer supported")));
PG_RETURN_NULL(); /* keep compiler quiet */
}
Datum
aclremove(PG_FUNCTION_ARGS)
{
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
errmsg("aclremove is no longer supported")));
PG_RETURN_NULL(); /* keep compiler quiet */
}
-----
I also included John Naylor's patch with some minor editorialization.
Any further comments or complaints?
Thanks,
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development
Attachments:
doc-acldefault-jec02.patchtext/x-patch; name=doc-acldefault-jec02.patchDownload
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4331beb..8ebb1bf 100644
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
*************** SELECT * FROM pg_ls_dir('.') WITH ORDINA
*** 15962,15968 ****
</sect1>
<sect1 id="functions-info">
! <title>System Information Functions</title>
<para>
<xref linkend="functions-info-session-table"/> shows several
--- 15962,15968 ----
</sect1>
<sect1 id="functions-info">
! <title>System Information Functions and Operators</title>
<para>
<xref linkend="functions-info-session-table"/> shows several
*************** SELECT has_function_privilege('joeuser',
*** 16894,16899 ****
--- 16894,17034 ----
</para>
<para>
+ <xref linkend="functions-aclitem-fn-table"/> shows the operators
+ available for the <type>aclitem</type> type, which is the internal
+ representation of access privileges. An <type>aclitem</type> entry
+ describes the permissions of a grantee, whether they are grantable
+ or not, and which grantor granted them. For instance,
+ <literal>calvin=r*w/hobbes</literal> specifies that the role
+ <literal>calvin</literal> has the grantable privilege
+ <literal>SELECT</literal> (<literal>r*</literal>) and the non-grantable
+ privilege <literal>UPDATE</literal> (<literal>w</literal>), granted by
+ the role <literal>hobbes</literal>. An empty grantee stands for
+ <literal>PUBLIC</literal>.
+ </para>
+
+ <indexterm>
+ <primary>aclitem</primary>
+ </indexterm>
+ <indexterm>
+ <primary>acldefault</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclitemeq</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclcontains</primary>
+ </indexterm>
+ <indexterm>
+ <primary>aclexplode</primary>
+ </indexterm>
+ <indexterm>
+ <primary>makeaclitem</primary>
+ </indexterm>
+
+ <table id="functions-aclitem-op-table">
+ <title><type>aclitem</type> Operators</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Operator</entry>
+ <entry>Description</entry>
+ <entry>Example</entry>
+ <entry>Result</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ <row>
+ <entry> <literal>=</literal> </entry>
+ <entry>equal</entry>
+ <entry><literal>'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem</literal></entry>
+ <entry><literal>f</literal></entry>
+ </row>
+
+ <row>
+ <entry> <literal>@></literal> </entry>
+ <entry>contains element</entry>
+ <entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*w/hobbes'::aclitem</literal></entry>
+ <entry><literal>t</literal></entry>
+ </row>
+
+ <row>
+ <entry> <literal>~</literal> </entry>
+ <entry>contains element</entry>
+ <entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*w/hobbes'::aclitem</literal></entry>
+ <entry><literal>t</literal></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <xref linkend="functions-aclitem-fn-table"/> shows some additional
+ functions to manage the <type>aclitem</type> type.
+ </para>
+
+ <table id="functions-aclitem-fn-table">
+ <title><type>aclitem</type> Functions</title>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal><function>acldefault</function>(<parameter>type</parameter>,
+ <parameter>ownerId</parameter>)</literal></entry>
+ <entry><type>aclitem[]</type></entry>
+ <entry>get the hardcoded default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
+ </row>
+ <row>
+ <entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry>
+ <entry><type>setof record</type></entry>
+ <entry>get <type>aclitem</type> array as tuples</entry>
+ </row>
+ <row>
+ <entry><literal><function>makeaclitem</function>(<parameter>grantee</parameter>, <parameter>grantor</parameter>, <parameter>privilege</parameter>, <parameter>grantable</parameter>)</literal></entry>
+ <entry><type>aclitem</type></entry>
+ <entry>build an <type>aclitem</type> from input</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <function>acldefault</function> returns the hardcoded default access privileges
+ for an object of <parameter>type</parameter> belonging to role <parameter>ownerId</parameter>.
+ Notice that these are used in the absence of any pg_default_acl
+ (<xref linkend="catalog-pg-default-acl"/>) entry. Default access privileges are described in
+ <xref linkend="sql-grant"/> and can be overwritten with
+ <xref linkend="sql-alterdefaultprivileges"/>. In other words, this function will return
+ results which may be misleading when the defaults have been overridden.
+ Type is a <type>CHAR</type>, use
+ 'c' for <literal>COLUMN</literal>,
+ 'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
+ 's' for <literal>SEQUENCE</literal>,
+ 'd' for <literal>DATABASE</literal>,
+ 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
+ 'l' for <literal>LANGUAGE</literal>,
+ 'L' for <literal>LARGE OBJECT</literal>,
+ 'n' for <literal>SCHEMA</literal>,
+ 't' for <literal>TABLESPACE</literal>,
+ 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
+ 'S' for <literal>FOREIGN SERVER</literal>,
+ 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
+ </para>
+
+ <para>
+ <function>aclexplode</function> returns an <type>aclitem</type> array
+ as a set rows. Output columns are grantor <type>oid</type>,
+ grantee <type>oid</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
+ granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
+ and whether the prilivege is grantable as <type>boolean</type>.
+ <function>makeaclitem</function> performs the inverse operation.
+ </para>
+
+ <para>
<xref linkend="functions-info-schema-table"/> shows functions that
determine whether a certain object is <firstterm>visible</firstterm> in the
current schema search path.
diff --git a/src/backend/utils/adt/acl.c b/src/backend/utils/adt/acl.c
index a45e093..d5285e2 100644
*** a/src/backend/utils/adt/acl.c
--- b/src/backend/utils/adt/acl.c
*************** acldefault(ObjectType objtype, Oid owner
*** 855,862 ****
/*
* SQL-accessible version of acldefault(). Hackish mapping from "char" type to
! * OBJECT_* values, but it's only used in the information schema, not
! * documented for general use.
*/
Datum
acldefault_sql(PG_FUNCTION_ARGS)
--- 855,861 ----
/*
* SQL-accessible version of acldefault(). Hackish mapping from "char" type to
! * OBJECT_* values.
*/
Datum
acldefault_sql(PG_FUNCTION_ARGS)
diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 8605714..8e4145f 100644
*** a/src/include/catalog/pg_proc.dat
--- b/src/include/catalog/pg_proc.dat
***************
*** 2073,2083 ****
{ oid => '1365', descr => 'make ACL item',
proname => 'makeaclitem', prorettype => 'aclitem',
proargtypes => 'oid oid text bool', prosrc => 'makeaclitem' },
! { oid => '3943', descr => 'TODO',
proname => 'acldefault', prorettype => '_aclitem', proargtypes => 'char oid',
prosrc => 'acldefault_sql' },
{ oid => '1689',
! descr => 'convert ACL item array to table, for use by information schema',
proname => 'aclexplode', prorows => '10', proretset => 't',
provolatile => 's', prorettype => 'record', proargtypes => '_aclitem',
proallargtypes => '{_aclitem,oid,oid,text,bool}',
--- 2073,2083 ----
{ oid => '1365', descr => 'make ACL item',
proname => 'makeaclitem', prorettype => 'aclitem',
proargtypes => 'oid oid text bool', prosrc => 'makeaclitem' },
! { oid => '3943', descr => 'show hardwired default privileges, primarily for use by the information schema',
proname => 'acldefault', prorettype => '_aclitem', proargtypes => 'char oid',
prosrc => 'acldefault_sql' },
{ oid => '1689',
! descr => 'convert ACL item array to table, primarily for use by information schema',
proname => 'aclexplode', prorows => '10', proretset => 't',
provolatile => 's', prorettype => 'record', proargtypes => '_aclitem',
proallargtypes => '{_aclitem,oid,oid,text,bool}',
On 09/21/2018 01:51 PM, Joe Conway wrote:
On 09/19/2018 11:18 AM, Joe Conway wrote:
On 09/19/2018 10:54 AM, Tom Lane wrote:
So maybe what we really need is a table of operators not functions.
Good idea -- I will take a look at that.
However, I don't object to documenting any function that has its
own pg_description string.Ok, so the attached version refactors/splits the group into two tables
-- operators and functions.
<snip>
I also included John Naylor's patch with some minor editorialization.
Any further comments or complaints?
Having seen none, committed/pushed. This did not seem worth
back-patching, so I only pushed to master.
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development
Joe Conway <mail@joeconway.com> writes:
Having seen none, committed/pushed. This did not seem worth
back-patching, so I only pushed to master.
I don't see anything on gitmaster?
regards, tom lane
On 09/24/2018 10:01 AM, Tom Lane wrote:
Joe Conway <mail@joeconway.com> writes:
Having seen none, committed/pushed. This did not seem worth
back-patching, so I only pushed to master.I don't see anything on gitmaster?
Hmm, yes, interesting -- I must of messed up my local git repo somehow.
Will try again.
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development
On 09/24/2018 10:09 AM, Joe Conway wrote:
On 09/24/2018 10:01 AM, Tom Lane wrote:
Joe Conway <mail@joeconway.com> writes:
Having seen none, committed/pushed. This did not seem worth
back-patching, so I only pushed to master.I don't see anything on gitmaster?
Hmm, yes, interesting -- I must of messed up my local git repo somehow.
Will try again.
This time it seems to have worked. Sorry for the noise earlier :-/
Joe
--
Crunchy Data - http://crunchydata.com
PostgreSQL Support for Secure Enterprises
Consulting, Training, & Open Source Development