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) 证书的文件的名称。如果文件存在，则服务器的证书将被验证是否由这些机构之一签名。
注释字符串在 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` 时，提供其他参数。不能与与转储文件格式相关的参数（如 ``–format=d``）一起使用。
encoding 字符串	数据库的编码。默认值： `""`
force 布尔值	当 state 为 `absent` 时强制删除数据库，否则忽略。选项 `false` ← (默认) `true`
icu_locale 字符串在 community.postgresql 3.4.0 中添加。	指定数据库默认排序顺序和字符分类的 ICU 区域设置 (ICU_LOCALE)，覆盖 locale 设置。区域设置提供程序必须是 ICU。如果指定了默认值，则为 locale 的设置；否则与模板数据库的设置相同。默认值： `""`
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"`
名称别名：db 字符串 / 必填	要添加或删除的数据库名称。
所有者字符串	设置为数据库所有者的角色名称。默认值： `""`
端口别名：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 默认值匹配。选项 `"允许"` `"禁用"` `"prefer"` ← (默认) `"需要"` `"验证-ca"` `"验证-完整"`
状态字符串	数据库状态。 `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`（自定义）、`.bz2`（bzip2）、`.gz`（gzip/pigz）和 `.xz`（xz）确定的转储和恢复支持的压缩格式。由目标文件格式 `.sql`（普通）、`.tar`（tar）、`.pgc`（自定义）和 `.dir`（目录）确定的转储和恢复支持的格式。对于自集合版本 1.4.0 起支持的目录格式。恢复程序由目标文件格式选择：`.tar`、`.pgc` 和 `.dir` 由 pg_restore 处理，其他由 pgsql 处理。 . `rename` 用于将数据库 `name` 重命名为 `target`。如果数据库 `name` 存在，它将被重命名为 `target`。如果数据库 `name` 不存在并且 `target` 数据库存在，模块将报告没有任何更改。如果两个数据库都存在以及它们的值相同时，将引发错误。当 state=rename 时，除了 `name` 选项外，模块还需要 `target` 选项。其他选项将被忽略。自集合版本 1.4.0 起支持。选项 `"不存在"` `"转储"` `"present"` ← (默认) `"重命名"` `"恢复"`
表空间路径	为数据库设置的表空间 https://postgresql.ac.cn/docs/current/sql-alterdatabase.html。如果要将数据库移回默认表空间，请明确将其设置为 pg_default。默认值： `""`
目标路径	备份或从中恢复的文件。当 state 为 `dump` 或 `restore` 时使用。默认值： `""`
target_opts 字符串	pg_dump 或恢复程序（pg_restore 或 psql，取决于目标的格式）的其他参数。当 state 为 `dump` 或 `restore` 时使用。默认值： `""`
模板字符串	用于创建数据库的模板。默认值： `""`
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 列表 / 元素=字符串在 community.postgresql 0.2.0 中添加。	尝试运行的命令列表。已返回：成功示例：`["CREATE DATABASE acme"]`

作者

Ansible 核心团队

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

作者

集合链接