community.postgresql.postgresql_user 模块 – 在 PostgreSQL 服务器实例中创建、修改或删除用户 (角色)

注意

此模块是 community.postgresql 集合 (版本 3.9.0) 的一部分。

如果您正在使用 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查是否已安装它，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install community.postgresql。您需要其他要求才能使用此模块，请参阅 要求 获取详细信息。

要在 playbook 中使用它，请指定： community.postgresql.postgresql_user。

概要

• 在 PostgreSQL 服务器实例（在 PostgreSQL 术语中称为“集群”）中创建、修改或删除用户 (角色)，并可选择地授予用户对现有数据库或表的访问权限。

• 用户是一个具有登录权限的角色。

• 您也可以使用它来授予或撤销用户在特定数据库中的权限。

• 当用户仍在任何数据库中拥有任何授予的权限时，您无法删除该用户。

• 将 fail_on_user 设置为 false 以使模块忽略尝试删除用户时的失败。在这种情况下，模块照常报告是否发生了更改，并分别报告用户是否已删除。

• **警告** priv 选项已**弃用**，将在 community.postgresql 4.0.0 中删除。请改用 community.postgresql.postgresql_privs 模块。

要求

以下要求是在执行此模块的主机上所需的。

• psycopg2 >= 2.5.1

参数

参数	注释
ca_cert 别名：ssl_rootcert 字符串	指定包含 SSL 证书颁发机构 (CA) 证书的文件的名称。 如果文件存在，则验证服务器的证书是否由这些机构之一签名。
注释 字符串 在 community.postgresql 0.2.0 中添加。	在用户上添加注释（相当于 COMMENT ON ROLE 语句）。 要重置注释，请传递空字符串。
配置 字典 在 community.postgresql 3.5.0 中添加。	角色特定的配置参数，否则将由 ALTER ROLE user SET variable TO value; 设置。 接受一个字典，其中键是配置参数的名称。如果键包含特殊字符，例如 . 和 -，则需要对其进行引用以确保 YAML 有效。 设置或更新数据库中不存在或值错误的列表中的任何参数。 从此处删除用户中未列出的任何参数。 如果 reset_unspecified_configuration=true，则仅重置数据库中存在但未包含在此列表中的参数。 模块会引用此参数中的 user 输入以及键和值。如果您需要用户包含 "，则需要将其加倍，否则模块将失败。" 和 ' 不允许在配置键中使用，此模块将转义配置值中的任何 '。此外，如果 trust_input 为 false，则会检查参数和值。 默认值： {}
conn_limit 整数	指定用户 (角色) 连接限制。
connect_params 字典 在 community.postgresql 2.3.0 中添加。	要传递给 libpg 的任何其他参数。 这些参数具有优先级。 默认值： {}
db 别名：login_db 字符串	要连接到的数据库名称以及授予用户权限的数据库。 默认值： ""
encrypted 布尔值	密码是否以哈希形式存储在数据库中。 您可以指定未哈希的密码，当设置 encrypted=true 时，PostgreSQL 会确保存储的密码已哈希。如果您指定哈希密码，则无论 encrypted 的设置如何，模块都会按原样使用它。 注意：Postgresql 10 及更高版本不支持未哈希的密码。 在 Ansible 2.6 之前，默认值为 false。 选项 false true ← (默认)
expires 字符串	用户密码过期日期。 如果设置为 'infinity'，则用户密码永不过期。 请注意，此值必须是有效的 SQL 日期和时间类型。
fail_on_user 别名：fail_on_role 布尔值	如果为 true，则在无法删除用户 (角色) 时失败。否则只记录并继续。 选项 false true ← (默认)
login_host 别名：host 字符串	运行数据库的主机。 如果使用localhost时遇到连接问题，请尝试使用127.0.0.1。 默认值： ""
login_password 字符串	此模块用于建立PostgreSQL会话的密码。 默认值： ""
login_unix_socket 别名：unix_socket 字符串	本地连接的Unix域套接字路径。 默认值： ""
login_user 别名：login 字符串	此模块用于建立PostgreSQL会话的用户名。 默认值："postgres"
name 别名：user 字符串 / 必填	要添加或删除的用户（角色）名称。
no_password_changes 布尔值	如果为true，则不会检查数据库中的密码更改。如果用户已存在，则跳过所有与密码相关的检查。当无法访问pg_authid（例如在AWS RDS中）时非常有用。否则，根据需要更改密码。 选项 false ← (默认) true
password 字符串	设置用户的密码，1.4版本之前这是必需的。 密码可以是非哈希的或哈希的（MD5哈希）。 如果设置了encrypted，则未哈希的密码在保存到数据库时会自动进行哈希处理，否则将以纯文本格式保存。 传递MD5哈希密码时，必须使用'str["md5"] + md5[ password + username ]'格式生成，总共35个字符。一个简单的做法是echo "md5`echo -n 'verysecretpasswordJOE' | md5sum | awk '{print $1}'`"。 请注意，如果提供的密码字符串已经是MD5哈希格式，则无论encrypted选项如何，都会按原样使用。
port 别名：login_port 整数	要连接的数据库端口。 默认值：5432
priv 字符串	此选项已弃用，将在community.postgresql 4.0.0中删除。请使用community.postgresql.postgresql_privs模块授予/撤销权限。 用斜杠分隔的PostgreSQL权限字符串：priv1/priv2，您可以在其中定义用户对数据库的权限（允许的选项 - ‘CREATE’，‘CONNECT’，‘TEMPORARY’，‘TEMP’，‘ALL’。例如CONNECT）或对表的权限（允许的选项 - ‘SELECT’，‘INSERT’，‘UPDATE’，‘DELETE’，‘TRUNCATE’，‘REFERENCES’，‘TRIGGER’，‘ALL’。例如table:SELECT）。此字符串的混合示例：CONNECT/CREATE/table1:SELECT/table2:INSERT。 当priv包含表时，模块默认使用public模式。如果需要指定不同的模式，请使用schema_name.table_name表示法，例如pg_catalog.pg_stat_database:SELECT。
reset_unspecified_configuration 布尔值 在 community.postgresql 3.5.0 中添加。	如果设置为true，则如果用户默认配置参数未包含在configuration中，则将重置这些参数；否则，如果未包含在configuration中，则不会修改现有参数。 选项 false ← (默认) true
role_attr_flags 字符串	PostgreSQL用户属性字符串，格式为：CREATEDB,CREATEROLE,SUPERUSER。 请注意，‘[NO]CREATEUSER’已弃用。 要创建一个简单的角色以将其用作组，请使用NOLOGIN标志。 请参阅PostgreSQL版本的文档中支持的标志的完整列表。 默认值： ""
session_role 字符串	连接后切换到会话角色。 指定的会话角色必须是当前login_user所属的角色。 SQL命令的权限检查将被执行，就好像会话角色是最初登录的角色一样。
ssl_cert 路径 在community.postgresql 2.4.0中添加	指定客户端SSL证书的文件名。
ssl_key 路径 在community.postgresql 2.4.0中添加	指定客户端证书使用的密钥位置。
ssl_mode 字符串	确定如何与服务器协商SSL会话。 有关模式的更多信息，请参阅https://postgresql.ac.cn/docs/current/static/libpq-ssl.html。 prefer的默认值与libpq默认值匹配。 选项 "allow" "disable" "prefer" ← (默认) "require" "verify-ca" "verify-full"
state 字符串	用户（角色）状态。 选项 "absent" "present" ← (默认)
trust_input 布尔值 在 community.postgresql 0.2.0 中添加。	如果为false，则检查选项name、password、privs、expires、role_attr_flags、comment、session_role的值是否可能有危险。 只有当可能通过选项进行SQL注入时，使用false才有意义。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行，并在不修改目标的情况下返回更改状态预测。

