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) 证书的文件名。如果该文件存在，则验证服务器的证书是否由其中一个机构签名。
comment 字符串在 community.postgresql 0.2.0 中添加	在用户上添加注释（相当于 `COMMENT ON ROLE` 语句）。要重置注释，请传递一个空字符串。
configuration 字典在 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 模块来 GRANT/REVOKE 权限。以斜杠分隔的 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 字符串	格式为 CREATEDB,CREATEROLE,SUPERUSER 的 PostgreSQL 用户属性字符串。请注意，“[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 核心团队

community.postgresql.postgresql_user 模块 – 从 PostgreSQL 服务器实例创建、更改或删除用户（角色）

作者

集合链接