community.postgresql.postgresql_privs 模块 – 授予或撤销 PostgreSQL 数据库对象的权限

注意

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

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

要安装它，请使用：ansible-galaxy collection install community.postgresql。您需要进一步的要求才能使用此模块，有关详细信息，请参阅 要求。

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

概要

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

• 此模块基本上是 PostgreSQL 的 GRANT 和 REVOKE 语句的大部分功能的包装器，并具有更改检测功能（GRANT/REVOKE privs ON type objs TO/FROM roles）。

要求

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

• psycopg2 >= 2.5.1

参数

参数	注释
ca_cert 别名：ssl_rootcert 字符串	指定包含 SSL 证书颁发机构 (CA) 证书的文件名。 如果文件存在，将验证服务器的证书是否由这些机构之一签名。
connect_params 字典 在 community.postgresql 2.3.0 中添加	要传递给 libpg 的任何其他参数。 这些参数优先。 默认值： {}
database 别名：db，login_db 字符串 / 必需	要连接的数据库的名称。
fail_on_role 布尔值	如果为 true，则当目标角色（需要为其授予权限的角色）不存在时失败。否则，仅发出警告并继续。 选项 false true ←（默认值）
grant_option 别名：admin_option 布尔值	角色是否可以向其他人授予/撤销指定的权限/组成员资格。 设置为 false 以撤销 GRANT OPTION，保留未指定以不进行更改。 grant_option 仅在 state 为 present 时有效。 选项 false true
login_host 别名：host 字符串	运行数据库的主机。 如果在使用 localhost 时遇到连接问题，请尝试改用 127.0.0.1。 默认值： ""
login_password 字符串	此模块应使用密码来建立其 PostgreSQL 会话。 默认值： ""
login_unix_socket 别名：unix_socket 字符串	用于本地连接的 Unix 域套接字的路径。 默认值： ""
login_user 别名：login 字符串	此模块应使用用户名来建立其 PostgreSQL 会话。 默认值： "postgres"
objs 别名：obj 字符串	要设置权限的数据库对象的逗号分隔列表。 如果 type 为 table、partition table、sequence、function 或 procedure，则可以提供特殊值 ALL_IN_SCHEMA 来指定通过 schema 指定的模式中 type 的所有数据库对象。（这也适用于 PostgreSQL < 9.0。）（ALL_IN_SCHEMA 自 Ansible 2.8 起可用于 function 和 partition table。） 自 PostgreSQL 11 和 community.postgresql 集合 1.3.0 起支持 procedure。 自 PostgreSQL 15 和 community.postgresql 集合 3.1.0 起支持 parameter。 如果 type 为 database，则可以省略此参数，在这种情况下，将为通过 database 指定的数据库设置权限。 如果 type 为 function 或 procedure，则对象名称中的冒号（“:”）将替换为逗号（需要指定签名，请参阅示例）。
password 字符串	用于身份验证的密码。 此选项已弃用，将在 community.postgresql 4.0.0 中删除，请改用 login_password 选项。 与 login_password 互斥。 默认值： ""
port 别名：login_port 整数	要连接的数据库端口。 默认值： 5432
privs 别名：priv 字符串	要授予/撤销的权限的逗号分隔列表。
roles 别名：role 字符串 / 必需	要为其设置权限的角色（用户/组）名称的逗号分隔列表。 角色 PUBLIC、 CURRENT_ROLE、 CURRENT_USER、 SESSION_USER 在 PostgreSQL 中是隐式定义的。 CURRENT_USER 和 SESSION_USER 隐式角色自集合版本 3.1.0 和 PostgreSQL 9.5 起受支持。 CURRENT_ROLE 隐式角色自集合版本 3.1.0 和 PostgreSQL 14 起受支持。
schema 字符串	包含通过 objs 指定的数据库对象的模式。 只有当 type 为 table、 sequence、 function、 procedure、 type 或 default_privs 时才能提供。在这些情况下，默认为 public。 请注意，对于嵌入式类型，当 type=type 时，schema 可以分别是 pg_catalog 或 information_schema。 如果未指定，则使用 public。要不传递任何模式，请使用 not-specified。
session_role 字符串	连接后切换到 session_role。 指定的 session_role 必须是当前 login_user 所属的角色。 SQL 命令的权限检查就像 session_role 是最初登录的用户一样进行。
ssl_cert 路径 在 community.postgresql 2.4.0 中添加	指定客户端 SSL 证书的文件名。
ssl_key 路径 在 community.postgresql 2.4.0 中添加	指定用于客户端证书的密钥的路径。
ssl_mode 字符串	确定是否以及以什么优先级与服务器协商安全的 SSL TCP/IP 连接。 有关模式的更多信息，请参见 https://postgresql.ac.cn/docs/current/static/libpq-ssl.html。 prefer 的默认值与 libpq 的默认值匹配。 选项 "allow" "disable" "prefer" ← (默认) "require" "verify-ca" "verify-full"
state 字符串	如果为 present，则授予指定的权限；如果为 absent，则撤销这些权限。 选项 "absent" "present" ← (默认)
target_roles 字符串	一个现有角色（用户/组）名称的列表，设置为它们随后创建的数据库对象的默认权限。 参数 target_roles 仅在 type=default_privs 时可用。
trust_input 布尔值 在 community.postgresql 0.2.0 中添加	如果为 false，则检查参数 roles、target_roles、session_role、schema 的值是否可能存在危险。 仅当通过参数可能发生 SQL 注入时，才使用 false 才有意义。 选项 false true ←（默认值）
type 字符串	要设置权限的数据库对象的类型。 default_privs 选项从 2.7 版本开始可用。 foreign_data_wrapper 和 foreign_server 对象类型从 Ansible 2.8 版本开始可用。 type 选项从 Ansible 2.10 版本开始可用。 procedure 自集合版本 1.3.0 和 PostgreSQL 11 起受支持。 parameter 自集合版本 3.1.0 和 PostgreSQL 15 起受支持。 table 自集合版本 3.6.0 起包含外部表。 选项 "database" "default_privs" "foreign_data_wrapper" "foreign_server" "function" "group" "language" "table" ← (默认) "tablespace" "schema" "sequence" "type" "procedure" "parameter"

