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 布尔值	role 是否可以将指定的权限/组成员身份授予或撤销给其他人。 设置为 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 中也适用）。（从 Ansible 2.8 开始，ALL_IN_SCHEMA 可用于 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，对象名称中的冒号（“: ”）将被替换为逗号（需要指定签名，请参见示例）。
密码 字符串	用于身份验证的密码。 此选项已弃用，将在 community.postgresql 4.0.0 中移除，请改用login_password 选项。 与login_password 互斥。 默认值： ""
端口 别名：login_port 整数	连接到的数据库端口。 默认值： 5432
权限 别名：priv 字符串	要授予/撤销的权限的逗号分隔列表。
角色 别名：role 字符串 / 必需	要为其设置权限的角色（用户/组）名称的逗号分隔列表。 PostgreSQL 中隐式定义了角色 PUBLIC、CURRENT_ROLE、CURRENT_USER、SESSION_USER。 从集合版本 3.1.0 和 PostgreSQL 9.5 开始支持 CURRENT_USER 和 SESSION_USER 隐式角色。 从集合版本 3.1.0 和 PostgreSQL 14 开始支持 CURRENT_ROLE 隐式角色。
模式 字符串	包含通过objs 指定的数据库对象的模式。 仅当type 为 table、sequence、function、procedure、type 或 default_privs 时才提供。在这些情况下，默认为 public。 请注意，对于嵌入式类型，当type=type 时，schema 可以分别为 pg_catalog 或 information_schema。 如果未指定，则使用 public。要避免传递任何模式，请使用 not-specified。
会话角色 字符串	连接后切换到session_role。 指定的session_role必须是当前登录用户所属的角色。 SQL命令的权限检查将像最初登录的session_role一样进行。
ssl证书 路径 在community.postgresql 2.4.0中添加	指定客户端SSL证书的文件名。
ssl密钥 路径 在community.postgresql 2.4.0中添加	指定用于客户端证书的密钥位置。
ssl模式 字符串	确定是否以及以什么优先级与服务器协商安全的SSL TCP/IP连接。 有关模式的更多信息，请参见https://postgresql.ac.cn/docs/current/static/libpq-ssl.html。 prefer 的默认值与 libpq 默认值匹配。 选项 "允许" "禁用" "prefer" ← (默认) "必需" "验证CA" "完全验证"
状态 字符串	如果 present，则授予指定的权限；如果 absent，则撤销指定的权限。 选项 "不存在" "present" ← (默认)
目标角色 字符串	现有角色（用户/组）名称列表，设置为随后由其创建的数据库对象的默认权限。 参数target_roles 仅在 type=default_privs 时可用。
信任输入 布尔值 在community.postgresql 0.2.0中添加	如果为 false，则检查参数roles、target_roles、session_role、schema 的值是否可能存在危险。 仅当可能通过参数进行SQL注入时，才建议使用 false。 选项 false true ← (默认)
类型 字符串	要设置其权限的数据库对象的类型。 从 2.7 版本开始提供 default_privs 选项。 从 Ansible 2.8 版本开始提供 foreign_data_wrapper 和 foreign_server 对象类型。 从 Ansible 2.10 版本开始提供 type 选项。 从集合版本 1.3.0 和 PostgreSQL 11 开始支持 procedure。 从集合版本 3.1.0 和 PostgreSQL 15 开始支持 parameter。 从集合版本 3.6.0 开始，table 包含外部表。 选项 "数据库" "默认权限" "外部数据包装器" "外部服务器" "函数" "组" "语言" "table" ← (默认) "表空间" "模式" "序列" "类型" "过程" "参数"

属性

属性	支持	描述
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 命令。

• 要避免“用户 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

返回值

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

键	描述
查询 列表 / 元素=字符串	已执行查询的列表。 返回：成功 示例： ["REVOKE GRANT OPTION FOR INSERT ON TABLE \"books\" FROM \"reader\";"]

作者

• Bernhard Weitzhofer (@b6d)

• Tobias Birkefeld (@tcraxs)

• Daniele Giudice (@RealGreenDragon)

资源链接

• 问题追踪
• 代码仓库
• 报告问题
• 沟通