Create an ALTER DEFAULT PRIVILEGES command, which allows users to adjust

the privileges that will be applied to subsequently-created objects.

Such adjustments are always per owning role, and can be restricted to objects
created in particular schemas too.  A notable benefit is that users can
override the traditional default privilege settings, eg, the PUBLIC EXECUTE
privilege traditionally granted by default for functions.

Petr Jelinek

doc/src/sgml/catalogs.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.207 2009/09/22 23:43:37 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.208 2009/10/05 19:24:32 tgl Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -113,6 +113,11 @@
       <entry>databases within this database cluster</entry>
      </row>
 
+     <row>
+      <entry><link linkend="catalog-pg-default-acl"><structname>pg_default_acl</structname></link></entry>
+      <entry>default privileges for object types</entry>
+     </row>
+
      <row>
       <entry><link linkend="catalog-pg-depend"><structname>pg_depend</structname></link></entry>
       <entry>dependencies between database objects</entry>
@@ -2155,6 +2160,93 @@
  </sect1>
 
 
+ <sect1 id="catalog-pg-default-acl">
+  <title><structname>pg_default_acl</structname></title>
+
+  <indexterm zone="catalog-pg-default-acl">
+   <primary>pg_default_acl</primary>
+  </indexterm>
+
+  <para>
+   The catalog <structname>pg_default_acl</> stores initial
+   privileges to be assigned to newly created objects.
+  </para>
+
+  <table>
+   <title><structname>pg_default_acl</> Columns</title>
+
+   <tgroup cols="4">
+    <thead>
+     <row>
+      <entry>Name</entry>
+      <entry>Type</entry>
+      <entry>References</entry>
+      <entry>Description</entry>
+     </row>
+    </thead>
+
+    <tbody>
+     <row>
+      <entry><structfield>defaclrole</structfield></entry>
+      <entry><type>oid</type></entry>
+      <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry>
+      <entry>The OID of the role associated with this entry</entry>
+     </row>
+
+     <row>
+      <entry><structfield>defaclnamespace</structfield></entry>
+      <entry><type>oid</type></entry>
+      <entry><literal><link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.oid</literal></entry>
+      <entry>The OID of the namespace associated with this entry,
+       or 0 if none</entry>
+     </row>
+
+     <row>
+      <entry><structfield>defaclobjtype</structfield></entry>
+      <entry><type>char</type></entry>
+      <entry></entry>
+      <entry>
+       Type of object this entry is for:
+       <literal>r</> = relation (table, view),
+       <literal>S</> = sequence,
+       <literal>f</> = function
+      </entry>
+     </row>
+
+     <row>
+      <entry><structfield>defaclacl</structfield></entry>
+      <entry><type>aclitem[]</type></entry>
+      <entry></entry>
+      <entry>
+       Access privileges that this type of object should have on creation
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </table>
+
+  <para>
+   A <structname>pg_default_acl</> entry shows the initial privileges to
+   be assigned to an object belonging to the indicated user.  There are
+   currently two types of entry: <quote>global</> entries with
+   <structfield>defaclnamespace</> = 0, and <quote>per-schema</> entries
+   that reference a particular schema.  If a global entry is present then
+   it <emphasis>overrides</> the normal hard-wired default privileges
+   for the object type.  A per-schema entry, if present, represents privileges
+   to be <emphasis>added to</> the global or hard-wired default privileges.
+  </para>
+
+  <para>
+   Note that when an ACL entry in another catalog is NULL, it is taken
+   to represent the hard-wired default privileges for its object,
+   <emphasis>not</> whatever might be in <structname>pg_default_acl</>
+   at the moment.  <structname>pg_default_acl</> is only consulted during
+   object creation.
+  </para>
+
+ </sect1>
+
+
  <sect1 id="catalog-pg-depend">
   <title><structname>pg_depend</structname></title>
 

doc/src/sgml/ref/allfiles.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.75 2009/09/22 23:43:37 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.76 2009/10/05 19:24:33 tgl Exp $
 PostgreSQL documentation
 Complete list of usable sgml source files in this directory.
 -->
