↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 命令行工具 / 客户端程序

createuser

createuser — 定义一个新的 PostgreSQL 用户账户

当前查看 PostgreSQL 18.6。

说明

createuser — 定义一个新的 PostgreSQL 用户账户

手册中的可执行程序
createuser
程序版本
18.6
参考清单
客户端程序
选项定义组
30

用法

createuser [ connection-option ...] [ option ...] [ username ]

手册中的选项

选项与参数说明
-a role --with-admin= role指定一个现有角色，使其自动作为带有 ADMIN OPTION 的成员加入新角色，从而有权将新角色的成员资格授予其他角色。可以通过写多个 -a 开关来指定多个现有角色。
-c number --connection-limit= number为新用户设置最大连接数。默认不设限制。
-d --createdb允许新用户创建数据库。
-D --no-createdb不允许新用户创建数据库。这是默认设置。
-e --echo回显 createuser 生成并发送给服务器的命令。
-E --encrypted该选项已废弃，但为了向后兼容仍被接受。
-g role --member-of= role --role= role （已弃用）指定新角色应自动成为指定现有角色的成员。可以通过写多个 -g 开关来指定多个现有角色。
-i --inherit新角色将自动继承其所属角色的权限。这是默认设置。
-I --no-inherit新角色将不会自动继承其所属角色的权限。
--interactive如果命令行未指定用户名，则提示输入；对于命令行中未指定的 -d/-D、-r/-R、-s/-S 选项，也会逐项提示。（直到 PostgreSQL 9.1，这都是默认行为。）
-l --login允许新用户登录（也就是说，该用户名可用作初始会话用户标识符）。这是默认设置。
-L --no-login不允许新用户登录。（不具有登录权限的角色仍可用于管理数据库权限。）
-m role --with-member= role指定一个现有角色，使其自动作为成员加入新角色。可以通过写多个 -m 开关来指定多个现有角色。
-P --pwprompt如果给出此选项， createuser 会提示输入新用户的密码。如果不打算使用密码认证，则不需要这样做。
-r --createrole允许新用户创建、更改、删除其他角色，对其添加注释，以及更改其安全标签；也就是说，该用户将具有 CREATEROLE 权限。关于该权限赋予哪些能力的更多细节，见 创建角色 。
-R --no-createrole不允许新用户创建新角色。这是默认设置。
-s --superuser新用户将成为超级用户。
-S --no-superuser新用户将不是超级用户。这是默认设置。
-v timestamp --valid-until= timestamp设置一个日期和时间，在此之后该角色的密码将不再有效。默认不设置密码过期日期。
-V --version打印 createuser 版本并退出。
--bypassrls新用户将绕过每一条行级安全（RLS）策略。
--no-bypassrls新用户将不会绕过行级安全（RLS）策略。这是默认设置。
--replication新用户将具有 REPLICATION 权限，关于该权限的更完整说明见 CREATE ROLE 。
--no-replication新用户将不具有 REPLICATION 权限，关于该权限的更完整说明见 CREATE ROLE 。这是默认设置。
-? --help显示有关 createuser 命令行参数的帮助并退出。
-h host --host= host指定服务器所在主机的主机名。如果该值以斜杠开头，则将其用作 Unix 域套接字所在目录。
-p port --port= port指定服务器监听连接所用的 TCP 端口或本地 Unix 域套接字文件扩展名。
-U username --username= username指定连接时使用的用户名（不是要创建的用户名）。
-w --no-password绝不提示输入密码。如果服务器要求密码认证，而密码又无法通过诸如 .pgpass 文件等其他方式获得，则连接尝试将失败。该选项可用于没有用户在场输入密码的批处理作业和脚本。
-W --password强制 createuser 提示输入密码（用于连接到服务器，而不是新用户的密码）。

环境变量

变量含义
PGHOST PGPORT PGUSER默认连接参数
PG_COLOR指定诊断消息是否使用颜色。可选值为 always 、 auto 和 never 。

手册定义

createuser

createuser — 定义一个新的PostgreSQL用户账户

大纲

createuser [connection-option...] [option...] [username]

说明

createuser创建一个新的PostgreSQL用户（更准确地说，是一个角色）。只有超级用户以及具有CREATEROLE权限的用户才能创建新用户，因此调用createuser的用户必须能够以超级用户或具有CREATEROLE权限的用户身份连接。

如果要创建一个具有SUPERUSER、REPLICATION或BYPASSRLS权限的角色，则必须以超级用户身份连接，而不能仅具有CREATEROLE权限。超级用户意味着能够绕过数据库中的所有访问权限检查，因此不应轻易授予超级用户权限。CREATEROLE也赋予非常广泛的权限。

createuser是SQL命令CREATE ROLE的一个包装器。通过此工具创建用户与通过其他访问服务器的方法创建用户，在效果上没有区别。

