raw/man7/grant.7

   1 .\\" auto-generated by docbook2man-spec $Revision: 1.1 $
   2 .TH "GRANT" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
   3 .SH NAME
   4 GRANT \- define access privileges
   5
   6 .SH SYNOPSIS
   7 .sp
   8 .nf
   9 GRANT { { SELECT | INSERT | UPDATE | DELETE | RULE | REFERENCES | TRIGGER }
  10     [,...] | ALL [ PRIVILEGES ] }
  11     ON [ TABLE ] \fItablename\fR [, ...]
  12     TO { \fIusername\fR | GROUP \fIgroupname\fR | PUBLIC } [, ...] [ WITH GRANT OPTION ]
  13
  14 GRANT { { CREATE | TEMPORARY | TEMP } [,...] | ALL [ PRIVILEGES ] }
  15     ON DATABASE \fIdbname\fR [, ...]
  16     TO { \fIusername\fR | GROUP \fIgroupname\fR | PUBLIC } [, ...] [ WITH GRANT OPTION ]
  17
  18 GRANT { EXECUTE | ALL [ PRIVILEGES ] }
  19     ON FUNCTION \fIfuncname\fR ([\fItype\fR, ...]) [, ...]
  20     TO { \fIusername\fR | GROUP \fIgroupname\fR | PUBLIC } [, ...] [ WITH GRANT OPTION ]
  21
  22 GRANT { USAGE | ALL [ PRIVILEGES ] }
  23     ON LANGUAGE \fIlangname\fR [, ...]
  24     TO { \fIusername\fR | GROUP \fIgroupname\fR | PUBLIC } [, ...] [ WITH GRANT OPTION ]
  25
  26 GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
  27     ON SCHEMA \fIschemaname\fR [, ...]
  28     TO { \fIusername\fR | GROUP \fIgroupname\fR | PUBLIC } [, ...] [ WITH GRANT OPTION ]
  29 .sp
  30 .fi
  31 .SH "DESCRIPTION"
  32 .PP
  33 The \fBGRANT\fR command gives specific privileges on
  34 an object (table, view, sequence, database, function, procedural language,
  35 or schema) to
  36 one or more users or groups of users. These privileges are added
  37 to those already granted, if any.
  38 .PP
  39 The key word PUBLIC indicates that the
  40 privileges are to be granted to all users, including those that may
  41 be created later. PUBLIC may be thought of as an
  42 implicitly defined group that always includes all users.
  43 Any particular user will have the sum
  44 of privileges granted directly to him, privileges granted to any group he
  45 is presently a member of, and privileges granted to
  46 PUBLIC.
  47 .PP
  48 If WITH GRANT OPTION is specified, the recipient
  49 of the privilege may in turn grant it to others. By default this
  50 is not allowed. Grant options can only be granted to individual
  51 users, not to groups or PUBLIC.
  52 .PP
  53 There is no need to grant privileges to the owner of an object
  54 (usually the user that created it),
  55 as the owner has all privileges by default. (The owner could,
  56 however, choose to revoke some of his own privileges for safety.)
  57 The right to drop an object, or to alter its definition in any way is
  58 not described by a grantable privilege; it is inherent in the owner,
  59 and cannot be granted or revoked. It is not possible for the owner's
  60 grant options to be revoked, either.
  61 .PP
  62 Depending on the type of object, the initial default privileges may
  63 include granting some privileges to PUBLIC.
  64 The default is no public access for tables and schemas;
  65 TEMP table creation privilege for databases;
  66 EXECUTE privilege for functions; and
  67 USAGE privilege for languages.
  68 The object owner may of course revoke these privileges. (For maximum
  69 security, issue the \fBREVOKE\fR in the same transaction that
  70 creates the object; then there is no window in which another user
  71 may use the object.)
  72 .PP
  73 The possible privileges are:
  74 .TP
  75 \fBSELECT\fR
  76 Allows SELECT [\fBselect\fR(7)] from any column of the
  77 specified table, view, or sequence. Also allows the use of
  78 COPY [\fBcopy\fR(7)] TO. For sequences, this
  79 privilege also allows the use of the \fBcurrval\fR function.
  80 .TP
  81 \fBINSERT\fR
  82 Allows INSERT [\fBinsert\fR(7)] of a new row into the
  83 specified table. Also allows COPY [\fBcopy\fR(7)] FROM.
  84 .TP
  85 \fBUPDATE\fR
  86 Allows UPDATE [\fBupdate\fR(7)] of any column of the
  87 specified table. SELECT ... FOR UPDATE
  88 also requires this privilege (besides the
  89 SELECT privilege). For sequences, this
  90 privilege allows the use of the \fBnextval\fR and
  91 \fBsetval\fR functions.
  92 .TP
  93 \fBDELETE\fR
  94 Allows DELETE [\fBdelete\fR(7)] of a row from the
  95 specified table.
  96 .TP
  97 \fBRULE\fR
  98 Allows the creation of a rule on the table/view. (See CREATE RULE [\fBcreate_rule\fR(7)] statement.)
  99 .TP
 100 \fBREFERENCES\fR
 101 To create a foreign key constraint, it is
 102 necessary to have this privilege on both the referencing and
 103 referenced tables.
 104 .TP
 105 \fBTRIGGER\fR
 106 Allows the creation of a trigger on the specified table. (See
 107 CREATE TRIGGER [\fBcreate_trigger\fR(7)] statement.)
 108 .TP
 109 \fBCREATE\fR
 110 For databases, allows new schemas to be created within the database.
 111
 112 For schemas, allows new objects to be created within the schema.
 113 To rename an existing object, you must own the object \fBand\fR
 114 have this privilege for the containing schema.
 115 .TP
 116 \fBTEMPORARY\fR
 117 .TP
 118 \fBTEMP\fR
 119 Allows temporary tables to be created while using the database.
 120 .TP
 121 \fBEXECUTE\fR
 122 Allows the use of the specified function and the use of any
 123 operators that are implemented on top of the function. This is
 124 the only type of privilege that is applicable to functions.
 125 (This syntax works for aggregate functions, as well.)
 126 .TP
 127 \fBUSAGE\fR
 128 For procedural languages, allows the use of the specified language for
 129 the creation of functions in that language. This is the only type
 130 of privilege that is applicable to procedural languages.
 131
 132 For schemas, allows access to objects contained in the specified
 133 schema (assuming that the objects' own privilege requirements are
 134 also met). Essentially this allows the grantee to ``look up''
 135 objects within the schema.
 136 .TP
 137 \fBALL PRIVILEGES\fR
 138 Grant all of the privileges applicable to the object at once.
 139 The PRIVILEGES key word is optional in
 140 PostgreSQL, though it is required by
 141 strict SQL.
 142 .PP
 143 The privileges required by other commands are listed on the
 144 reference page of the respective command.
 145 .SH "NOTES"
 146 .PP
 147 The REVOKE [\fBrevoke\fR(7)] command is used
 148 to revoke access privileges.
 149 .PP
 150 It should be noted that database superusers can access
 151 all objects regardless of object privilege settings. This
 152 is comparable to the rights of root in a Unix system.
 153 As with root, it's unwise to operate as a superuser
 154 except when absolutely necessary.
 155 .PP
 156 If a superuser chooses to issue a \fBGRANT\fR or \fBREVOKE\fR
 157 command, the command is performed as though it were issued by the
 158 owner of the affected object. In particular, privileges granted via
 159 such a command will appear to have been granted by the object owner.
 160 .PP
 161 Currently, to grant privileges in PostgreSQL
 162 to only a few columns, you must
 163 create a view having the desired columns and then grant privileges
 164 to that view.
 165 .PP
 166 Use \fBpsql\fR(1)'s \fB\\z\fR command
 167 to obtain information about existing privileges, for example:
 168 .sp
 169 .nf
 170 => \\z mytable
 171
 172         Access privileges for database "lusitania"
 173  Schema |  Table  |           Access privileges
 174 --------+---------+---------------------------------------
 175  public | mytable | {=r/postgres,miriam=arwdRxt/postgres,"group todos=arw/postgres"}
 176 (1 row)
 177 .sp
 178 .fi
 179 The entries shown by \fB\\z\fR are interpreted thus:
 180 .sp
 181 .nf
 182               =xxxx -- privileges granted to PUBLIC
 183          uname=xxxx -- privileges granted to a user
 184    group gname=xxxx -- privileges granted to a group
 185
 186                   r -- SELECT ("read")
 187                   w -- UPDATE ("write")
 188                   a -- INSERT ("append")
 189                   d -- DELETE
 190                   R -- RULE
 191                   x -- REFERENCES
 192                   t -- TRIGGER
 193                   X -- EXECUTE
 194                   U -- USAGE
 195                   C -- CREATE
 196                   T -- TEMPORARY
 197             arwdRxt -- ALL PRIVILEGES (for tables)
 198                   * -- grant option for preceding privilege
 199
 200               /yyyy -- user who granted this privilege
 201 .sp
 202 .fi
 203 The above example display would be seen by user miriam after
 204 creating table mytable and doing
 205 .sp
 206 .nf
 207 GRANT SELECT ON mytable TO PUBLIC;
 208 GRANT SELECT, UPDATE, INSERT ON mytable TO GROUP todos;
 209 .sp
 210 .fi
 211 .PP
 212 If the ``Access privileges'' column is empty for a given object,
 213 it means the object has default privileges (that is, its privileges column
 214 is null). Default privileges always include all privileges for the owner,
 215 and may include some privileges for PUBLIC depending on the
 216 object type, as explained above. The first \fBGRANT\fR or
 217 \fBREVOKE\fR on an object
 218 will instantiate the default privileges (producing, for example,
 219 {=,miriam=arwdRxt}) and then modify them per the specified request.
 220 .SH "EXAMPLES"
 221 .PP
 222 Grant insert privilege to all users on table films:
 223 .sp
 224 .nf
 225 GRANT INSERT ON films TO PUBLIC;
 226 .sp
 227 .fi
 228 .PP
 229 Grant all privileges to user manuel on view kinds:
 230 .sp
 231 .nf
 232 GRANT ALL PRIVILEGES ON kinds TO manuel;
 233 .sp
 234 .fi
 235 .SH "COMPATIBILITY"
 236 .PP
 237 According to the SQL standard, the PRIVILEGES
 238 key word in ALL PRIVILEGES is required. The
 239 SQL standard does not support setting the privileges on more than
 240 one object per command.
 241 .PP
 242 The SQL standard allows setting privileges for individual columns
 243 within a table:
 244 .sp
 245 .nf
 246 GRANT \fIprivileges\fR
 247     ON \fItable\fR [ ( \fIcolumn\fR [, ...] ) ] [, ...]
 248     TO { PUBLIC | \fIusername\fR [, ...] } [ WITH GRANT OPTION ]
 249 .sp
 250 .fi
 251 .PP
 252 The SQL standard provides for a USAGE privilege
 253 on other kinds of objects: character sets, collations,
 254 translations, domains.
 255 .PP
 256 The RULE privilege, and privileges on
 257 databases, schemas, languages, and sequences are
 258 PostgreSQL extensions.
 259 .SH "SEE ALSO"
 260 .PP
 261 REVOKE [\fBrevoke\fR(7)]