salt.modules.cassandra_cql¶

Cassandra Database Module

This module works with Cassandra v2 and v3 and hence generates queries based on the internal schema of said version.

depends:

DataStax Python Driver for Apache Cassandra https://github.com/datastax/python-driver pip install cassandra-driver

referenced by:

Salt's cassandra_cql returner

configuration:

The Cassandra cluster members and connection port can either be specified in the master or minion config, the minion's pillar or be passed to the module.

Example configuration in the config for a single node:

cassandra:
  cluster: 192.168.50.10
  port: 9000

Example configuration in the config for a cluster:

cassandra:
  cluster:
    - 192.168.50.10
    - 192.168.50.11
    - 192.168.50.12
  port: 9000
  username: cas_admin

Changed in version 2016.11.0.

Added support for ssl_options and protocol_version.

Example configuration with ssl options:

If ssl_options are present in cassandra config the cassandra_cql returner will use SSL. SSL isn't used if ssl_options isn't specified.

cassandra:
  cluster:
    - 192.168.50.10
    - 192.168.50.11
    - 192.168.50.12
  port: 9000
  username: cas_admin

  ssl_options:
    ca_certs: /etc/ssl/certs/ca-bundle.trust.crt

    # SSL version should be one from the ssl module
    # This is an optional parameter
    ssl_version: PROTOCOL_TLSv1

Additionally you can also specify the protocol_version to use.

cassandra:
  cluster:
    - 192.168.50.10
    - 192.168.50.11
    - 192.168.50.12
  port: 9000
  username: cas_admin

  # defaults to 4, if not set
  protocol_version: 3

Also all configuration could be passed directly to module as arguments.

salt minion1 cassandra_cql.info contact_points=delme-nextgen-01 port=9042 cql_user=cassandra cql_pass=cassandra protocol_version=4

salt minion1 cassandra_cql.info ssl_options='{"ca_certs": /path/to/-ca.crt}'

We can also provide the load balancing policy as arguments

salt minion1 cassandra_cql.cql_query "alter user cassandra with password 'cassandra2' ;" contact_points=scylladb cql_user=user1 cql_pass=password port=9142 protocol_version=4 ssl_options='{"ca_certs": path-to-client-ca.crt}' load_balancing_policy=DCAwareRoundRobinPolicy load_balancing_policy_args='{"local_dc": "datacenter1"}'

