community.postgresql.postgresql_script 模块 – 从文件运行 PostgreSQL 语句

注意

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

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

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

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

community.postgresql 2.1.0 中的新增功能

概要 

从文件运行任意 PostgreSQL 语句。
该模块始终报告状态已更改。
请勿针对由 pg_dump、pg_dumpall、pg_restore 和其他 PostgreSQL 实用程序生成的文件运行该模块。
使用 community.postgresql.postgresql_db 并将 state=restore 用于运行由 pg_dump/pg_dumpall 生成的文件中的查询。

要求 

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

psycopg2 >= 2.5.1

参数 

参数	注释
ca_cert 别名：ssl_rootcert 字符串	指定包含 SSL 证书颁发机构 (CA) 证书的文件名。如果该文件存在，将验证服务器的证书是否由这些机构之一签名。
connect_params 字典在 community.postgresql 2.3.0 中添加	要传递给 libpg 的任何其他参数。这些参数具有优先权。默认值： `{}`
db 别名：login_db 字符串	要连接并运行查询的数据库的名称。
encoding 字符串	设置当前会话的客户端编码（例如 `UTF-8`）。默认值是数据库定义的编码。
login_host 别名：host 字符串	运行数据库的主机。如果在使用 `localhost` 时遇到连接问题，请尝试改用 `127.0.0.1`。默认值： `""`
login_password 字符串	此模块应用于建立其 PostgreSQL 会话的密码。默认值： `""`
login_unix_socket 别名：unix_socket 字符串	用于本地连接的 Unix 域套接字的路径。默认值： `""`
login_user 别名：login 字符串	此模块应用于建立其 PostgreSQL 会话的用户名。默认值： `"postgres"`
named_args 字典	键值参数的字典，用于替换文件内容中的变量占位符。当值是列表时，它将被转换为 PostgreSQL 数组。与 positional_args 互斥。
path path	目标计算机上 SQL 脚本的路径。要上传转储，首选方法是使用 community.postgresql.postgresql_db 模块并使用 state=restore。
port 别名：login_port 整数	要连接的数据库端口。默认值： `5432`
positional_args 列表 / elements=any	值的列表，用于替换文件内容中的变量占位符。当值是列表时，它将被转换为 PostgreSQL 数组。与 named_args 互斥。
search_path 列表 / 元素=字符串	覆盖用于搜索数据库对象的模式列表。
session_role 字符串	连接后切换到 `session_role`。指定的角色必须是当前 `login_user` 所属的角色。 SQL 命令的权限检查就像 `session_role` 最初登录一样执行。
ssl_cert path 在 community.postgresql 2.4.0 中添加	指定客户端 SSL 证书的文件名。
ssl_key path 在 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 布尔值	如果为 `false`，则检查 session_role 的值是否可能存在危险。仅当通过 session_role 可能发生 SQL 注入时，使用 `false` 才有意义。选项 `false` `true` ← (默认)

属性 

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

备注 

注意

默认身份验证假设您以主机上的 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_db: 从远程主机添加或删除 PostgreSQL 数据库。
community.postgresql.postgresql_query: 运行 PostgreSQL 查询。
PostgreSQL 模式参考: PostgreSQL 模式文档的完整参考。

示例 

# Assuming that the file contains
# SELECT * FROM id_talbe WHERE id = %s,
# '%s' will be substituted with 1
- name: Run query from SQL script using UTF-8 client encoding for session and positional args
  community.postgresql.postgresql_script:
    db: test_db
    path: /var/lib/pgsql/test.sql
    positional_args:
      - 1
    encoding: UTF-8

# Assuming that the file contains
# SELECT * FROM test WHERE id = %(id_val)s AND story = %(story_val)s,
# %-values will be substituted with 1 and 'test'
- name: Select query to test_db with named_args
  community.postgresql.postgresql_script:
    db: test_db
    path: /var/lib/pgsql/test.sql
    named_args:
      id_val: 1
      story_val: test

- block:
  # Assuming that the the file contains
  # SELECT * FROM test_array_table WHERE arr_col1 = %s AND arr_col2 = %s
  # Pass list and string vars as positional_args
  - name: Set vars
    ansible.builtin.set_fact:
      my_list:
      - 1
      - 2
      - 3
      my_arr: '{1, 2, 3}'
  - name: Passing positional_args as arrays
    community.postgresql.postgresql_script:
      path: /var/lib/pgsql/test.sql
      positional_args:
        - '{{ my_list }}'
        - '{{ my_arr|string }}'

# Assuming that the the file contains
# SELECT * FROM test_table,
# look into app1 schema first, then,
# if the schema doesn't exist or the table hasn't been found there,
# try to find it in the schema public
- name: Select from test using search_path
  community.postgresql.postgresql_script:
    path: /var/lib/pgsql/test.sql
    search_path:
    - app1
    - public

- block:
    # If you use a variable in positional_args/named_args that can
    # be undefined and you wish to set it as NULL, constructions like
    # "{{ my_var if (my_var is defined) else none | default(none) }}"
    # will not work as expected substituting an empty string instead of NULL.
    # If possible, we suggest using Ansible's DEFAULT_JINJA2_NATIVE configuration
    # (https://docs.ansible.org.cn/ansible/latest/reference_appendices/config.html#default-jinja2-native).
    # Enabling it fixes this problem. If you cannot enable it, the following workaround
    # can be used.
    # You should precheck such a value and define it as NULL when undefined.
    # For example:
    - name: When undefined, set to NULL
      set_fact:
        my_var: NULL
      when: my_var is undefined

    # Then, assuming that the file contains
    # INSERT INTO test_table (col1) VALUES (%s)
    - name: Insert a value using positional arguments
      community.postgresql.postgresql_script:
        path: /var/lib/pgsql/test.sql
        positional_args:
          - '{{ my_var }}'

返回值 

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

键	描述
query 字符串	执行的查询。当使用 `positional_args` 或 `named_args` 选项时，查询包含数据库连接器内部替换的所有变量。返回: 成功示例: `"SELECT * FROM bar"`
query_result 列表 / 元素=字典	以列：值形式表示返回行的字典列表。当脚本中有多个语句时，返回最后一个语句的结果。返回: 成功示例: `[{"Column": "Value1"}, {"Column": "Value2"}]`
rowcount 整数	生成或影响的行数。当脚本中有多个语句时，返回最后一个语句影响的行数。返回: 更改示例: `5`
statusmessage 字符串	包含数据库连接器在执行脚本内容后返回的消息的属性。当脚本中有多个语句时，返回与最后一个语句相关的消息。返回: 成功示例: `"INSERT 0 1"`

作者

Douglas J Hunley (@hunleyd)
1. Hart (@jtelcontar)
Daniel Scharon (@DanScharon)
Andrew Klychkov (@Andersson007)

community.postgresql.postgresql_script 模块 – 从文件运行 PostgreSQL 语句

作者

集合链接