备注

注意

• 此模块默认情况下创建一个具有登录权限的用户（角色）。使用NOLOGIN role_attr_flags来更改此行为。

• 如果将PUBLIC指定为用户（角色），则权限更改将应用于所有用户（角色）。当指定PUBLIC用户时，不得指定密码或role_attr_flags。

• SCRAM-SHA-256哈希密码（SASL身份验证）需要PostgreSQL 10或更高版本。在之前的版本中，整个哈希字符串用作密码。

• 使用SCRAM-SHA-256哈希密码时，请确保在PostgreSQL版本不是默认值时使用environment:变量PGOPTIONS: "-c password_encryption=scram-sha-256"（请参阅提供的示例）。

• 在某些系统（例如AWS RDS）上，无法访问pg_authid，因此模块无法比较当前密码和所需密码password。在这种情况下，模块假定密码不同并更改它，并报告状态已更改。要跳过对现有用户的与密码相关的所有检查，请使用no_password_changes=true。

• 在某些系统（例如AWS RDS）上，SUPERUSER不可用。这意味着不应指定SUPERUSER和NOSUPERUSER role_attr_flags以保持幂等性并避免InsufficientPrivilege错误。

• 默认身份验证假定您正在以主机上的postgres帐户身份登录或使用sudo。

• 为了避免“Peer authentication failed for user postgres”错误，请使用postgres用户作为become_user。

• 此模块使用psycopg，一个Python PostgreSQL数据库适配器。在使用此模块之前，必须确保主机上安装了psycopg2 >= 2.5.1或psycopg3 >= 3.1.8。