@@ -9,6 +9,7 @@ Complete list of usable sgml source files in this directory.
 <!entity alterAggregate     system "alter_aggregate.sgml">
 <!entity alterConversion    system "alter_conversion.sgml">
 <!entity alterDatabase      system "alter_database.sgml">
+<!entity alterDefaultPrivileges system "alter_default_privileges.sgml">
 <!entity alterDomain        system "alter_domain.sgml">
 <!entity alterForeignDataWrapper system "alter_foreign_data_wrapper.sgml">
 <!entity alterFunction      system "alter_function.sgml">

doc/src/sgml/ref/alter_default_privileges.sgml

@@ -0,0 +1,211 @@
+<!--
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_default_privileges.sgml,v 1.1 2009/10/05 19:24:33 tgl Exp $
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-ALTERDEFAULTPRIVILEGES">
+ <refmeta>
+  <refentrytitle id="SQL-ALTERDEFAULTPRIVILEGES-TITLE">ALTER DEFAULT PRIVILEGES</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>ALTER DEFAULT PRIVILEGES</refname>
+  <refpurpose>define default access privileges</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-alterdefaultprivileges">
+  <primary>ALTER DEFAULT PRIVILEGES</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+ALTER DEFAULT PRIVILEGES
+    [ FOR { ROLE | USER } <replaceable>target_role</replaceable> [, ...] ]
+    [ IN SCHEMA <replaceable>schema_name</replaceable> [, ...] ]
+    <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable>
+
+<phrase>where <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable> is one of:</phrase>
+
+GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
+    [,...] | ALL [ PRIVILEGES ] }
+    ON TABLE
+    TO { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { { USAGE | SELECT | UPDATE }
+    [,...] | ALL [ PRIVILEGES ] }
+    ON SEQUENCE
+    TO { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { EXECUTE | ALL [ PRIVILEGES ] }
+    ON FUNCTION
+    TO { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }
+    [,...] | ALL [ PRIVILEGES ] }
+    ON TABLE
+    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { { USAGE | SELECT | UPDATE }
+    [,...] | ALL [ PRIVILEGES ] }
+    ON SEQUENCE
+    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { EXECUTE | ALL [ PRIVILEGES ] }
+    ON FUNCTION
+    FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="sql-alterdefaultprivileges-description">
+  <title>Description</title>
+
+  <para>
+   <command>ALTER DEFAULT PRIVILEGES</> allows you to set the privileges
+   that will be applied to objects created in the future.  (It does not
+   affect privileges assigned to already-existing objects.)  Currently,
+   only the privileges for tables (including views), sequences, and
+   functions can be altered.
+  </para>
+
+  <para>
+   You can change default privileges only for objects that will be created by
+   yourself or by roles that you are a member of.  The privileges can be set
+   globally (i.e., for all objects created in the current database),
+   or just for objects created in specified schemas.  Default privileges
+   that are specified per-schema are added to whatever the global default
+   privileges are for the particular object type.
+  </para>
+
+  <para>
+   As explained under <xref linkend="sql-grant" endterm="sql-grant-title">,
+   the default privileges for any object type normally grant all grantable
+   permissions to the object owner, and may grant some privileges to
+   <literal>PUBLIC</> as well.  However, this behavior can be changed by
+   altering the global default privileges with
+   <command>ALTER DEFAULT PRIVILEGES</>.
+  </para>
+
+ <refsect2>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><replaceable>target_role</replaceable></term>
+    <listitem>
+     <para>
+      The name of an existing role of which the current role is a member.
+      If <literal>FOR ROLE</> is omitted, the current role is assumed.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable>schema_name</replaceable></term>
+    <listitem>
+     <para>
+      The name of an existing schema.  Each <replaceable>target_role</>
+      must have <literal>CREATE</> privileges for each specified schema.
+      If <literal>IN SCHEMA</> is omitted, the global default privileges
+      are altered.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable>role_name</replaceable></term>
+    <listitem>
+     <para>
+      The name of an existing role to grant or revoke privileges for.
+      This parameter, and all the other parameters in
+      <replaceable class="parameter">abbreviated_grant_or_revoke</>,
+      act as described under
+      <xref linkend="sql-grant" endterm="sql-grant-title"> or
+      <xref linkend="sql-revoke" endterm="sql-revoke-title">,
+      except that one is setting permissions for a whole class of objects
+      rather than specific named objects.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1 id="sql-alterdefaultprivileges-notes">
+  <title>Notes</title>
+
+  <para>
+   Use <xref linkend="app-psql">'s <command>\ddp</command> command
+   to obtain information about existing assignments of default privileges.
+   The meaning of the privilege values is the same as explained for
+   <command>\dp</command> under
+   <xref linkend="sql-grant" endterm="sql-grant-title">.
+  </para>
+
+  <para>
+   If you wish to drop a role that has had its global default privileges
+   altered, it is necessary to use <command>DROP OWNED BY</> first,
+   to get rid of the default privileges entry for the role.
+  </para>
+ </refsect1>
+
+ <refsect1 id="sql-alterdefaultprivileges-examples">
+  <title>Examples</title>
+
+  <para>
+   Grant SELECT privilege to everyone for all tables (and views) you
+   subsequently create in schema <literal>myschema</literal>, and allow
+   role <literal>webuser</> to INSERT into them too:
+
+<programlisting>
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT SELECT ON TABLE TO PUBLIC;
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT INSERT ON TABLE TO webuser;
+</programlisting>
+  </para>
+
+  <para>
+   Undo the above, so that subsequently-created tables won't have any
+   more permissions than normal:
+
+<programlisting>
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE SELECT ON TABLE FROM PUBLIC;
+ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLE FROM webuser;
+</programlisting>
+  </para>
+
+  <para>
+   Remove the public EXECUTE permission that is normally granted on functions,
+   for all functions subsequently created by role <literal>admin</>:
+
+<programlisting>
+ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTION FROM PUBLIC;
+</programlisting>
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   There is no <command>ALTER DEFAULT PRIVILEGES</command> statement in the SQL
+   standard.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
+   <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>

doc/src/sgml/ref/grant.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.77 2009/09/19 10:23:27 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.78 2009/10/05 19:24:34 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -80,14 +80,6 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
    they are different enough to be described separately.
   </para>
 
-  <para>
-   As of <productname>PostgreSQL</productname> 8.1, the concepts of users and
-   groups have been unified into a single kind of entity called a role.
-   It is therefore no longer necessary to use the keyword <literal>GROUP</>
-   to identify whether a grantee is a user or a group.  <literal>GROUP</>
-   is still allowed in the command, but it is a noise word.
-  </para>
-
  <refsect2 id="sql-grant-description-objects">
   <title>GRANT on Database Objects</title>
 
@@ -145,6 +137,9 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
    security, issue the <command>REVOKE</> in the same transaction that
    creates the object; then there is no window in which another user
    can use the object.)
