Skip to content

Commit c62dd80

Browse files
jconwayjconway
committed
Document aclitem functions and operators
aclitem functions and operators have been heretofore undocumented. Fix that. While at it, ensure the non-operator aclitem functions have pg_description strings. Does not seem worthwhile to back-patch. Author: Fabien Coelho, with pg_description from John Naylor, and significant refactoring and editorialization by me. Reviewed by: Tom Lane Discussion: https://postgr.es/m/flat/alpine.DEB.2.21.1808010825490.18204%40lancre
1 parent d18f667 commit c62dd80

File tree

3 files changed

+139
-5
lines changed

3 files changed

+139
-5
lines changed

‎doc/src/sgml/func.sgml‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15962,7 +15962,7 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
1596215962
</sect1>
1596315963

1596415964
<sect1 id="functions-info">
15965-
<title>System Information Functions</title>
15965+
<title>System Information Functions and Operators</title>
1596615966

1596715967
<para>
1596815968
<xref linkend="functions-info-session-table"/> shows several
@@ -16893,6 +16893,141 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
1689316893
be specified by name or by OID.
1689416894
</para>
1689516895

16896+
<para>
16897+
<xref linkend="functions-aclitem-fn-table"/> shows the operators
16898+
available for the <type>aclitem</type> type, which is the internal
16899+
representation of access privileges. An <type>aclitem</type> entry
16900+
describes the permissions of a grantee, whether they are grantable
16901+
or not, and which grantor granted them. For instance,
16902+
<literal>calvin=r*w/hobbes</literal> specifies that the role
16903+
<literal>calvin</literal> has the grantable privilege
16904+
<literal>SELECT</literal> (<literal>r*</literal>) and the non-grantable
16905+
privilege <literal>UPDATE</literal> (<literal>w</literal>), granted by
16906+
the role <literal>hobbes</literal>. An empty grantee stands for
16907+
<literal>PUBLIC</literal>.
16908+
</para>
16909+
16910+
<indexterm>
16911+
<primary>aclitem</primary>
16912+
</indexterm>
16913+
<indexterm>
16914+
<primary>acldefault</primary>
16915+
</indexterm>
16916+
<indexterm>
16917+
<primary>aclitemeq</primary>
16918+
</indexterm>
16919+
<indexterm>
16920+
<primary>aclcontains</primary>
16921+
</indexterm>
16922+
<indexterm>
16923+
<primary>aclexplode</primary>
16924+
</indexterm>
16925+
<indexterm>
16926+
<primary>makeaclitem</primary>
16927+
</indexterm>
16928+
16929+
<table id="functions-aclitem-op-table">
16930+
<title><type>aclitem</type> Operators</title>
16931+
<tgroup cols="4">
16932+
<thead>
16933+
<row>
16934+
<entry>Operator</entry>
16935+
<entry>Description</entry>
16936+
<entry>Example</entry>
16937+
<entry>Result</entry>
16938+
</row>
16939+
</thead>
16940+
<tbody>
16941+
16942+
<row>
16943+
<entry> <literal>=</literal> </entry>
16944+
<entry>equal</entry>
16945+
<entry><literal>'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem</literal></entry>
16946+
<entry><literal>f</literal></entry>
16947+
</row>
16948+
16949+
<row>
16950+
<entry> <literal>@&gt;</literal> </entry>
16951+
<entry>contains element</entry>
16952+
<entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*w/hobbes'::aclitem</literal></entry>
16953+
<entry><literal>t</literal></entry>
16954+
</row>
16955+
16956+
<row>
16957+
<entry> <literal>~</literal> </entry>
16958+
<entry>contains element</entry>
16959+
<entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*w/hobbes'::aclitem</literal></entry>
16960+
<entry><literal>t</literal></entry>
16961+
</row>
16962+
16963+
</tbody>
16964+
</tgroup>
16965+
</table>
16966+
16967+
<para>
16968+
<xref linkend="functions-aclitem-fn-table"/> shows some additional
16969+
functions to manage the <type>aclitem</type> type.
16970+
</para>
16971+
16972+
<table id="functions-aclitem-fn-table">
16973+
<title><type>aclitem</type> Functions</title>
16974+
<tgroup cols="3">
16975+
<thead>
16976+
<row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
16977+
</thead>
16978+
<tbody>
16979+
<row>
16980+
<entry><literal><function>acldefault</function>(<parameter>type</parameter>,
16981+
<parameter>ownerId</parameter>)</literal></entry>
16982+
<entry><type>aclitem[]</type></entry>
16983+
<entry>get the hardcoded default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
16984+
</row>
16985+
<row>
16986+
<entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry>
16987+
<entry><type>setof record</type></entry>
16988+
<entry>get <type>aclitem</type> array as tuples</entry>
16989+
</row>
16990+
<row>
16991+
<entry><literal><function>makeaclitem</function>(<parameter>grantee</parameter>, <parameter>grantor</parameter>, <parameter>privilege</parameter>, <parameter>grantable</parameter>)</literal></entry>
16992+
<entry><type>aclitem</type></entry>
16993+
<entry>build an <type>aclitem</type> from input</entry>
16994+
</row>
16995+
</tbody>
16996+
</tgroup>
16997+
</table>
16998+
16999+
<para>
17000+
<function>acldefault</function> returns the hardcoded default access privileges
17001+
for an object of <parameter>type</parameter> belonging to role <parameter>ownerId</parameter>.
17002+
Notice that these are used in the absence of any pg_default_acl
17003+
(<xref linkend="catalog-pg-default-acl"/>) entry. Default access privileges are described in
17004+
<xref linkend="sql-grant"/> and can be overwritten with
17005+
<xref linkend="sql-alterdefaultprivileges"/>. In other words, this function will return
17006+
results which may be misleading when the defaults have been overridden.
17007+
Type is a <type>CHAR</type>, use
17008+
'c' for <literal>COLUMN</literal>,
17009+
'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
17010+
's' for <literal>SEQUENCE</literal>,
17011+
'd' for <literal>DATABASE</literal>,
17012+
'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
17013+
'l' for <literal>LANGUAGE</literal>,
17014+
'L' for <literal>LARGE OBJECT</literal>,
17015+
'n' for <literal>SCHEMA</literal>,
17016+
't' for <literal>TABLESPACE</literal>,
17017+
'F' for <literal>FOREIGN DATA WRAPPER</literal>,
17018+
'S' for <literal>FOREIGN SERVER</literal>,
17019+
'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
17020+
</para>
17021+
17022+
<para>
17023+
<function>aclexplode</function> returns an <type>aclitem</type> array
17024+
as a set rows. Output columns are grantor <type>oid</type>,
17025+
grantee <type>oid</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
17026+
granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
17027+
and whether the prilivege is grantable as <type>boolean</type>.
17028+
<function>makeaclitem</function> performs the inverse operation.
17029+
</para>
17030+
1689617031
<para>
1689717032
<xref linkend="functions-info-schema-table"/> shows functions that
1689817033
determine whether a certain object is <firstterm>visible</firstterm> in the