属性

属性	支持	描述
check_mode	支持: 完整	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标。

注释

注意

• 接受逗号分隔列表的参数（privs、objs、roles）具有单数别名名称（priv、obj、role）。

• 要仅撤销特定对象的 GRANT OPTION，请将 state 设置为 present，并将 grant_option 设置为 false（请参阅示例）。

• 请注意，当从角色 R 撤销权限时，该角色仍然可以通过授予任何 R 所属的角色（包括 PUBLIC）的权限来访问。

• 请注意，当从角色 R 撤销权限时，您是以通过 login_user 指定的用户身份执行的。如果 R 也被另一个用户授予了相同的权限，那么 R 仍然可以通过这些权限访问数据库对象。

• 当撤销权限时，假定使用 RESTRICT（请参阅 PostgreSQL 文档）。

• 默认身份验证假定您是以主机上的 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_user

从 PostgreSQL 服务器实例创建、更改或删除用户（角色）。

community.postgresql.postgresql_owner

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

community.postgresql.postgresql_membership

从组中添加或删除 PostgreSQL 角色。

PostgreSQL 权限

有关 PostgreSQL 权限的一般信息。

PostgreSQL GRANT 命令参考

PostgreSQL GRANT 命令文档的完整参考。

PostgreSQL REVOKE 命令参考

PostgreSQL REVOKE 命令文档的完整参考。

示例

# On database "library":
# GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors
# TO librarian, reader WITH GRANT OPTION
- name: Grant privs to librarian and reader on database library
  community.postgresql.postgresql_privs:
    database: library
    state: present
    privs: SELECT,INSERT,UPDATE
    type: table
    objs: books,authors
    schema: public
    roles: librarian,reader
    grant_option: true

- name: Same as above leveraging default values
  community.postgresql.postgresql_privs:
    db: library
    privs: SELECT,INSERT,UPDATE
    objs: books,authors
    roles: librarian,reader
    grant_option: true

# REVOKE GRANT OPTION FOR INSERT ON TABLE books FROM reader
# Note that role "reader" will be *granted* INSERT privilege itself if this
# isn't already the case (since state: present).
- name: Revoke privs from reader
  community.postgresql.postgresql_privs:
    db: library
    state: present
    priv: INSERT
    obj: books
    role: reader
    grant_option: false

# "public" is the default schema. This also works for PostgreSQL 8.x.
- name: REVOKE INSERT, UPDATE ON ALL TABLES IN SCHEMA public FROM reader
  community.postgresql.postgresql_privs:
    db: library
    state: absent
    privs: INSERT,UPDATE
    objs: ALL_IN_SCHEMA
    role: reader

- name: GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian
  community.postgresql.postgresql_privs:
    db: library
    privs: ALL
    type: schema
    objs: public,math
    role: librarian

# Note the separation of arguments with colons.
- name: GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader
  community.postgresql.postgresql_privs:
    db: library
    privs: ALL
    type: function
    obj: add(int:int)
    schema: math
    roles: librarian,reader

# Note that group role memberships apply cluster-wide and therefore are not
# restricted to database "library" here.
- name: GRANT librarian, reader TO alice, bob WITH ADMIN OPTION
  community.postgresql.postgresql_privs:
    db: library
    type: group
    objs: librarian,reader
    roles: alice,bob
    admin_option: true

# Note that here "db: postgres" specifies the database to connect to, not the
# database to grant privileges on (which is specified via the "objs" param)
- name: GRANT ALL PRIVILEGES ON DATABASE library TO librarian
  community.postgresql.postgresql_privs:
    db: postgres
    privs: ALL
    type: database
    obj: library
    role: librarian

# If objs is omitted for type "database", it defaults to the database
# to which the connection is established
- name: GRANT ALL PRIVILEGES ON DATABASE library TO librarian
  community.postgresql.postgresql_privs:
    db: library
    privs: ALL
    type: database
    role: librarian