+   Also, these initial default privilege settings can be changed using the
+   <xref linkend="sql-alterdefaultprivileges" endterm="sql-alterdefaultprivileges-title">
+   command.
   </para>
 
   <para>
@@ -388,6 +383,14 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace
     to revoke access privileges.
    </para>
 
+   <para>
+    Since <productname>PostgreSQL</productname> 8.1, the concepts of users and
+    groups have been unified into a single kind of entity called a role.
+    It is therefore no longer necessary to use the keyword <literal>GROUP</>
+    to identify whether a grantee is a user or a group.  <literal>GROUP</>
+    is still allowed in the command, but it is a noise word.
+   </para>
+
    <para>
     A user may perform <command>SELECT</>, <command>INSERT</>, etc. on a
     column if he holds that privilege for either the specific column or
@@ -518,8 +521,13 @@ GRANT SELECT (col1), UPDATE (col1) ON mytable TO miriam_rw;
     <command>REVOKE</> on an object
     will instantiate the default privileges (producing, for example,
     <literal>{miriam=arwdDxt/miriam}</>) and then modify them per the
-    specified request.  Entries are shown in <quote>Column access
+    specified request.  Similarly, entries are shown in <quote>Column access
     privileges</> only for columns with nondefault privileges.
+    (Note: for this purpose, <quote>default privileges</> always means the
+    built-in default privileges for the object's type.  An object whose
+    privileges have been affected by an <command>ALTER DEFAULT PRIVILEGES</>
+    command will always be shown with an explicit privilege entry that
+    includes the effects of the <command>ALTER</>.)
    </para>
 
    <para>
