PostgreSQL: 文档：17：CREATE ROLE

文档 → PostgreSQL 17

受支持版本：当前版本 (18) / 17 / 16 / 15 / 14

开发版本： devel

CREATE ROLE
Prev	Up	SQL 命令	Home	Next

CREATE ROLE

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

Synopsis

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

其中 option 可以是：

      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 #

这些子句决定某个角色是否被允许创建、更改、删除其他角色，为其添加注释，以及更改其安全标签。关于该权限赋予的具体能力，参见创建角色。若未指定，默认值是 NOCREATEROLE。

INHERIT NOINHERIT #

这会影响该角色在本命令以及后续命令中被加入为其他角色成员时，其成员资格的继承状态。具体来说，它控制通过本命令中的IN ROLE 子句添加的成员资格的继承状态，以及通过后续命令中的ROLE 子句添加的成员资格的继承状态。使用GRANT命令把该角色添加为成员时，它也会被用作默认继承状态。若未指定，默认值是 INHERIT。

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

LOGIN NOLOGIN #

这些子句决定一个角色是否允许登录，也就是说，该角色能否在客户端连接时被用作初始会话授权标识符。具有LOGIN属性的角色可以视为用户。没有这个属性的角色对于管理数据库权限很有用，但并不是通常意义上的用户。若未指定，默认值是NOLOGIN；但当 CREATE ROLE以其另一种拼写 CREATE USER 调用时，默认值是LOGIN。

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，并且该用户的密码认证将始终失败。也可以显式写为PASSWORD NULL。

Note

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

密码始终以加密形式存储在系统目录中。ENCRYPTED关键字没有实际效果，但为了向后兼容仍会被接受。加密方式由配置参数 password_encryption决定。如果给出的密码字符串已经是 MD5 加密或 SCRAM 加密格式，那么无论password_encryption 的值是什么，它都会按原样存储（因为系统无法解密指定的已加密密码字符串，再将其改用其他格式加密）。这样便可在转储/恢复期间重新装载已加密的密码。

Warning

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

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相同（实际上它就是调用此命令），但它可以从命令 shell 中运行。

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;

兼容性

SQL 标准包含CREATE ROLE语句，但标准只要求如下语法：

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 GROUP子句的行为与IN ROLE相同，但已经被弃用：

IN GROUP role_name [, ...]

参见

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

Prev	Up	Next
CREATE PUBLICATION	Home	CREATE RULE

提交更正

如果您发现文档中有不正确的内容、与您使用特定功能的经验不符或需要进一步说明，请使用此表单来报告文档问题。