选项

createuser接受下列命令行参数：

username

指定要创建的PostgreSQL用户名。该名称必须不同于此PostgreSQL安装中的所有现有角色名称。

-a role
--with-admin=role

指定一个现有角色，使其自动作为带有 ADMIN OPTION 的成员加入新角色，从而有权将新角色的成员资格授予其他角色。可以通过写多个-a开关来指定多个现有角色。

-c number
--connection-limit=number

为新用户设置最大连接数。默认不设限制。

-d
--createdb

允许新用户创建数据库。

-D
--no-createdb

不允许新用户创建数据库。这是默认设置。

-e
--echo

回显createuser生成并发送给服务器的命令。

-E
--encrypted

该选项已废弃，但为了向后兼容仍被接受。

-g role
--member-of=role
--role=role（已弃用）

指定新角色应自动成为指定现有角色的成员。可以通过写多个-g开关来指定多个现有角色。

-i
--inherit

新角色将自动继承其所属角色的权限。这是默认设置。

-I
--no-inherit

新角色将不会自动继承其所属角色的权限。

--interactive

如果命令行未指定用户名，则提示输入；对于命令行中未指定的 -d/-D、-r/-R、-s/-S 选项，也会逐项提示。（直到 PostgreSQL 9.1，这都是默认行为。）

-l
--login

允许新用户登录（也就是说，该用户名可用作初始会话用户标识符）。这是默认设置。

-L
--no-login

不允许新用户登录。（不具有登录权限的角色仍可用于管理数据库权限。）

-m role
--with-member=role

指定一个现有角色，使其自动作为成员加入新角色。可以通过写多个-m开关来指定多个现有角色。

-P
--pwprompt

如果给出此选项，createuser会提示输入新用户的密码。如果不打算使用密码认证，则不需要这样做。

-r
--createrole

允许新用户创建、更改、删除其他角色，对其添加注释，以及更改其安全标签；也就是说，该用户将具有CREATEROLE权限。关于该权限赋予哪些能力的更多细节，见创建角色。

-R
--no-createrole

不允许新用户创建新角色。这是默认设置。

-s
--superuser

新用户将成为超级用户。

-S
--no-superuser

新用户将不是超级用户。这是默认设置。

-v timestamp
--valid-until=timestamp

设置一个日期和时间，在此之后该角色的密码将不再有效。默认不设置密码过期日期。

-V
--version

打印createuser版本并退出。

--bypassrls

新用户将绕过每一条行级安全（RLS）策略。

--no-bypassrls

新用户将不会绕过行级安全（RLS）策略。这是默认设置。

--replication

新用户将具有REPLICATION权限，关于该权限的更完整说明见CREATE ROLE。

--no-replication

新用户将不具有REPLICATION权限，关于该权限的更完整说明见CREATE ROLE。这是默认设置。

-?
--help

显示有关createuser命令行参数的帮助并退出。

createuser也接受下列用于连接参数的命令行参数：

-h host
--host=host

指定服务器所在主机的主机名。如果该值以斜杠开头，则将其用作 Unix 域套接字所在目录。

-p port
--port=port

指定服务器监听连接所用的 TCP 端口或本地 Unix 域套接字文件扩展名。

-U username
--username=username

指定连接时使用的用户名（不是要创建的用户名）。

-w
--no-password

绝不提示输入密码。如果服务器要求密码认证，而密码又无法通过诸如.pgpass文件等其他方式获得，则连接尝试将失败。该选项可用于没有用户在场输入密码的批处理作业和脚本。

-W
--password

强制createuser提示输入密码（用于连接到服务器，而不是新用户的密码）。

该选项绝非必需，因为如果服务器要求密码认证，createuser会自动提示输入密码。不过，createuser会浪费一次连接尝试来发现服务器需要密码。在某些情况下，输入-W可以避免这次额外的连接尝试。

环境

PGHOST
PGPORT
PGUSER

默认连接参数

PG_COLOR

指定诊断消息是否使用颜色。可选值为 always、auto和 never。

与大多数其他 PostgreSQL 工具一样，此工具也使用 libpq 支持的环境变量（见第 32.15 节）。

诊断

如果遇到问题，请参见CREATE ROLE和psql中关于潜在问题和错误消息的讨论。数据库服务器必须在目标主机上运行。此外，libpq前端库所使用的任何默认连接设置和环境变量都会生效。

示例

要在默认数据库服务器上创建用户joe：

$ createuser joe

要在默认数据库服务器上创建用户joe，并提示输入一些额外属性：

$ createuser --interactive joe
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n

使用主机 eden 上端口为 5000 的服务器，显式指定属性来创建同一个用户 joe，并查看底层命令：