salt.modules.cassandra_cql.cql_query(query, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Run a query on a Cassandra cluster and return a dictionary.

Parameters:

• query (str) -- The query to execute.

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• params (str) -- The parameters for the query, optional.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

A dictionary from the return values of the query

Return type:

list[dict]

CLI Example:

salt 'cassandra-server' cassandra_cql.cql_query "SELECT * FROM users_by_name WHERE first_name = 'jane'"

salt.modules.cassandra_cql.cql_query_with_prepare(query, statement_name, statement_arguments, asynchronous=False, callback_errors=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None, **kwargs)¶

Run a query on a Cassandra cluster and return a dictionary.

This function should not be used asynchronously for SELECTs -- it will not return anything and we don't currently have a mechanism for handling a future that will return results.

Parameters:

• query (str) -- The query to execute.

• statement_name (str) -- Name to assign the prepared statement in the __context__ dictionary

• statement_arguments (list[str]) -- Bind parameters for the SQL statement

• asynchronous (bool) -- Run this query in asynchronous mode

• async (bool) -- Run this query in asynchronous mode (an alias to 'asynchronous') NOTE: currently it overrides 'asynchronous' and it will be dropped in version 3001!

• callback_errors (Function callable) -- Function to call after query runs if there is an error

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• params (str) -- The parameters for the query, optional.

• protocol_version -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

A dictionary from the return values of the query

Return type:

list[dict]

CLI Example:

# Insert data asynchronously
salt this-node cassandra_cql.cql_query_with_prepare "name_insert" "INSERT INTO USERS (first_name, last_name) VALUES (?, ?)"             statement_arguments=['John','Doe'], asynchronous=True

# Select data, should not be asynchronous because there is not currently a facility to return data from a future
salt this-node cassandra_cql.cql_query_with_prepare "name_select" "SELECT * FROM USERS WHERE first_name=?"             statement_arguments=['John']

salt.modules.cassandra_cql.create_keyspace(keyspace, replication_strategy='SimpleStrategy', replication_factor=1, replication_datacenters=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Create a new keyspace in Cassandra.

Parameters:

• keyspace (str) -- The keyspace name

• replication_strategy (str) -- either SimpleStrategy or NetworkTopologyStrategy

• replication_factor (int) -- number of replicas of data on multiple nodes. not used if using NetworkTopologyStrategy

• replication_datacenters (str | dict[str, int]) -- string or dict of datacenter names to replication factors, required if using NetworkTopologyStrategy (will be a dict if coming from state file).

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The info for the keyspace or False if it does not exist.

Return type:

dict

CLI Example:

# CLI Example:
salt 'minion1' cassandra_cql.create_keyspace keyspace=newkeyspace

salt 'minion1' cassandra_cql.create_keyspace keyspace=newkeyspace replication_strategy=NetworkTopologyStrategy         replication_datacenters='{"datacenter_1": 3, "datacenter_2": 2}'

salt.modules.cassandra_cql.create_user(username, password, superuser=False, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Create a new cassandra user with credentials and superuser status.

Parameters:

• username (str) -- The name of the new user.

• password (str) -- The password of the new user.

• superuser (bool) -- Is the new user going to be a superuser? default: False

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

Return type:

CLI Example:

salt 'minion1' cassandra_cql.create_user username=joe password=secret

salt 'minion1' cassandra_cql.create_user username=joe password=secret superuser=True

salt 'minion1' cassandra_cql.create_user username=joe password=secret superuser=True contact_points=minion1

salt.modules.cassandra_cql.drop_keyspace(keyspace, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Drop a keyspace if it exists in a Cassandra cluster.

Parameters:

• keyspace (str) -- The keyspace to drop.

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The info for the keyspace or False if it does not exist.

Return type:

dict

CLI Example:

salt 'minion1' cassandra_cql.drop_keyspace keyspace=test

salt 'minion1' cassandra_cql.drop_keyspace keyspace=test contact_points=minion1

salt.modules.cassandra_cql.grant_permission(username, resource=None, resource_type='keyspace', permission=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Grant permissions to a user.

Parameters:

• username (str) -- The name of the user to grant permissions to.

• resource (str) -- The resource (keyspace or table), if None, permissions for all resources are granted.

• resource_type (str) -- The resource_type (keyspace or table), defaults to 'keyspace'.

• permission (str) -- A permission name (e.g. select), if None, all permissions are granted.

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

Return type:

CLI Example:

salt 'minion1' cassandra_cql.grant_permission

salt 'minion1' cassandra_cql.grant_permission username=joe resource=test_keyspace permission=select

salt 'minion1' cassandra_cql.grant_permission username=joe resource=test_table resource_type=table         permission=select contact_points=minion1

salt.modules.cassandra_cql.info(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Show the Cassandra information for this cluster.

Parameters:

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The information for this Cassandra cluster.

Return type:

dict

CLI Example:

salt 'minion1' cassandra_cql.info

salt 'minion1' cassandra_cql.info contact_points=minion1

salt.modules.cassandra_cql.keyspace_exists(keyspace, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Check if a keyspace exists in a Cassandra cluster.

:param keyspace The keyspace name to check for. :type keyspace: str :param contact_points: The Cassandra cluster addresses, can either be a string or a list of IPs. :type contact_points: str | list[str] :param cql_user: The Cassandra user if authentication is turned on. :type cql_user: str :param cql_pass: The Cassandra user password if authentication is turned on. :type cql_pass: str :param port: The Cassandra cluster port, defaults to None. :type port: int :param protocol_version: Cassandra protocol version to use. :type protocol_version: int :param load_balancing_policy: cassandra.policy class name to use :type load_balancing_policy: str :param load_balancing_policy_args: cassandra.policy constructor args :type load_balancing_policy_args: dict :param ssl_options: Cassandra protocol version to use. :type ssl_options: dict :return: The info for the keyspace or False if it does not exist. :rtype: dict

CLI Example:

salt 'minion1' cassandra_cql.keyspace_exists keyspace=system

salt.modules.cassandra_cql.list_column_families(keyspace=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

List column families in a Cassandra cluster for all keyspaces or just the provided one.

Parameters:

• keyspace (str) -- The keyspace to provide the column families for, optional.

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The column families in this Cassandra cluster.

Return type:

list[dict]

CLI Example:

salt 'minion1' cassandra_cql.list_column_families

salt 'minion1' cassandra_cql.list_column_families contact_points=minion1

salt 'minion1' cassandra_cql.list_column_families keyspace=system

salt.modules.cassandra_cql.list_keyspaces(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

List keyspaces in a Cassandra cluster.

Parameters:

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The keyspaces in this Cassandra cluster.

Return type:

list[dict]

CLI Example:

salt 'minion1' cassandra_cql.list_keyspaces

salt 'minion1' cassandra_cql.list_keyspaces contact_points=minion1 port=9000

salt.modules.cassandra_cql.list_permissions(username=None, resource=None, resource_type='keyspace', permission=None, contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

List permissions.

Parameters:

• username (str) -- The name of the user to list permissions for.

• resource (str) -- The resource (keyspace or table), if None, permissions for all resources are listed.

• resource_type (str) -- The resource_type (keyspace or table), defaults to 'keyspace'.

• permission (str) -- A permission name (e.g. select), if None, all permissions are listed.

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

Dictionary of permissions.

Return type:

dict

CLI Example:

salt 'minion1' cassandra_cql.list_permissions

salt 'minion1' cassandra_cql.list_permissions username=joe resource=test_keyspace permission=select

salt 'minion1' cassandra_cql.list_permissions username=joe resource=test_table resource_type=table           permission=select contact_points=minion1

salt.modules.cassandra_cql.list_users(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

List existing users in this Cassandra cluster.

Parameters:

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• port (int) -- The Cassandra cluster port, defaults to None.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The list of existing users.

Return type:

dict

CLI Example:

salt 'minion1' cassandra_cql.list_users

salt 'minion1' cassandra_cql.list_users contact_points=minion1

salt.modules.cassandra_cql.version(contact_points=None, port=None, cql_user=None, cql_pass=None, protocol_version=None, load_balancing_policy=None, load_balancing_policy_args=None, ssl_options=None)¶

Show the Cassandra version.

Parameters:

• contact_points (str | list[str]) -- The Cassandra cluster addresses, can either be a string or a list of IPs.

• cql_user (str) -- The Cassandra user if authentication is turned on.

• cql_pass (str) -- The Cassandra user password if authentication is turned on.

• port (int) -- The Cassandra cluster port, defaults to None.

• protocol_version (int) -- Cassandra protocol version to use.

• load_balancing_policy (str) -- cassandra.policy class name to use

• load_balancing_policy_args (dict) -- cassandra.policy constructor args

• ssl_options (dict) -- Cassandra protocol version to use.

Returns:

The version for this Cassandra cluster.

Return type:

str

CLI Example:

salt 'minion1' cassandra_cql.version

salt 'minion1' cassandra_cql.version contact_points=minion1