diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 94 | ||||
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_default_privileges.sgml | 211 | ||||
| -rw-r--r-- | doc/src/sgml/ref/grant.sgml | 35 | ||||
| -rw-r--r-- | doc/src/sgml/ref/psql-ref.sgml | 39 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 3 |
6 files changed, 359 insertions, 26 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index dd103573a5d..15dab71cc0d 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/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 --> @@ -114,6 +114,11 @@ </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> </row> @@ -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> diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 845033b6b66..c15579c5164 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/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"> diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml new file mode 100644 index 00000000000..b2054b17804 --- /dev/null +++ b/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> diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 4dddde27b91..2dcf4aa0f0b 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/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> @@ -389,6 +384,14 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </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 its whole table. Granting the privilege at the table level and then @@ -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> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index f60c3150e9f..e689d275cb4 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/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 --> @@ -979,6 +979,29 @@ testdb=> <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> <para> @@ -1142,8 +1165,8 @@ testdb=> 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=> <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> @@ -2046,12 +2071,6 @@ lo_import 152801 </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>). </para> diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 48f8040541d..0e72fc5475b 100644 --- a/doc/src/sgml/reference.sgml +++ b/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; |