PostgreSQL 17 文档: 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 [, ...]
    | ROLE role_name [, ...]
    | ADMIN role_name [, ...]
    | SYSID uid

说明

CREATE ROLE 为 PostgreSQL 数据库集群添加一个新角色。角色是可以拥有数据库对象和具有数据库权限的实体；可以认为角色是一个 “用户”、一个 “组”，或者两者皆是，具体取决于其使用方式。有关管理用户和身份验证的信息，请参阅第 21 章和第 20 章。您必须拥有 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 选项。除非指定了 NOINHERIT 选项，否则 INHERIT 选项将被启用。

ROLE role_name

ROLE 子句导致指定的一个或多个现有角色作为成员自动添加，其中 SET 选项已启用。这样实际上将新角色变成 “组”。在此子句中命名的具有角色级 INHERIT 属性的角色将在新成员关系中启用 INHERIT 选项。新成员关系中将禁用 ADMIN 选项。

ADMIN role_name

ADMIN 子句的作用与 ROLE 相同，但命名的角色作为成员添加到新角色中，并启用 ADMIN，从而获得向他人授予新角色成员关系的权利。

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 相同（事实上，它会调用该命令），但可从命令行在运行。

仅近似执行 CONNECTION LIMIT 选项；当仅有一个连接 “插槽”适用于该角色时，如果有两个新会话在同一时间左右开始，就有可能两个都会失败。此外，超级用户永远不会强制执行限制。

使用该命令指定未加密密码时务必谨慎。密码将以明文传输到服务器，且可能还会记录在客户端命令历史记录或服务器日志中。然而，命令 createuser 会以加密方式传输密码。此外，psql 包含命令 \password，可用于稍后以安全方式更改密码。

示例

创建允许登录但不要提供密码的角色

CREATE ROLE jonathan LOGIN;

创建带密码的角色

CREATE USER davide WITH PASSWORD 'jw8s0F4';

(CREATE USER 与 CREATE ROLE 相同，但暗示 LOGIN).

创建密码有效期到 2004 年末的角色。2005 年 1 秒后，密码将不再有效。

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 角色。

USER 子句的行为与 ROLE 相同，但已弃用。

USER role_name [, ...]

IN GROUPIN ROLE 相同，但已弃用

IN GROUP role_name [, ...]

另请参阅

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