• 如果远程主机是PostgreSQL服务器（这是默认情况），则还必须在远程主机上安装PostgreSQL。

• 对于基于Ubuntu的系统，在使用此模块之前，请在远程主机上安装postgresql、libpq-dev和python3-psycopg2包。

另请参阅

另请参阅

community.postgresql.postgresql_privs

授予或撤销PostgreSQL数据库对象的权限。

community.postgresql.postgresql_membership

向组添加或删除PostgreSQL角色。

community.postgresql.postgresql_owner

更改PostgreSQL数据库对象的拥有者。

PostgreSQL数据库角色

PostgreSQL数据库角色文档的完整参考。

PostgreSQL SASL身份验证

PostgreSQL SASL身份验证的完整参考。

示例

# This example uses the 'priv' argument which is deprecated.
# You should use the 'postgresql_privs' module instead.
- name: Connect to acme database, create django user, and grant access to database and products table
  community.postgresql.postgresql_user:
    db: acme
    name: django
    password: ceec4eif7ya
    priv: "CONNECT/products:ALL"
    expires: "Jan 31 2020"

- name: Add a comment on django user
  community.postgresql.postgresql_user:
    db: acme
    name: django
    comment: This is a test user

# Connect to default database, create rails user, set its password (MD5- or SHA256-hashed),
# and grant privilege to create other databases and demote rails from super user status if user exists
# the hash from the corresponding pg_authid entry.
- name: Create rails user, set MD5-hashed password, grant privs
  community.postgresql.postgresql_user:
    name: rails
    password: md59543f1d82624df2b31672ec0f7050460
    # password: SCRAM-SHA-256$4096:zFuajwIVdli9mK=NJkcv1Q++$JC4gWIrEHmF6sqRbEiZw5FFW45HUPrpVzNdoM72o730+;fqA4vLN3mCZGbhcbQyvNYY7anCrUTsem1eCh/4YA94=
    role_attr_flags: CREATEDB,NOSUPERUSER
  # When using sha256-hashed password:
  #environment:
  #  PGOPTIONS: "-c password_encryption=scram-sha-256"

# This example uses the 'priv' argument which is deprecated.
# You should use the 'postgresql_privs' module instead.
- name: Connect to acme database and remove test user privileges from there
  community.postgresql.postgresql_user:
    db: acme
    name: test
    priv: "ALL/products:ALL"
    state: absent
    fail_on_user: false

# This example uses the 'priv' argument which is deprecated.
# You should use the 'postgresql_privs' module instead.
- name: Connect to test database, remove test user from cluster
  community.postgresql.postgresql_user:
    db: test
    name: test
    priv: ALL
    state: absent

# This example uses the 'priv' argument which is deprecated.
# You should use the 'postgresql_privs' module instead.
- name: Connect to acme database and set user's password with no expire date
  community.postgresql.postgresql_user:
    db: acme
    name: django
    password: mysupersecretword
    priv: "CONNECT/products:ALL"
    expires: infinity

# Example privileges string format
# INSERT,UPDATE/table:SELECT/anothertable:ALL

- name: Connect to test database and remove an existing user's password
  community.postgresql.postgresql_user:
    db: test
    user: test
    password: ""

# Create user with a cleartext password if it does not exist or update its password.
# The password will be encrypted with SCRAM algorithm (available since PostgreSQL 10)
- name: Create appclient user with SCRAM-hashed password
  community.postgresql.postgresql_user:
    name: appclient
    password: "secret123"
  environment:
    PGOPTIONS: "-c password_encryption=scram-sha-256"

# This example uses the 'priv' argument which is deprecated.
# You should use the 'postgresql_privs' module instead.
- name: Create a user, grant SELECT on pg_catalog.pg_stat_database
  community.postgresql.postgresql_user:
    name: monitoring
    priv: 'pg_catalog.pg_stat_database:SELECT'

# Create a user and set a default-configuration that is active when they start a session
- name: Create a user with config-parameter
  community.postgresql.postgresql_user:
    name: appclient
    password: "secret123"
    configuration:
      work_mem: "16MB"

# Make sure user has only specified default configuration parameters
- name: Clear all configuration that is not explicitly defined for user
  community.postgresql.postgresql_user:
    name: appclient
    password: "secret123"
    configuration:
      work_mem: "16MB"
    reset_unspecified_configuration: true

返回值

常见的返回值已在此处记录，以下是此模块特有的字段

键	描述
queries 列表 / 元素=字符串	已执行查询的列表。 返回：成功 示例：["CREATE USER \"alice\"", "GRANT CONNECT ON DATABASE \"acme\" TO \"alice\""]

作者

• Ansible核心团队

集合链接

• 问题跟踪器
• 代码库（源代码）
• 报告问题
• 交流