community.clickhouse.clickhouse_named_collection module – Creates, removes or modify a ClickHouse named collection using the clickhouse-driver Client interface

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_named_collection.

New in community.clickhouse 2.2.0

Synopsis

  • Creates, remove or modify a ClickHouse named collection using the clickhouse-driver Client interface.

  • The module can only work if login_user will have necessary grants.

  • An existing named collection can be modified only if server is properly configured and user is allowed to view secrets. There is an option to rewrite whole secret, but then it will not be idempotent.

  • Module is supported only on version 25.8 or later.

Requirements

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

  • clickhouse-driver

Parameters

Parameter

Comments

client_kwargs

dictionary

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

Default: {}

cluster

string

Run the command on all cluster hosts.

If the cluster is not configured, the command will crash with an error.

collection

list / elements=dictionary

Content of named collection.

name

string / required

Name of secret.

value

string / required

Content of secret.

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.

name

string / required

Named collection name to add or remove.

rewrite

boolean

Force to rewrite secret. It has only use when viewing secrets is disabled and user can’t fetch secrets values.

If user can view secret values it will be fully idempotent. Will only alter collection if it differs.

Choices:

  • false ← (default)

  • true

state

string

Named collection state.

If present, will create or modify the named collection.

If absent, will drop the named collection if exists.

Choices:

  • "present" ← (default)

  • "absent"

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

Supports check_mode.

idempotent

Support: full

At second run will not change anything.

If login_user doesn’t have proper privileges, the module can’t determine if the collection differs.

rewrite still will be idempotent if login_user has privileges to display collection content.

Notes

Note

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

Examples

- name: Create named collection with 2 secrets
  community.clickhouse.clickhouse_named_collection:
    name: test_col
    collection:
      - name: user
        value: alice
      - name: password
        value: test_pass

- name: Create named collection with forcing rewrite
  community.clickhouse.clickhouse_named_collection:
    name: test_col
    collection:
      - name: user
        value: alice
      - name: password
        value: test_pass
    rewrite: true

- name: Drop named collection
  community.clickhouse.clickhouse_named_collection:
    name: test_col
    state: absent

Return Values

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

Key

Description

executed_statements

list / elements=string

Data-modifying executed statements.

Returned: on success

Sample: ["CREATE NAMED COLLECTION `test_col` AS `user` = %(val_0)s, `password` = %(val_1)s"]

query_parameters

list / elements=string

Query parameters passed to query from executed_statements.

Returned: on succes

Sample: [{"val_0": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER", "val_1": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER"}]

Authors

  • Rafal Kozlowski (@rkozlo)