community.clickhouse.clickhouse_script module – Run SQL queries from a file

Note

This module is part of the community.clickhouse collection (version 2.2.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.clickhouse. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.clickhouse.clickhouse_script.

New in community.clickhouse 2.2.0

Synopsis

  • This module allows to execute SQL queries from files.

  • Queries has to be separated with ;

  • Module uses sqlglot for parsing file.

  • Module uses server side parametrization. Ex {d:Date}, {id:String}.

Requirements

The below requirements are needed on the host that executes this module.

  • clickhouse-driver

  • sqlglot

Parameters

Parameter

Comments

client_kwargs

dictionary

Any additional keyword arguments you want to pass to the Client interface when instantiating its object.

Default: {}

login_db

string

The same as the Client(database='...') argument.

If not passed, relies on the driver’s default argument value.

login_host

string

The same as the Client(host='...') argument.

Default: "localhost"

login_password

string

The same as the Client(password='...') argument.

If not passed, relies on the driver’s default argument value.

login_port

integer

The same as the Client(port='...') argument.

If not passed, relies on the driver’s default argument value.

login_user

string

The same as the Client(user='...') argument.

If not passed, relies on the driver’s default argument value.

Be sure your the user has permissions to read the system tables listed in the RETURN section.

parameters

dictionary

Parameters to pass to substitute in script.

Note module uses server side parametrization.

path

string / required

Path to a SQL file to execute.

success_on

list / elements=integer

added in community.clickhouse 2.2.0

List of server error codes that will be treated as success, otherwise throw errors.

Default: [497]

Attributes

Attribute

Support

Description

check_mode

Support: full

In check mode executed_statements and query_parameters will be set, but none queire will be sent to database.

idempotency

Support: none

Always changed=True.

Notes

Note

  • See the clickhouse-driver documentation for more information about the driver interface.

Examples

- name: Execute plain sql script
  community.clickhouse.clickhouse_script:
    path: test_file.sql

- name: Execute sql script with parametrization
  community.clickhouse.clickhouse_script:
    path: test_file.sql
    parameters:
      d: "2026-05-19"
      c: "cl"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

custom_message

dictionary

Queries that was successfully executed in case if one of them fail. Normally, executed queries are returned via executed_statements.

Returned: on failure

Sample: {"success_queries": ["SELECT 1", "SELECT 1"]}

executed_statements

list / elements=string

Queries executed from file. In case of failure, queries executed prior to the failed one are returned via custom_message.

Returned: on success

Sample: ["CREATE DATABASE IF NOT EXISTS test_db", "SELECT 1 FROM test_db WHERE b = {a:String}"]

query_parameters

list / elements=string

Query parameters passed to server.

Returned: on success

Sample: [{"a": "cl", "d": "2026-05-19"}]

Authors

  • Rafal Kozlowski (@rkozlo)