$ createuser -h eden -p 5000 -S -D -R -e joe
CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;

要把用户joe创建为超级用户，并立即为其设置密码：

$ createuser -P -s -e joe
Enter password for new role: xyzzy
Enter it again: xyzzy
CREATE ROLE joe PASSWORD 'SCRAM-SHA-256$4096:44560wPMLfjqiAzyPDZ/eQ==$4CA054rZlSFEq8Z3FEhToBTa2X6KnWFxFkPwIbKoDe0=:L/nbSZRCjp6RhOhKK56GoR1zibCCSePKshCJ9lnl3yw=' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN NOREPLICATION NOBYPASSRLS;

在上面的示例中，输入新密码时实际上不会回显它，但为清楚起见，这里展示了输入的内容。可以看到，该密码在发送给服务器之前就已经被加密了。

另见

dropuser, CREATE ROLE, createrole_self_grant

文档与源码

来源构建
版本
18.6
构建
https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹
ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 15 → 16: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 15
+++ PostgreSQL 16
@@ -11,6 +11,14 @@
   ],
   "options": [
     {
+      "description": "Specifies an existing role that will be automatically added as a member of the new role with admin option, giving it the right to grant membership in the new role to others. Multiple existing roles can be specified by writing multiple -a switches.",
+      "names": [
+        "-a role",
+        "--with-admin= role"
+      ],
+      "signature": "-a role --with-admin= role"
+    },
+    {
       "description": "Set a maximum number of connections for the new user. The default is to set no limit.",
       "names": [
         "-c number",
@@ -51,12 +59,13 @@
       "signature": "-E --encrypted"
     },
     {
-      "description": "Indicates role to which this role will be added immediately as a new member. Multiple roles to which this role will be added as a member can be specified by writing multiple -g switches.",
+      "description": "Specifies the new role should be automatically added as a member of the specified existing role. Multiple existing roles can be specified by writing multiple -g switches.",
       "names": [
         "-g role",
+        "--member-of= role",
         "--role= role"
       ],
-      "signature": "-g role --role= role"
+      "signature": "-g role --member-of= role --role= role (deprecated)"
     },
     {
       "description": "The new role will automatically inherit privileges of roles it is a member of. This is the default.",
@@ -98,6 +107,14 @@
       "signature": "-L --no-login"
     },
     {
+      "description": "Specifies an existing role that will be automatically added as a member of the new role. Multiple existing roles can be specified by writing multiple -m switches.",
+      "names": [
+        "-m role",
+        "--with-member= role"
+      ],
+      "signature": "-m role --with-member= role"
+    },
+    {
       "description": "If given, createuser will issue a prompt for the password of the new user. This is not necessary if you do not plan on using password authentication.",
       "names": [
         "-P",
@@ -106,7 +123,7 @@
       "signature": "-P --pwprompt"
     },
     {
-      "description": "The new user will be allowed to create, alter, drop, comment on, change the security label for, and grant or revoke membership in other roles; that is, this user will have CREATEROLE privilege. See role creation for more details about what capabilities are conferred by this privilege.",
+      "description": "The new user will be allowed to create, alter, drop, comment on, change the security label for other roles; that is, this user will have CREATEROLE privilege. See role creation for more details about what capabilities are conferred by this privilege.",
       "names": [
         "-r",
         "--createrole"
@@ -138,6 +155,14 @@
       "signature": "-S --no-superuser"
     },
     {
+      "description": "Set a date and time after which the role's password is no longer valid. The default is to set no password expiry date.",
+      "names": [
+        "-v timestamp",
+        "--valid-until= timestamp"
+      ],
+      "signature": "-v timestamp --valid-until= timestamp"
+    },
+    {
       "description": "Print the createuser version and exit.",
       "names": [
         "-V",
@@ -146,6 +171,20 @@
       "signature": "-V --version"
     },
     {
+      "description": "The new user will bypass every row-level security (RLS) policy.",
+      "names": [
+        "--bypassrls"
+      ],
+      "signature": "--bypassrls"
+    },
+    {
+      "description": "The new user will not bypass row-level security (RLS) policies. This is the default.",
+      "names": [
+        "--no-bypassrls"
+      ],
+      "signature": "--no-bypassrls"
+    },
+    {
       "description": "The new user will have the REPLICATION privilege, which is described more fully in the documentation for CREATE ROLE .",
       "names": [
         "--replication"
@@ -153,7 +192,7 @@
       "signature": "--replication"
     },
     {
-      "description": "The new user will not have the REPLICATION privilege, which is described more fully in the documentation for CREATE ROLE .",
+      "description": "The new user will not have the REPLICATION privilege, which is described more fully in the documentation for CREATE ROLE . This is the default.",
       "names": [
         "--no-replication"
       ],

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

相关条目

导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。