On 09/19/2018 11:18 AM, Joe Conway wrote:
> On 09/19/2018 10:54 AM, Tom Lane wrote:
>> Joe Conway <m...@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
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>@&gt;</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}',

Attachment: signature.asc
Description: OpenPGP digital signature

Reply via email to