# Available since version 2.7
# Objs must be set, ALL_DEFAULT to TABLES/SEQUENCES/TYPES/FUNCTIONS
# ALL_DEFAULT works only with privs=ALL
# For specific
- name: ALTER DEFAULT PRIVILEGES ON DATABASE library TO librarian
  community.postgresql.postgresql_privs:
    db: library
    objs: ALL_DEFAULT
    privs: ALL
    type: default_privs
    role: librarian
    grant_option: true

# Available since version 2.7
# Objs must be set, ALL_DEFAULT to TABLES/SEQUENCES/TYPES/FUNCTIONS
# ALL_DEFAULT works only with privs=ALL
# For specific
- name: ALTER DEFAULT PRIVILEGES ON DATABASE library TO reader, step 1
  community.postgresql.postgresql_privs:
    db: library
    objs: TABLES,SEQUENCES
    privs: SELECT
    type: default_privs
    role: reader

- name: ALTER DEFAULT PRIVILEGES ON DATABASE library TO reader, step 2
  community.postgresql.postgresql_privs:
    db: library
    objs: TYPES
    privs: USAGE
    type: default_privs
    role: reader

# Available since version 2.8
- name: GRANT ALL PRIVILEGES ON FOREIGN DATA WRAPPER fdw TO reader
  community.postgresql.postgresql_privs:
    db: test
    objs: fdw
    privs: ALL
    type: foreign_data_wrapper
    role: reader

# Available since community.postgresql 0.2.0
- name: GRANT ALL PRIVILEGES ON TYPE customtype TO reader
  community.postgresql.postgresql_privs:
    db: test
    objs: customtype
    privs: ALL
    type: type
    role: reader

# Available since version 2.8
- name: GRANT ALL PRIVILEGES ON FOREIGN SERVER fdw_server TO reader
  community.postgresql.postgresql_privs:
    db: test
    objs: fdw_server
    privs: ALL
    type: foreign_server
    role: reader

# Available since version 2.8
# Grant 'execute' permissions on all functions in schema 'common' to role 'caller'
- name: GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA common TO caller
  community.postgresql.postgresql_privs:
    type: function
    state: present
    privs: EXECUTE
    roles: caller
    objs: ALL_IN_SCHEMA
    schema: common

# Available since collection version 1.3.0
# Grant 'execute' permissions on all procedures in schema 'common' to role 'caller'
# Needs PostreSQL 11 or higher and community.postgresql 1.3.0 or higher
- name: GRANT EXECUTE ON ALL PROCEDURES IN SCHEMA common TO caller
  community.postgresql.postgresql_privs:
    type: procedure
    state: present
    privs: EXECUTE
    roles: caller
    objs: ALL_IN_SCHEMA
    schema: common

# Available since version 2.8
# ALTER DEFAULT PRIVILEGES FOR ROLE librarian IN SCHEMA library GRANT SELECT ON TABLES TO reader
# GRANT SELECT privileges for new TABLES objects created by librarian as
# default to the role reader.
# For specific
- name: ALTER privs
  community.postgresql.postgresql_privs:
    db: library
    schema: library
    objs: TABLES
    privs: SELECT
    type: default_privs
    role: reader
    target_roles: librarian

# Available since version 2.8
# ALTER DEFAULT PRIVILEGES FOR ROLE librarian IN SCHEMA library REVOKE SELECT ON TABLES FROM reader
# REVOKE SELECT privileges for new TABLES objects created by librarian as
# default from the role reader.
# For specific
- name: ALTER privs
  community.postgresql.postgresql_privs:
    db: library
    state: absent
    schema: library
    objs: TABLES
    privs: SELECT
    type: default_privs
    role: reader
    target_roles: librarian

# Available since community.postgresql 0.2.0
- name: Grant type privileges for pg_catalog.numeric type to alice
  community.postgresql.postgresql_privs:
    type: type
    roles: alice
    privs: ALL
    objs: numeric
    schema: pg_catalog
    db: acme

- name: Alter default privileges grant usage on schemas to datascience
  community.postgresql.postgresql_privs:
    database: test
    type: default_privs
    privs: usage
    objs: schemas
    role: datascience

# Available since community.postgresql 3.1.0
# Needs PostgreSQL 15 or higher
- name: GRANT SET ON PARAMETER log_destination,log_line_prefix TO logtest
  community.postgresql.postgresql_privs:
    database: logtest
    state: present
    privs: SET
    type: parameter
    objs: log_destination,log_line_prefix
    roles: logtest

- name: GRANT ALTER SYSTEM ON PARAMETER primary_conninfo,synchronous_standby_names TO replicamgr
  community.postgresql.postgresql_privs:
    database: replicamgr
    state: present
    privs: ALTER_SYSTEM
    type: parameter
    objs: primary_conninfo,synchronous_standby_names
    roles: replicamgr

返回值

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

键	描述
queries list / elements=string	已执行查询的列表。 返回: 成功 示例: ["REVOKE GRANT OPTION FOR INSERT ON TABLE \"books\" FROM \"reader\";"]

作者

• Bernhard Weitzhofer (@b6d)

• Tobias Birkefeld (@tcraxs)

• Daniele Giudice (@RealGreenDragon)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 报告问题
• 通讯