‎src/backend/utils/adt/acl.c‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -855,8 +855,7 @@ acldefault(ObjectType objtype, Oid ownerId)
855855

856856
/*
857857
* SQL-accessible version of acldefault(). Hackish mapping from "char" type to
858-
* OBJECT_* values, but it's only used in the information schema, not
859-
* documented for general use.
858+
* OBJECT_* values.
860859
*/
861860
Datum
862861
acldefault_sql(PG_FUNCTION_ARGS)

‎src/include/catalog/pg_proc.dat‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2073,11 +2073,11 @@
20732073
{ oid => '1365', descr => 'make ACL item',
20742074
proname => 'makeaclitem', prorettype => 'aclitem',
20752075
proargtypes => 'oid oid text bool', prosrc => 'makeaclitem' },
2076-
{ oid => '3943', descr => 'TODO',
2076+
{ oid => '3943', descr => 'show hardwired default privileges, primarily for use by the information schema',
20772077
proname => 'acldefault', prorettype => '_aclitem', proargtypes => 'char oid',
20782078
prosrc => 'acldefault_sql' },
20792079
{ oid => '1689',
2080-
descr => 'convert ACL item array to table, for use by information schema',
2080+
descr => 'convert ACL item array to table, primarily for use by information schema',
20812081
proname => 'aclexplode', prorows => '10', proretset => 't',
20822082
provolatile => 's', prorettype => 'record', proargtypes => '_aclitem',
20832083
proallargtypes => '{_aclitem,oid,oid,text,bool}',

0 commit comments

Comments
 (0)