begriffs open source - ai-pg/blob - full-docs/txt/database-roles.txt

   1
   2 21.1. Database Roles #
   3
   4    Database roles are conceptually completely separate from operating
   5    system users. In practice it might be convenient to maintain a
   6    correspondence, but this is not required. Database roles are global
   7    across a database cluster installation (and not per individual
   8    database). To create a role use the CREATE ROLE SQL command:
   9 CREATE ROLE name;
  10
  11    name follows the rules for SQL identifiers: either unadorned without
  12    special characters, or double-quoted. (In practice, you will usually
  13    want to add additional options, such as LOGIN, to the command. More
  14    details appear below.) To remove an existing role, use the analogous
  15    DROP ROLE command:
  16 DROP ROLE name;
  17
  18    For convenience, the programs createuser and dropuser are provided as
  19    wrappers around these SQL commands that can be called from the shell
  20    command line:
  21 createuser name
  22 dropuser name
  23
  24    To determine the set of existing roles, examine the pg_roles system
  25    catalog, for example:
  26 SELECT rolname FROM pg_roles;
  27
  28    or to see just those capable of logging in:
  29 SELECT rolname FROM pg_roles WHERE rolcanlogin;
  30
  31    The psql program's \du meta-command is also useful for listing the
  32    existing roles.
  33
  34    In order to bootstrap the database system, a freshly initialized system
  35    always contains one predefined login-capable role. This role is always
  36    a “superuser”, and it will have the same name as the operating system
  37    user that initialized the database cluster with initdb unless a
  38    different name is specified. This role is often named postgres. In
  39    order to create more roles you first have to connect as this initial
  40    role.
  41
  42    Every connection to the database server is made using the name of some
  43    particular role, and this role determines the initial access privileges
  44    for commands issued in that connection. The role name to use for a
  45    particular database connection is indicated by the client that is
  46    initiating the connection request in an application-specific fashion.
  47    For example, the psql program uses the -U command line option to
  48    indicate the role to connect as. Many applications assume the name of
  49    the current operating system user by default (including createuser and
  50    psql). Therefore it is often convenient to maintain a naming
  51    correspondence between roles and operating system users.
  52
  53    The set of database roles a given client connection can connect as is
  54    determined by the client authentication setup, as explained in
  55    Chapter 20. (Thus, a client is not limited to connect as the role
  56    matching its operating system user, just as a person's login name need
  57    not match his or her real name.) Since the role identity determines the
  58    set of privileges available to a connected client, it is important to
  59    carefully configure privileges when setting up a multiuser environment.