Cassandra/Tools/cassandra-table-properties

Cassandra table and keyspace property configuration tool.
== Source Code ==
The project source code is maintained in Gerrit
* Project Page
== Overview/Motivation ==
Cassandra's DDL covers what is traditionally considered schema but also information that is more configuration in nature. For example, consider keyspace creation:
=== Keyspace Example ===
 CREATE KEYSPACE "globaldomain_T_mathoid__ng_mml" WITH replication = {'class': 'NetworkTopologyStrategy', 'codfw': '3', 'eqiad': '3'} AND durable_writes = true;
 -- \___________________________________________/ \________________________________________________________________________________________________________/
 -- | |
 -- schema configuration
A keyspace in Cassandra is a namespace to associate tables with (similar to a database in MySQL terminology). Here, globaldomain_T_mathoid__ng_mml is the keyspace, and everything that follows the WITH is configuration pertaining to associated tables (replication, or whether or not to make use of the commitlog).
It is similar with tables:
=== Table Example ===
Schema Portion
 CREATE TABLE "globaldomain_T_mathoid__ng_mml".data (
 "_domain" text,
 key text,
 headers text,
 tid timeuuid,
 value text,
 PRIMARY KEY (("_domain", key))
Configuration Portion
 ) WITH bloom_filter_fp_chance = 0.01
 AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
 AND comment = <nowiki></nowiki>
 AND compaction = {
 'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 
 'max_threshold': '32', 'min_threshold': '4'
 }
 AND compression = {
 'chunk_length_in_kb': '32', 
 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'
 }
 AND crc_check_chance = 1.0
 AND dclocal_read_repair_chance = 0.1
 AND default_time_to_live = 0
 AND gc_grace_seconds = 86400
 AND max_index_interval = 2048
 AND memtable_flush_period_in_ms = 0
 AND min_index_interval = 128
 AND read_repair_chance = 0.0
 AND speculative_retry = '99PERCENTILE';
Likewise, the DDL describes both schema, and table-specific configuration. In the example above, "globaldomain_T_mathoid__ng_mml".data is the table name, followed within the parenthesis by the names and types of the attributes. This is schema, as it models the data to be stored there. Everything that follows the WITH however, is configuration.
This is an important distinction (schema v configuration), because schema is determined by the application; No change in schema makes sense without a corresponding change to the application. Configuration however is site-specific, and operational in nature; Parameters can be unique to a use-case, and updated frequently outside of any change to the application. Schema is determined by application developers, configuration by users/operators.
----Unfortunately, it is colloquial to refer to the entire DDL for a keyspace and/or table as schema. However, every effort is made throughput this ticket to use the term schema to mean only that which determines the data model, and configuration to refer to the corresponding operational settings.
----
== Workflow ==
table-properties allows the user to create the YAML representation (via -d switch) of existing keyspaces and tables. When saved the configuration can be changed and then used as input for table-properties to generate the ALTER statements.
==== Sample YAML Output ====
 keyspaces:
 - durable_writes: true
 name: globaldomain_T_mathoid__ng_mml
 replication:
 class: SimpleStrategy
 replication_factor: 1
 tables:
 - bloom_filter_fp_chance: 0.01
 caching:
 keys: ALL
 rows_per_partition: NONE
 cdc: null
 comment: <nowiki></nowiki>
 compaction:
 class: SizeTieredCompactionStrategy
 max_threshold: 32
 min_threshold: 4
 compression:
 chunk_length_in_kb: 32
 class: LZ4Compressor
 crc_check_chance: 1.0
 dclocal_read_repair_chance: 0.1
 default_time_to_live: 0
 extensions: {}
 flags:
 - compound
 gc_grace_seconds: 86400
 id: 1de04a10-a409-11e9-94f8-6dbc19352e3a
 max_index_interval: 2048
 memtable_flush_period_in_ms: 0
 min_index_interval: 128
 name: data
 read_repair_chance: 0.0
 speculative_retry: 99PERCENTILE
== Installation ==
Python 3.4 or higher is required. Either clone the repo or download a zipped (release) version.
Install the dependencies with
 pip install -r requirements.txt
== Usage ==
From the command prompt, execute below to get help on available options
 table-properties -h
To write the current configuration as formatted YAML to stdout
 table-properties -d
Once you have an existing configuration, you can make changes to that YAML file and use it as an input file.
 table-properties <filename>
This generates ALTER statements if any differences between the configurations were detected. Use
 table-properties <filename> | cqlsh
to update Cassandra's configuration.
=== Changing Defaults and Using cqlshrc ===
If the server connection is different from the default values, in addition to the CLI switches, an existing cqlshrc file can be used to provide those settings.
 table-properties -r <cqlshrc filename>
==== Other switches ====
 -h, --help show this help message and exit
 -i <ip>, --ip <ip> Host IP address or name. Default: localhost
 -C <filename>, --clientcert <filename> Client cert file name.
 -d, --dump Dump current configuration to STDOUT
 -k <filename>, --clientkey <filename> Client key file name.
 -l <filename>, --log <filename> Log file name. If none is provied, STDERR is used.
 -p <port #>, --port <port #> Port number. Default: 9042
 -P, --password Prompt for password.
 -q, --quiet When the flag is set exit with 0 only if the 
 configuration matches the YAML file. Exit with
 code 1 otherwise.
 -r <filename>, --rcfile <filename> cqlrc file name. Default: ~/.cassandra/cqlshrc
 -s, --ssl Use SSL/TLS encryption for client server communication.
 -u <user name>, --username <user name> User name for plain text authentication.
 -v, --version Display version number and exit
</code>