PostgreSQL 16 文档: CREATE ROLE

CREATE ROLE
上一个	向上	SQL 命令	主页	下一个

CREATE ROLE

CREATE ROLE — 定义新的数据库角色

语法

CREATE ROLE name [ [ WITH ] option [ ... ] ]

where option can be:

      SUPERUSER | NOSUPERUSER
    | CREATEDB | NOCREATEDB
    | CREATEROLE | NOCREATEROLE
    | INHERIT | NOINHERIT
    | LOGIN | NOLOGIN
    | REPLICATION | NOREPLICATION
    | BYPASSRLS | NOBYPASSRLS
    | CONNECTION LIMIT connlimit
    | [ ENCRYPTED ] PASSWORD 'password' | PASSWORD NULL
    | VALID UNTIL 'timestamp'
    | IN ROLE role_name [, ...]
    | IN GROUP role_name [, ...]
    | ROLE role_name [, ...]
    | ADMIN role_name [, ...]
    | USER role_name [, ...]
    | SYSID uid

描述

CREATE ROLE 向 PostgreSQL 数据库集群中添加一个新角色。角色是一个可以拥有数据库对象并具有数据库权限的实体；角色可以被视为 “用户”、“组”，或两者，具体取决于其使用方式。有关管理用户和身份验证的信息，请参阅第 22 章和第 21 章。您必须拥有 CREATEROLE 权限或成为数据库超级用户才能使用此命令。

请注意，角色是在数据库集群级别定义的，因此在集群中的所有数据库中都是有效的。

在角色创建期间，可以立即将新创建的角色指定为现有角色的成员，还可以将现有角色指定为新创建角色的成员。有关启用哪些初始角色成员资格选项的规则，请参阅以下 IN ROLE、ROLE 和 ADMIN 子句中的说明。GRANT 命令在创建成员资格期间具有细粒度的选项控制，并且能够在新角色创建后修改这些选项。

参数

name

新角色的名称。

SUPERUSER NOSUPERUSER

这些子句确定新角色是否是 “超级用户”，它可以覆盖数据库中的所有访问限制。超级用户状态很危险，只有在真正需要时才应使用。您自己必须是超级用户才能创建新的超级用户。如果未指定，则 NOSUPERUSER 为默认值。

CREATEDB NOCREATEDB

这些子句定义角色创建数据库的能力。如果指定 CREATEDB，则正在定义的角色将被允许创建新数据库。指定 NOCREATEDB 将拒绝角色创建数据库的能力。如果未指定，则 NOCREATEDB 为默认值。只有超级用户角色或具有 CREATEDB 的角色才能指定 CREATEDB。

CREATEROLE NOCREATEROLE

这些子句确定是否允许角色创建、更改、删除、注释和更改其他角色的安全标签。有关此权限赋予哪些功能的更多详细信息，请参阅角色创建。如果未指定，则 NOCREATEROLE 为默认值。

INHERIT NOINHERIT

当此角色作为另一个角色的成员添加时，这会影响成员继承状态，无论是在此命令还是在将来的命令中。具体来说，它控制使用 IN ROLE 子句在此命令中添加的成员资格的继承状态，以及在使用 ROLE 子句的后续命令中。当使用 GRANT 命令添加此角色作为成员时，它也会用作默认继承状态。如果未指定，INHERIT 为默认值。

在 16 之前的 PostgreSQL 版本中，继承是角色级属性，用于控制该角色的所有运行时成员资格检查。

LOGIN NOLOGIN

这些子句确定角色是否允许登录；也就是说，是否可以在客户端连接期间将角色指定为初始会话授权名称。具有 LOGIN 属性的角色可以被认为是用户。没有此属性的角色对于管理数据库权限很有用，但不是通常意义上的用户。如果未指定，NOLOGIN 为默认值，但当通过其替代拼写 CREATE USER 调用 CREATE ROLE 时除外。

REPLICATION NOREPLICATION

这些子句确定角色是否是复制角色。角色必须具有此属性（或成为超级用户）才能以复制模式（物理复制或逻辑复制）连接到服务器，并才能创建或删除复制槽。具有 REPLICATION 属性的角色是一个非常高权限的角色，并且只应在实际用于复制的角色上使用。如果未指定，NOREPLICATION 为默认值。只有超级用户角色或具有 REPLICATION 的角色才能指定 REPLICATION。

BYPASSRLS NOBYPASSRLS

这些子句确定角色是否绕过每行安全 (RLS) 策略。NOBYPASSRLS 为默认值。只有超级用户角色或具有 BYPASSRLS 的角色才能指定 BYPASSRLS。

请注意，pg_dump 将默认将 row_security 设置为 OFF，以确保转储表的所有内容。如果运行 pg_dump 的用户没有适当的权限，将返回错误。但是，超级用户和正在转储的表的拥有者始终绕过 RLS。

CONNECTION LIMIT connlimit

如果角色可以登录，这将指定角色可以建立的并发连接数。-1（默认值）表示没有限制。请注意，只有正常连接才计入此限制。已准备的事务和后台工作程序连接都不计入此限制。

[ ENCRYPTED ] PASSWORD 'password' PASSWORD NULL

设置角色的密码。（密码仅对具有 LOGIN 属性的角色有用，但您仍然可以为没有该属性的角色定义密码。）如果您不打算使用密码身份验证，则可以省略此选项。如果未指定密码，则密码将设置为 null，并且该用户的密码身份验证将始终失败。可以将 null 密码显式地写为 PASSWORD NULL。

