CREATE ROLE

CREATE ROLE
上一页	上一级	SQL 命令	首页	下一页

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

Synopsis

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 数据库集群添加一个新角色。角色是一个可以拥有数据库对象并持有数据库特权的实体；根据使用方式的不同，角色可以被视为“用户”、“组”，或两者兼而有之。有关管理用户和认证的信息，请参见 Chapter 21 和 Chapter 20。使用此命令必须拥有 CREATEROLE 特权或者是数据库超级用户。

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

在创建角色时，可以立即把新创建的角色指派为某个现有角色的成员，也可以把现有角色指派为新角色的成员。哪些初始角色成员身份选项会被启用，其规则在下文的 IN ROLE、ROLE 和 ADMIN 子句中描述。GRANT 命令在创建成员身份时提供更细粒度的选项控制，并且可以在新角色创建之后修改这些选项。

参数

name

新角色的名字。

SUPERUSER NOSUPERUSER

这些子句决定新角色是否为“超级用户”，超级用户可以绕过数据库中的所有访问限制。超级用户状态是危险的，应当只在真正需要时才使用。你必须自己就是超级用户才能创建新的超级用户。如果不指定，默认为 NOSUPERUSER。

CREATEDB NOCREATEDB

这些子句定义角色创建数据库的能力。如果指定了 CREATEDB，被定义的角色将被允许创建新数据库。指定 NOCREATEDB 将剥夺角色创建数据库的能力。如果不指定，默认为 NOCREATEDB。只有超级用户角色或拥有 CREATEDB 的角色才能指定 CREATEDB。

CREATEROLE NOCREATEROLE

这些子句决定是否允许该角色创建、修改、删除其他角色，对其他角色进行注释以及更改其安全标签。有关此特权赋予哪些能力的更多细节，参见创建角色特权（CREATEROLE）。如果不指定，默认为 NOCREATEROLE。

INHERIT NOINHERIT

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

在 PostgreSQL 16 之前的版本中，继承是一个角色级属性，控制该角色在运行时的所有成员身份检查。

LOGIN NOLOGIN

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

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 属性的角色有用，但你仍然可以为没有该属性的角色定义密码。）如果你不打算使用密码认证，可以省略此选项。如果没有指定密码，密码将被设置为空，该用户的密码认证将总是失败。空密码也可以显式写成 PASSWORD NULL。

Note

指定空字符串也会把密码设置为空，但在 PostgreSQL 10 之前并非如此。在更早的版本中，空字符串能否使用取决于认证方法和具体版本，而且 libpq 在任何情况下都会拒绝使用它。为避免这种歧义，应当避免指定空字符串。

密码总是以加密形式存储在系统目录中。ENCRYPTED 关键字没有任何效果，只是为了向后兼容而被接受。加密方法由配置参数 password_encryption 决定。如果所提供的密码字符串已经是 MD5 加密或 SCRAM 加密的格式，那么无论 password_encryption 设置如何，它都会按原样存储（因为系统无法解密所给的加密密码字符串再以其他格式加密）。这使得在转储/恢复期间可以重新载入加密的密码。

Warning

对 MD5 加密密码的支持已被弃用，并将在 PostgreSQL 的未来版本中被移除。有关迁移到其他密码类型的细节，请参见 Section 20.3.2。

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 子句只为密码定义一个过期时间，而不是针对角色本身。特别地，在使用基于非密码的认证方法登录时，不会强制执行这个过期时间。

这里定义的角色属性是不可继承的，也就是说，即使成员身份授予带有 INHERIT 选项，作为具有 CREATEDB 等属性角色的成员也不能创建新数据库。当然，如果成员身份授予带有 SET 选项，成员角色将能够 SET ROLE 到具有创建数据库能力的角色，然后再创建新数据库。

由 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 年一秒之后，该密码就不再有效。

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 标准中的用户创建为 PostgreSQL 中带 NOINHERIT 选项的角色，将 SQL 标准中的角色创建为 PostgreSQL 中带 INHERIT 选项的角色，最能近似地体现 SQL 标准所规定的行为。

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

USER role_name [, ...]

IN GROUP 子句与 IN ROLE 的行为相同，但已被弃用：

IN GROUP role_name [, ...]

另请参阅

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