community.postgresql.postgresql_db 模块 – 从远程主机添加或删除 PostgreSQL 数据库

注意

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

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

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

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

概要

• 从远程主机添加或删除 PostgreSQL 数据库。

要求

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

• psycopg2 >= 2.5.1

参数

参数	注释
ca_cert 别名：ssl_rootcert 字符串	指定包含 SSL 证书颁发机构 (CA) 证书的文件名。 如果文件存在，则会验证服务器的证书是否由此类机构签名。
comment 字符串 在 community.postgresql 3.3.0 中添加	设置数据库的注释。 要重置注释，请传递一个空字符串。
conn_limit 字符串	指定数据库连接限制。 默认值： ""
connect_params 字典 在 community.postgresql 2.3.0 中添加	要传递给 libpg 的任何其他参数。 这些参数优先。 默认值： {}
dump_extra_args 字符串 在 community.postgresql 0.2.0 中添加	当 state 为 dump 时提供额外的参数。 不能与 dump-file-format 相关的参数（如 ``--format=d``）一起使用。
encoding 字符串	数据库的编码。 默认值： ""
force 布尔值	当 state 为 absent 时，用于强制删除数据库，否则将被忽略。 选择 false ← (默认) true
icu_locale 字符串 在 community.postgresql 3.4.0 中添加	指定数据库默认排序顺序和字符分类的 ICU 区域设置 (ICU_LOCALE)，覆盖区域设置设置。 区域设置提供程序必须是 ICU。如果指定了区域设置，则默认值为区域设置设置；否则与模板数据库的设置相同。 默认值： ""
lc_collate 字符串	数据库中使用的排序顺序 (LC_COLLATE) 必须与模板数据库的排序顺序匹配，除非使用 template0 作为模板。 默认值： ""
lc_ctype 字符串	数据库中使用的字符分类 (LC_CTYPE)（例如，小写、大写、…）。 必须与模板数据库的 LC_CTYPE 匹配，除非使用 template0 作为模板。 默认值： ""
locale_provider 字符串 在 community.postgresql 3.4.0 中添加	指定用于此数据库中默认排序规则的提供程序 (LOCALE_PROVIDER)。 可能的值为 icu（如果服务器是使用 ICU 支持构建的）或 libc。 默认情况下，提供程序与模板的提供程序相同。 默认值： ""
login_host 别名：host 字符串	运行数据库的主机。 如果使用 localhost 时出现连接问题，请尝试改用 127.0.0.1。 默认值： ""
login_password 字符串	此模块应使用此密码来建立其 PostgreSQL 会话。 默认值： ""
login_unix_socket 别名：unix_socket 字符串	用于本地连接的 Unix 域套接字路径。 默认值： ""
login_user 别名：login 字符串	此模块应使用此用户名来建立其 PostgreSQL 会话。 默认值： "postgres"
maintenance_db 字符串	该值指定 Ansible 连接的初始数据库（也称为维护数据库）。 默认值： "postgres"
name 别名：db 字符串 / 必需	要添加或删除的数据库的名称。
owner 字符串	要设置为数据库所有者的角色的名称。 默认值： ""
port 别名：login_port 整数	数据库连接端口。 默认值： 5432
session_role 字符串	连接后切换到 session_role。 指定的 session_role 必须是当前登录用户所属的角色。 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 表示如果存在，应该删除数据库。 dump 需要一个目标定义，数据库将被备份到该目标。（在 Ansible 2.4 中添加）请注意，在某些 PostgreSQL 版本的 pg_dump 中（它是嵌入式 PostgreSQL 实用程序，由模块使用），即使发生错误（例如，连接被 pg_hba.conf 禁止等），也会返回 rc 0，因此模块返回 changed=True，但实际上并没有执行转储。请确保您的 pg_dump 版本在这种情况下返回 rc 1。 restore 也需要一个目标定义，数据库将从该目标还原。（在 Ansible 2.4 中添加）。 备份的格式将根据目标名称进行检测。 转储和还原支持的压缩格式由目标文件格式确定： .pgc (custom)、.bz2 (bzip2)、 .gz (gzip/pigz) 和 .xz (xz)。 转储和还原支持的格式由目标文件格式确定：.sql（plain）、 .tar (tar)、 .pgc (custom) 和 .dir (directory)。目录格式自集合版本 1.4.0 起支持。 还原程序根据目标文件格式选择：.tar、.pgc 和 .dir 由 pg_restore 处理，其他由 pgsql 处理。 . rename 用于将数据库 name 重命名为 target。 如果数据库 name 存在，它将被重命名为 target。 如果数据库 name 不存在，而 target 数据库存在，则模块将报告没有发生任何更改。 如果两个数据库都存在，或者它们具有相同的值，则会引发错误。 当 state=rename 时，除了 name 选项外，模块还需要 target 选项。其他选项将被忽略。自集合版本 1.4.0 起支持。 选择 "absent" "dump" "present" ← (默认) "rename" "restore"
tablespace 路径	为数据库设置的表空间，请参考 https://postgresql.ac.cn/docs/current/sql-alterdatabase.html。 如果要将数据库移回默认表空间，请显式设置为 pg_default。 默认值： ""
target 路径	备份或还原的文件。 当 state 为 dump 或 restore 时使用。 默认值： ""
target_opts 字符串	pg_dump 或还原程序（pg_restore 或 psql，具体取决于目标的格式）的附加参数。 当 state 为 dump 或 restore 时使用。 默认值： ""
template 字符串	用于创建数据库的模板。 默认值： ""
trust_input 布尔值 在 community.postgresql 0.2.0 中添加	如果为 false，则检查参数 owner、conn_limit、encoding、db、template、tablespace、session_role 的值是否可能存在危险。 只有当通过参数进行 SQL 注入的可能性时，才建议使用 false。 选择 false true ← (默认)

