community.postgresql.postgresql_set 模块 – 更改 PostgreSQL 服务器配置参数

注意

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

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

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

要在剧本中使用它，请指定：community.postgresql.postgresql_set。

概要

  • 允许更改 PostgreSQL 服务器配置参数。

  • 该模块使用 ALTER SYSTEM 命令并通过重新加载服务器配置来应用更改。

  • ALTER SYSTEM 用于更改整个数据库集群的服务器配置参数。

  • 它比手动编辑 postgresql.conf 文件的传统方法更方便和安全。

  • ALTER SYSTEM 将给定的参数设置写入 $PGDATA/postgresql.auto.conf 文件，该文件除了 postgresql.conf 之外还会被读取。

  • 该模块允许通过 reset=true 将参数重置为 boot_val（集群初始值）或从 postgresql.auto.conf 中删除参数字符串并重新加载 value=default（对于具有 postmaster 上下文的设置，需要重新启动）。

  • 更改后，您可以使用返回值和 ansible.builtin.debug 模块在 ansible 输出中看到先前和新的参数值以及其他信息。

要求

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

  • psycopg2 >= 2.5.1

参数

参数

注释

ca_cert

别名：ssl_rootcert

字符串

指定包含 SSL 证书颁发机构 (CA) 证书的文件名。

如果该文件存在，则将验证服务器的证书是否由这些机构之一签名。

connect_params

字典

在 community.postgresql 2.3.0 中添加

要传递给 libpg 的任何其他参数。

这些参数优先。

默认值： {}

db

别名：login_db

字符串

要连接的数据库名称。

login_host

别名：host

字符串

运行数据库的主机。

如果在使用 localhost 时出现连接问题，请尝试使用 127.0.0.1 代替。

默认值： ""

login_password

字符串

此模块应用于建立其 PostgreSQL 会话的密码。

默认值： ""

login_unix_socket

别名：unix_socket

字符串

用于本地连接的 Unix 域套接字的路径。

默认值： ""

login_user

别名：login

字符串

此模块应用于建立其 PostgreSQL 会话的用户名。

默认值： "postgres"

name

字符串 / 必需

PostgreSQL 服务器参数的名称。请注意，参数区分大小写（请参阅下面的示例）。

port

别名：login_port

整数

要连接的数据库端口。

默认值： 5432

reset

布尔值

将参数恢复到初始状态 (boot_val)。与 value 互斥。

选择

  • false ←（默认）

  • true

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"

trust_input

布尔值

在 community.postgresql 0.2.0 中添加

如果 false，请检查参数值是否可能危险。

仅当可能存在 SQL 注入时，使用 false 才是有意义的。

选择

  • false

  • true ← (默认)

value

字符串

要设置的参数值。

要从 postgresql.auto.conf 中删除参数字符串并重新加载服务器配置，您必须传递 value=default。使用 value=default 时，playbook 总是返回 changed 为 true。

属性

属性

支持

描述

check_mode

支持: 完全

可以在 check_mode 下运行，并返回 changed 状态预测，而无需修改目标。

注释

注意

  • 支持的 PostgreSQL 版本为 9.4 及更高版本。

  • 请注意，当实际没有任何更改时，使用 ‘postmaster’ 上下文更改设置可能会返回 changed 为 true，因为相同的值可能以几种不同的形式呈现，例如 1024MB、1GB 等。但是，在 pg_settings 系统视图中，它可以定义为 131072 个 8kB 页。由于服务器尚未重启，并且 pg_settings 中的值尚未更新，因此参数值的最终检查无法比较它。

  • 对于某些参数，需要重启 PostgreSQL 服务器。请参阅官方文档 https://postgresql.ac.cn/docs/current/view-pg-settings.html。

  • 默认身份验证假设您正在以主机上的 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_info

收集有关 PostgreSQL 服务器的信息。

PostgreSQL 服务器配置

有关 PostgreSQL 服务器配置的常规信息。

PostgreSQL 视图 pg_settings 参考

pg_settings 视图文档的完整参考。

PostgreSQL ALTER SYSTEM 命令参考

ALTER SYSTEM 命令文档的完整参考。

示例

- name: Restore wal_keep_segments parameter to initial state
  community.postgresql.postgresql_set:
    name: wal_keep_segments
    reset: true

# Set work_mem parameter to 32MB and show what's been changed and restart is required or not
# (output example: "msg": "work_mem 4MB >> 64MB restart_req: False")
- name: Set work mem parameter
  community.postgresql.postgresql_set:
    name: work_mem
    value: 32mb
  register: set

- name: Print the result if the setting changed
  ansible.builtin.debug:
    msg: "{{ set.name }} {{ set.prev_val_pretty }} >> {{ set.value_pretty }} restart_req: {{ set.restart_required }}"
  when: set.changed
# Ensure that the restart of PostgreSQL server must be required for some parameters.
# In this situation you see the same parameter in prev_val_pretty and value_pretty, but 'changed=True'
# (If you passed the value that was different from the current server setting).

- name: Set log_min_duration_statement parameter to 1 second
  community.postgresql.postgresql_set:
    name: log_min_duration_statement
    value: 1s

- name: Set wal_log_hints parameter to default value (remove parameter from postgresql.auto.conf)
  community.postgresql.postgresql_set:
    name: wal_log_hints
    value: default

- name: Set TimeZone parameter (careful, case sensitive)
  community.postgresql.postgresql_set:
    name: TimeZone
    value: 'Europe/Paris'

返回值

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

键

描述

context

字符串

PostgreSQL 设置上下文。

返回: 成功

示例: "user"

name

字符串

name

返回: 成功

示例: "shared_buffers"

prev_val_pretty

字符串

有关参数先前状态的信息。

返回: 成功

示例: "4MB"

queries

list / elements=string

在 community.postgresql 3.7.0 中添加

已执行的 DML 查询列表。

返回: 成功

示例: ["ALTER SYSTEM SET shared_preload_libraries = ''"]

restart_required

布尔值

有关参数当前状态的信息。

返回: 成功

示例: true

value

字典

一个字典，其中包含当前参数值（在 playbook 完成时）。

请注意，对于真正的更改，某些参数需要重启 PostgreSQL 服务器。

在检查模式下返回当前值。

返回: 成功

示例: {"unit": "b", "value": 67108864}

value_pretty

字符串

有关参数当前状态的信息。

返回: 成功

示例: "64MB"

作者

  • Andrew Klychkov (@Andersson007)

  • Daniele Giudice (@RealGreenDragon)