Модуль community.postgresql.postgresql_query — выполнение запросов PostgreSQL

Примечание

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

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

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

Чтобы использовать модуль в плейбуке, укажите: community.postgresql.postgresql_query.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Выполняет произвольные запросы PostgreSQL.

Требования

На узле, на котором выполняется этот модуль, должны быть установлены следующие компоненты.

psycopg2 >= 2.5.1

Параметры

Параметр	Комментарии
autocommit логический	Выполнять в режиме autocommit, если запрос нельзя выполнить внутри блока транзакции (например, VACUUM). Несовместимо с check_mode. Варианты: `false` ← (по умолчанию) `true`
ca_cert псевдонимы: ssl_rootcert строка	Указывает имя файла, содержащего сертификат или сертификаты центра сертификации (CA) SSL. Если файл существует, будет проверено, что сертификат сервера подписан одним из этих центров сертификации.
connect_params словарь добавлено в community.postgresql 2.3.0	Любые дополнительные параметры, передаваемые в libpg. Эти параметры имеют приоритет. По умолчанию: `{}`
encoding строка добавлено в community.postgresql 0.2.0	Задаёт кодировку клиента для текущего сеанса (например, `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.
positional_args список / элементы=любые	Список значений, передаваемых запросу в качестве позиционных аргументов. Если значение является списком, оно будет преобразовано в массив PostgreSQL. Несовместимо с named_args.
query любой	Строка SQL-запроса или список запросов для выполнения. Переменные можно экранировать с помощью синтаксиса psycopg: https://www.psycopg.org/psycopg3/docs/basic/params.html.
search_path список / элементы=строка добавлено в community.postgresql 1.0.0	Список имён схем для поиска.
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://www.postgresql.org/docs/current/static/libpq-ssl.html. Значение по умолчанию `prefer` соответствует значению по умолчанию libpq. Варианты: `"allow"` `"disable"` `"prefer"` ← (по умолчанию) `"require"` `"verify-ca"` `"verify-full"`
trust_input логический добавлено в community.postgresql 0.2.0	Если `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 — адаптер Python для баз данных PostgreSQL. Перед использованием модуля необходимо убедиться, что на узле установлен psycopg2 >= 2.5.1 или psycopg3 >= 3.1.8.
Если удалённый узел является сервером PostgreSQL (что используется по умолчанию), PostgreSQL также должен быть установлен на удалённом узле.
В системах на базе Ubuntu перед использованием этого модуля установите на удалённый узел пакеты postgresql, libpq-dev и python3-psycopg2.

См. также

community.postgresql.postgresql_script: Выполнение инструкций PostgreSQL из файла.
community.postgresql.postgresql_db: Добавление или удаление баз данных PostgreSQL на удалённом узле.
Справочник по схемам PostgreSQL: Полный справочник по документации схем PostgreSQL.

Примеры

- name: Simple select query to acme db
  community.postgresql.postgresql_query:
    login_db: acme
    query: SELECT version()

# The result of each query will be stored in query_all_results return value
- name: Run several queries against acme db
  community.postgresql.postgresql_query:
    login_db: acme
    query:
    - SELECT version()
    - SELECT id FROM accounts

- name: Select query to db acme with positional arguments and non-default credentials
  community.postgresql.postgresql_query:
    login_db: acme
    login_user: django
    login_password: mysecretpass
    query: SELECT * FROM acme WHERE id = %s AND story = %s
    positional_args:
    - 1
    - test

- name: Select query to test_db with named_args
  community.postgresql.postgresql_query:
    login_db: test_db
    query: SELECT * FROM test WHERE id = %(id_val)s AND story = %(story_val)s
    named_args:
      id_val: 1
      story_val: test

- name: Insert query to test_table in db test_db
  community.postgresql.postgresql_query:
    login_db: test_db
    query: INSERT INTO test_table (id, story) VALUES (2, 'my_long_story')

- name: Use connect_params to add any additional connection parameters that libpg supports
  community.postgresql.postgresql_query:
    connect_params:
      target_session_attrs: read-write
      connect_timeout: 10
    login_host: "host1,host2"
    login_user: "test"
    login_password: "test1234"
    login_db: "test"
    query: 'insert into test (test) values (now())'

- name: Example of using autocommit parameter
  community.postgresql.postgresql_query:
    login_db: test_db
    query: VACUUM
    autocommit: true

- name: >
    Insert data to the column of array type using positional_args.
    Note that we use quotes here, the same as for passing JSON, etc.
  community.postgresql.postgresql_query:
    query: INSERT INTO test_table (array_column) VALUES (%s)
    positional_args:
    - '{1,2,3}'

# 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: Select from test table by passing positional_args as arrays
  community.postgresql.postgresql_query:
    query: SELECT * FROM test_array_table WHERE arr_col1 = %s AND arr_col2 = %s
    positional_args:
    - '{{ my_list }}'
    - '{{ my_arr|string }}'

# Select from test table looking 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_query:
    query: SELECT * FROM test_array_table
    search_path:
    - app1
    - public

# If you use a variable in positional_args / named_args that can
# be undefined and you wish to set it as NULL, the 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 to use 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:
- name: Insert a value using positional arguments
  community.postgresql.postgresql_query:
    query: INSERT INTO test_table (col1) VALUES (%s)
    positional_args:
    - '{{ my_var }}'

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже приведены поля, уникальные для этого модуля:

Ключ	Описание
execution_time_ms список / элементы=строка добавлено в community.postgresql 3.10.0	Список, содержащий время выполнения каждого запроса в миллисекундах. Измерения выполняются непосредственно перед передачей запроса драйверу для выполнения и сразу после неё. Возвращается: при успешном выполнении Пример: `[7104]`
query строка	Выполненный запрос. При чтении нескольких запросов из файла содержит только последний запрос. Возвращается: при успешном выполнении Пример: `"SELECT * FROM bar"`
query_all_results список / элементы=список	Список, содержащий результаты всех выполненных запросов (для каждого запроса предусмотрен отдельный вложенный список). Возвращается: при успешном выполнении Пример: `[[{"Column": "Value1"}, {"Column": "Value2"}], [{"Column": "Value1"}, {"Column": "Value2"}]]`
query_list список / элементы=строка	Список выполненных запросов. Возвращается: при успешном выполнении Пример: `["SELECT * FROM foo", "SELECT * FROM bar"]`
query_result список / элементы=словарь	Список словарей в формате «столбец: значение», представляющих возвращённые строки. При выполнении запросов из файла возвращает результат последнего запроса. Возвращается: при успешном выполнении Пример: `[{"Column": "Value1"}, {"Column": "Value2"}]`
rowcount целое число	Количество созданных или затронутых строк. При использовании скрипта с несколькими запросами содержит общее количество созданных или затронутых строк. Возвращается: при внесении изменений Пример: `5`
statusmessage строка	Атрибут, содержащий сообщение, возвращённое командой. При чтении нескольких запросов из файла содержит сообщение для последнего запроса. Возвращается: при успешном выполнении Пример: `"INSERT 0 1"`

Авторы

Felix Archambault (@archf)
Andrew Klychkov (@Andersson007)
Will Rouesnel (@wrouesnel)

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

© 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_query_module.html