属性

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

说明

注意

• 自 ansible 版本 2.8 起，状态 dump 和 restore 不再需要 psycopg。

• 默认身份验证假设您以主机上的 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 软件包，然后才能使用此模块。

另请参阅

另请参阅

CREATE DATABASE 参考

CREATE DATABASE 命令文档的完整参考。

DROP DATABASE 参考

DROP DATABASE 命令文档的完整参考。

pg_dump 参考

pg_dump 文档的完整参考。

pg_restore 参考

pg_restore 文档的完整参考。

community.postgresql.postgresql_tablespace

从远程主机添加或删除 PostgreSQL 表空间。

community.postgresql.postgresql_info

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

community.postgresql.postgresql_ping

检查远程 PostgreSQL 服务器的可用性。

示例

- name: Create a new database with name "acme"
  community.postgresql.postgresql_db:
    name: acme
    comment: My test DB

# Note: If a template different from "template0" is specified,
# encoding and locale settings must match those of the template.
- name: Create a new database with name "acme" and specific encoding and locale # settings
  community.postgresql.postgresql_db:
    name: acme
    encoding: UTF-8
    lc_collate: de_DE.UTF-8
    lc_ctype: de_DE.UTF-8
    locale_provider: icu
    icu_locale: de-DE-x-icu
    template: template0

# Note: Default limit for the number of concurrent connections to
# a specific database is "-1", which means "unlimited"
- name: Create a new database with name "acme" which has a limit of 100 concurrent connections
  community.postgresql.postgresql_db:
    name: acme
    conn_limit: "100"

- name: Dump an existing database to a file
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/acme.sql

- name: Dump an existing database to a file excluding the test table
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/acme.sql
    dump_extra_args: --exclude-table=test

- name: Dump an existing database to a file (with compression)
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/acme.sql.gz

- name: Dump a single schema for an existing database
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/acme.sql
    target_opts: "-n public"

- name: Dump only table1 and table2 from the acme database
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/table1_table2.sql
    target_opts: "-t table1 -t table2"

- name: Dump an existing database using the directory format
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/acme.dir

- name: Dump an existing database using the custom format
  community.postgresql.postgresql_db:
    name: acme
    state: dump
    target: /tmp/acme.pgc

# name: acme - the name of the database to connect through which the recovery will take place
- name: Restore database using the tar format
  community.postgresql.postgresql_db:
    name: acme
    state: restore
    target: /tmp/acme.tar

# Note: In the example below, if database foo exists and has another tablespace
# the tablespace will be changed to foo. Access to the database will be locked
# until the copying of database files is finished.
- name: Create a new database called foo in tablespace bar
  community.postgresql.postgresql_db:
    name: foo
    tablespace: bar

# Rename the database foo to bar.
# If the database foo exists, it will be renamed to bar.
# If the database foo does not exist and the bar database exists,
# the module will report that nothing has changed.
# If both the databases exist, an error will be raised.
- name: Rename the database foo to bar
  community.postgresql.postgresql_db:
    name: foo
    state: rename
    target: bar

返回值

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

键	描述
executed_commands list / elements=string 在 community.postgresql 0.2.0 中添加	尝试运行的命令列表。 返回值： 成功 示例： ["CREATE DATABASE acme"]

作者

• Ansible 核心团队

集合链接

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