注意

指定空字符串也将把密码设置为 null，但在 PostgreSQL 10 版之前并非如此。在早期版本中，可以使用空字符串，也可以不使用，具体取决于身份验证方法和确切版本，并且 libpq 在任何情况下都拒绝使用它。为了避免歧义，应避免指定空字符串。

密码始终以加密形式存储在系统目录中。ENCRYPTED 关键字无效，但出于向后兼容性考虑而被接受。加密方法由配置参数 password_encryption 确定。如果提供的密码字符串已经是 MD5 加密或 SCRAM 加密格式，那么无论 password_encryption 如何，它都将按原样存储（因为系统无法解密指定的加密密码字符串，以不同格式对其进行加密）。这允许在转储/还原期间重新加载加密密码。

VALID UNTIL 'timestamp'

VALID UNTIL 子句设置一个日期和时间，在此之后角色的密码将不再有效。如果省略此子句，则密码将一直有效。

IN ROLE role_name

IN ROLE 子句导致新角色自动添加为指定现有角色的成员。新成员资格将启用 SET 选项并禁用 ADMIN 选项。INHERIT 选项将被启用，除非指定了 NOINHERIT 选项。

IN GROUP role_name

IN GROUP 是 IN ROLE 的过时拼写。

ROLE role_name

ROLE 子句导致一个或多个指定的现有角色自动添加为成员，同时启用 SET 选项。这实际上使新角色成为一个 “组”。在此子句中命名的具有角色级别 INHERIT 属性的角色将在新成员资格中启用 INHERIT 选项。新成员资格将禁用 ADMIN 选项。

ADMIN role_name

ADMIN 子句与 ROLE 子句具有相同的效果，但命名的角色被添加为新角色的成员，并启用 ADMIN，从而赋予他们向其他人授予新角色成员资格的权利。

USER role_name

USER 子句是 ROLE 子句的过时拼写。

SYSID uid

SYSID 子句被忽略，但出于向后兼容性考虑而被接受。

注释

使用 ALTER ROLE 更改角色的属性，并使用 DROP ROLE 删除角色。由 CREATE ROLE 指定的所有属性都可以通过后续的 ALTER ROLE 命令进行修改。

添加和删除用作组的角色成员的首选方法是使用 GRANT 和 REVOKE。

VALID UNTIL 子句仅为密码定义到期时间，而不是角色本身的到期时间。特别是，在使用基于非密码的身份验证方法登录时，不会强制执行到期时间。

此处定义的角色属性不可继承，即，成为具有 CREATEDB 等的角色的成员不会允许成员创建新数据库，即使成员授予具有 INHERIT 选项。当然，如果成员授予具有 SET 选项，则成员角色将能够 SET ROLE 到 createdb 角色，然后创建新数据库。

由 IN ROLE、ROLE 和 ADMIN 子句创建的成员资格授予将执行此命令的角色作为受让人。

INHERIT 属性出于向后兼容性的原因是默认属性：在 PostgreSQL 的早期版本中，用户始终可以访问其成员身份组的所有权限。但是，NOINHERIT 提供了与 SQL 标准中指定的语义更接近的匹配。

PostgreSQL 包含一个程序 createuser，其功能与 CREATE ROLE（事实上，它调用此命令）相同，但可以从命令 shell 运行。

CONNECTION LIMIT 选项仅近似强制执行；如果两个新会话在角色仅剩一个连接 “slot” 时大约同时启动，则两者都可能失败。此外，该限制永远不会对超级用户强制执行。

使用此命令指定未加密密码时必须小心。密码将以明文形式传输到服务器，并且也可能记录在客户端命令历史记录或服务器日志中。但是，命令 createuser 会加密传输密码。此外，psql 包含一个命令 \password，可用于稍后安全地更改密码。

示例

创建可以登录但不要给它密码的角色

CREATE ROLE jonathan LOGIN;

使用密码创建角色

CREATE USER davide WITH PASSWORD 'jw8s0F4';

(CREATE USER 与 CREATE ROLE 相同，除了它暗示 LOGIN。）

创建具有密码的角色，该密码在 2004 年底之前有效。在 2005 年过了一秒钟之后，密码将不再有效。

CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';

创建可以创建数据库和管理角色的角色

CREATE ROLE admin WITH CREATEDB CREATEROLE;

兼容性

CREATE ROLE 语句在 SQL 标准中，但该标准仅要求语法

CREATE ROLE name [ WITH ADMIN role_name ]

多个初始管理员和 CREATE ROLE 的所有其他选项是 PostgreSQL 扩展。

SQL 标准定义了用户和角色的概念，但将其视为不同的概念，并让每个数据库实现指定定义用户的全部命令。在 PostgreSQL 中，我们选择将用户和角色统一为单一类型的实体。因此，角色比标准中拥有的可选属性多得多。

SQL 标准指定的行为最接近于将 SQL 标准用户创建为具有 NOINHERIT 选项的 PostgreSQL 角色，以及将 SQL 标准角色创建为具有 INHERIT 选项的 PostgreSQL 角色。

另请参阅

SET ROLE、ALTER ROLE、DROP ROLE、GRANT、REVOKE、createuser、createrole_self_grant