Модуль community.postgresql.postgresql_script — запуск инструкций PostgreSQL из файла

Примечание

Этот модуль входит в коллекцию community.postgresql (версия 4.2.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.postgresql. Для использования этого модуля необходимы дополнительные требования; подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: 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 строка	Указывает имя файла, содержащего сертификат(ы) удостоверяющего центра (CA) SSL. Если файл существует, будет проверено, что сертификат сервера подписан одним из этих центров.
connect_params словарь добавлено в community.postgresql 2.3.0	Любые дополнительные параметры, передаваемые в libpg. Эти параметры имеют приоритет. По умолчанию: `{}`
encoding строка	Задаёт кодировку клиента для текущего сеанса (например, `UTF-8`). По умолчанию используется кодировка, заданная для базы данных.
login_db псевдонимы: db строка	Имя базы данных, к которой нужно подключиться и выполнить запросы. Псевдоним `db` устарел и будет удалён в версии 5.0.0.
login_host псевдонимы: host строка	Узел, на котором запущена база данных. Если при использовании `localhost` возникают проблемы с подключением, попробуйте вместо него использовать `127.0.0.1`. По умолчанию: `""`
login_password строка	Пароль, который модуль должен использовать для создания сеанса PostgreSQL. По умолчанию: `""`
login_port псевдонимы: port целое число	Порт базы данных для подключения. Псевдоним `port` устарел и будет удалён в следующем основном выпуске. Вместо него используйте `login_port`. По умолчанию: `5432`
login_unix_socket псевдонимы: unix_socket строка	Путь к сокету домена Unix для локальных подключений. По умолчанию: `""`
login_user псевдонимы: login строка	Имя пользователя, которое модуль должен использовать для создания сеанса PostgreSQL. По умолчанию: `"postgres"`
named_args словарь	Словарь аргументов «ключ-значение» для подстановки переменных вместо заполнителей в содержимом файла. Если значение является списком, оно будет преобразовано в массив PostgreSQL. Несовместим с positional_args.
path путь	Путь к SQL-скрипту на целевой машине. Для загрузки дампов предпочтительно использовать модуль community.postgresql.postgresql_db с параметром state=restore.
positional_args список / элементы=любые	Список значений для подстановки переменных вместо заполнителей в содержимом файла. Если значение является списком, оно будет преобразовано в массив PostgreSQL. Несовместим с named_args.
search_path список / элементы=строка	Переопределяет список схем, в которых выполняется поиск объектов базы данных.
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 строка	Определяет, будет ли согласовано безопасное TCP/IP-подключение SSL к серверу и, если будет, с каким приоритетом. Дополнительные сведения о режимах см. в https://www.postgresql.org/docs/current/static/libpq-ssl.html. Значение по умолчанию `prefer` соответствует значению по умолчанию libpq. Варианты: `"allow"` `"disable"` `"prefer"` ← (по умолчанию) `"require"` `"verify-ca"` `"verify-full"`
trust_input логический	Если `false`, проверяет, не является ли значение session_role потенциально опасным. Использовать `false` имеет смысл только в том случае, если возможны SQL-инъекции через session_role. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: нет	Может работать в режиме check_mode и возвращать прогноз изменения состояния без изменения целевого узла.

Примечания

Примечание

По умолчанию предполагается, что вы входите в систему как учётная запись postgres на узле или переключаетесь на неё с помощью sudo.
Чтобы избежать ошибки “Peer authentication failed for user postgres”, используйте пользователя postgres в качестве become_user.
Этот модуль использует psycopg — адаптер базы данных PostgreSQL для Python. Перед использованием модуля необходимо убедиться, что на узле установлено 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:
    login_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:
    login_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.com/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)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/postgresql/postgresql_script_module.html