community.clickhouse.clickhouse_db module – Creates or removes a ClickHouse database using the clickhouse-driver Client interface

Note

This module is part of the community.clickhouse collection (version 2.1.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_db.

New in community.clickhouse 0.3.0

Synopsis
Requirements
Parameters
Attributes
Notes
Examples
Return Values

Synopsis

Creates or removes a ClickHouse database using the clickhouse-driver Client interface.

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 added in community.clickhouse 0.4.0	Run the command on all cluster hosts. If the cluster is not configured, the command will crash with an error.
comment string added in community.clickhouse 0.4.0	Database comment. Once set, cannot be changed.
engine string	Database engine. Once set, cannot be changed.
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	Database name to add or remove.
state string	Database state. If `present`, will create the database if not exists. If `absent`, will drop the database if exists. If `rename`, will rename the database if exists. Choices: `"present"` ← (default) `"absent"` `"rename"`
target string added in community.clickhouse 0.4.0	Name for renaming the database.

Attributes

Attribute	Support	Description
check_mode	Support: full	Supports check_mode.

Notes

Note

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

Examples

- name: Create database
  community.clickhouse.clickhouse_db:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_db
    engine: Memory
    state: present
    comment: Test DB

- name: Drop database
  community.clickhouse.clickhouse_db:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_db
    state: absent

# Rename the database test_db to prod_db.
# If the database test_db exists, it will be renamed to prod_db.
# If the database test_db does not exist and the prod_db database exists,
# the module will report that nothing has changed.
# If both the databases exist, an error will be raised.
- name: Rename database
  community.clickhouse.clickhouse_db:
    login_host: localhost
    login_user: alice
    login_db: foo
    login_password: my_password
    name: test_db
    target: prod_db
    cluster: test_cluster
    state: rename

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 DATABASE test_db"]`

Authors

Andrew Klychkov (@Andersson007)
Aleksandr Vagachev (@aleksvagachev)

Collection links

© 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/clickhouse/clickhouse_db_module.html