@@ -602,9 +610,10 @@ GRANT admins TO joe;
  <refsect1>
   <title>See Also</title>
 
-  <simpara>
-   <xref linkend="sql-revoke" endterm="sql-revoke-title">
-  </simpara>
+  <simplelist type="inline">
+   <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
+   <member><xref linkend="sql-alterdefaultprivileges" endterm="sql-alterdefaultprivileges-title"></member>
+  </simplelist>
  </refsect1>
 
 </refentry>

doc/src/sgml/ref/psql-ref.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.229 2009/08/11 12:02:58 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.230 2009/10/05 19:24:34 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -978,6 +978,29 @@ testdb=&gt;
       </varlistentry>
 
 
+      <varlistentry>
+        <term><literal>\ddp [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
+        <listitem>
+        <para>
+        Lists default access privilege settings.  An entry is shown for
+        each role (and schema, if applicable) for which the default
+        privilege settings have been changed from the built-in defaults.
+        If <replaceable class="parameter">pattern</replaceable> is
+        specified, only entries whose role name or schema name matches
+        the pattern are listed.
+        </para>
+
+        <para>
+        The <xref linkend="sql-alterdefaultprivileges"
+        endterm="sql-alterdefaultprivileges-title"> command is used to set
+        default access privileges.  The meaning of the
+        privilege display is explained under
+        <xref linkend="sql-grant" endterm="sql-grant-title">.
+        </para>
+        </listitem>
+      </varlistentry>
+
+
       <varlistentry>
         <term><literal>\dD[S] [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
         <listitem>
@@ -1142,8 +1165,8 @@ testdb=&gt;
         class="parameter">pattern</replaceable> is specified, only
         those roles whose names match the pattern are listed.
         (This command is now effectively the same as <literal>\du</literal>).
-        If the form <literal>\dg+</literal> is used, additional information 
-        is shown about each role, including the comment for each role.  
+        If the form <literal>\dg+</literal> is used, additional information
+        is shown about each role, including the comment for each role.
         </para>
         </listitem>
       </varlistentry>
@@ -1235,7 +1258,9 @@ testdb=&gt;
         <para>
         The <xref linkend="sql-grant" endterm="sql-grant-title"> and
         <xref linkend="sql-revoke" endterm="sql-revoke-title">
-        commands are used to set access privileges.
+        commands are used to set access privileges.  The meaning of the
+        privilege display is explained under
+        <xref linkend="sql-grant" endterm="sql-grant-title">.
         </para>
         </listitem>
       </varlistentry>
@@ -2045,12 +2070,6 @@ lo_import 152801
         specified, only tables,views and sequences whose names match the pattern are listed.
         </para>
 
-        <para>
-        The <xref linkend="sql-grant" endterm="sql-grant-title"> and
-        <xref linkend="sql-revoke" endterm="sql-revoke-title">
-        commands are used to set access privileges.
-        </para>
-
         <para>
         This is an alias for <command>\dp</command> (<quote>display
         privileges</quote>).

doc/src/sgml/reference.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.68 2009/09/22 23:43:37 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.69 2009/10/05 19:24:33 tgl Exp $ -->
 
 <part id="reference">
  <title>Reference</title>
@@ -37,6 +37,7 @@
    &alterAggregate;
    &alterConversion;
    &alterDatabase;
+   &alterDefaultPrivileges;
    &alterDomain;
    &alterForeignDataWrapper;
    &alterFunction;