Quick Start
Welcome to the world of Apache Cassandra! In this first chapter, we will briefly introduce Cassandra, along with a quick, step-by-step process to get your own single-node cluster up and running. Even if you already have experience working with Cassandra, this chapter will help to provide assurance that you are building everything properly. If this is your first foray into Cassandra, then get ready to take your first steps into a larger world.
In this chapter, we will cover the following topics:
- Introduction to Cassandra
- Installation and configuration
- Starting up and shutting down Cassandra
- Cassandra Cluster Manager (CCM)
By the end of this chapter, you will have built a single-node cluster of Apache Cassandra. This will be a good exercise to help you start to see some of the configuration and thought that goes into building a larger cluster. As this chapter progresses and the material gets more complex, you will start to connect the dots and understand exactly what is happening between installation, operation, and development.
Introduction to Cassandra
Apache Cassandra is a highly available, distributed, partitioned row store. It is one of the more popular NoSQL databases used by both small and large companies all over the world to store and efficiently retrieve large amounts of data. While there are licensed, proprietary versions available (which include enterprise support), Cassandra is also a top-level project of the Apache Software Foundation, and has deep roots in the open source community. This makes Cassandra a proven and battle-tested approach to scaling high-throughput applications.
High availability
Cassandra's design is premised on the points outlined in the Dynamo: Amazon's Highly Available Key-value Store paper (https://www.allthingsdistributed.com/files/amazon-dynamo-sosp2007.pdf). Specifically, when you have large networks of interconnected hardware, something is always in a state of failure. In reality, every piece of hardware being in a healthy state is the exception, rather than the rule. Therefore, it is important that a data storage system is able to deal with (and account for) issues such as network or disk failure.
Depending on the Replication Factor (RF) and required consistency level, a Cassandra cluster is capable of sustaining operations with one or two nodes in a failure state. For example, let's assume that a cluster with a single data center has a keyspace configured for a RF of three. This means that the cluster contains three copies of each row of data. If an application queries with a consistency level of one, then it can still function properly with one or two nodes in a down state.
Distributed
Cassandra is known as a distributed database. A Cassandra cluster is a collection of nodes (individual instances running Cassandra) all working together to serve the same dataset. Nodes can also be grouped together into logical data centers. This is useful for providing data locality for an application or service layer, as well as for working with Cassandra instances that have been deployed in different regions of a public cloud.
Cassandra clusters can scale to suit both expanding disk footprint and higher operational throughput. Essentially, this means that each cluster becomes responsible for a smaller percentage of the total data size. Assuming that the 500 GB disks of a six node cluster (RF of three) start to reach their maximum capacity, then adding three more nodes (for a total of nine) accomplishes the following:
- Brings the total disk available to the cluster up from 3 TB to 4.5 TB
- The percentage of data that each node is responsible for drops from 50% down to 33%
Additionally, let's assume that before the expansion of the cluster (from the prior example), the cluster was capable of supporting 5,000 operations per second. Cassandra scales linearly to support operational throughput. After increasing the cluster from six nodes to nine, the cluster should then be expected to support 7,500 operations per second.
Partitioned row store
In Cassandra, rows of data are stored in tables based on the hashed value of the partition key, called a token. Each node in the cluster is assigned multiple token ranges, and rows are stored on nodes that are responsible for their tokens.
Each keyspace (collection of tables) can be assigned a RF. The RF designates how many copies of each row should be stored in each data center. If a keyspace has a RF of three, then each node is assigned primary, secondary, and tertiary token ranges. As data is written, it is written to all of the nodes that are responsible for its token.
Installation
To get started with Cassandra quickly, we'll step through a single-node, local installation.
The following are the requirements to run Cassandra locally:
- A flavor of Linux or macOS
- A system with between 4 GB and 16 GB of random access memory (RAM)
- A local installation of the Java Development Kit (JDK) version 8, latest patch
- A local installation of Python 2.7 (for cqlsh)
- Your user must have sudo rights to your local system
Head to the Apache download site for the Cassandra project (http://cassandra.apache.org/download/), choose 3.11.2, and select a mirror to download the latest version of Cassandra. When complete, copy the .tar or .gzip file to a location that your user has read and write permissions for. This example will assume that this is going to be the ~/local/ directory:
mkdir ~/local
cd ~/local
cp ~/Downloads/apache-cassandra-3.11.2-bin.tar.gz .
Untar the file to create your cassandra directory:
tar -zxvf apache-cassandra-3.11.2-bin.tar.gz
Some people prefer to rename this directory, like so:
mv apache-cassandra-3.11.2/ cassandra/
Configuration
At this point, you could start your node with no further configuration. However, it is good to get into the habit of checking and adjusting the properties that are indicated as follows.
cassandra.yaml
It is usually a good idea to rename your cluster. Inside the conf/cassandra.yaml file, specify a new cluster_name property, overwriting the default Test Cluster:
cluster_name: 'PermanentWaves'
The num_tokens property default of 256 has proven to be too high for the newer, 3.x versions of Cassandra. Go ahead and set that to 24:
num_tokens: 24
To enable user security, change the authenticator and authorizer properties (from their defaults) to the following values:
authenticator: PasswordAuthenticator
authorizer: CassandraAuthorizer
By default, Cassandra will come up bound to localhost or 127.0.0.1. For your own local development machine, this is probably fine. However, if you want to build a multi-node cluster, you will want to bind to your machine's IP address. For this example, I will use 192.168.0.101. To configure the node to bind to this IP, adjust the listen_address and rpc_address properties:
listen_address: 192.168.0.101
rpc_address: 192.168.0.101
If you set listen_address and rpc_address, you'll also need to adjust your seed list (defaults to 127.0.0.1) as well:
seeds: 192.168.0.101
I will also adjust my endpoint_snitch property to use GossipingPropertyFileSnitch:
endpoint_snitch: GossipingPropertyFileSnitch
cassandra-rackdc.properties
In terms of NoSQL databases, Apache Cassandra handles multi-data center awareness better than any other. To configure this, each node must use GossipingPropertyFileSnitch (as previously mentioned in the preceding cassandra.yaml configuration process) and must have its local data center (and rack) settings defined. Therefore, I will set the dc and rack properties in the conf/cassandra-rackdc.properties file:
dc=ClockworkAngels
rack=R40
Starting Cassandra
To start Cassandra locally, execute the Cassandra script. If no arguments are passed, it will run in the foreground. To have it run in the background, send the -p flag with a destination file for the Process ID (PID):
cd cassandra
bin/cassandra -p cassandra.pid
This will store the PID of the Cassandra process in a file named cassandra.pid in the local/cassandra directory. Several messages will be dumped to the screen. The node is successfully running when you see this message:
Starting listening for CQL clients on localhost/192.168.0.101:9042 (unencrypted).
This can also be verified with the nodetool status command:
bin/nodetool status
Datacenter: ClockworkAngels
===========================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address Load Tokens Owns (effective) Host ID Rack
UN 192.168.0.101 71.26 KiB 24 100.0% 0edb5efa... R40
Cassandra Cluster Manager
If you want an even faster way to install Cassandra, you can use an open source tool called CCM. CCM installs Cassandra for you, with very minimal configuration. In addition to ease of installation, CCM also allows you to run multiple Cassandra nodes locally.
First, let's clone the CCM repository from GitHub, and cd into the directory:
git clone https://github.com/riptano/ccm.git
cd ccm
Next, we'll run the setup program to install CCM:
sudo ./setup.py install
To verify that my local cluster is working, I'll invoke nodetool status via node1:
ccm node1 status
Datacenter: datacenter1
=======================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address Load Tokens Owns (effective) Host ID Rack
UN 127.0.0.1 100.56 KiB 1 66.7% 49ecc8dd... rack1
UN 127.0.0.2 34.81 KiB 1 66.7% 404a8f97... rack1
UN 127.0.0.3 34.85 KiB 1 66.7% eed33fc5... rack1
To shut down your cluster, go ahead and send the stop command to each node:
ccm stop node1
ccm stop node2
ccm stop node3
Note that CCM requires a working installation of Python 2.7 or later, as well as a few additional libraries (pyYAML, six, ant, and psutil), and local IPs 127.0.0.1 through 127.0.0.3 to be available. Visit https://github.com/riptano/ccm for more information.
A quick introduction to the data model
Now that we have a Cassandra cluster running on our local machine, we will demonstrate its use with some quick examples. We will start with cqlsh, and use that as our primary means of working with the Cassandra data model.
Using Cassandra with cqlsh
To start working with Cassandra, let's start the Cassandra Query Language (CQL) shell . The shell interface will allow us to execute CQL commands to define, query, and modify our data. As this is a new cluster and we have turned on authentication and authorization, we will use the default cassandra and cassandra username and password, as follows:
bin/cqlsh 192.168.0.101 -u cassandra -p cassandra
Connected to PermanentWaves at 192.168.0.101:9042.
[cqlsh 5.0.1 | Cassandra 3.11.2 | CQL spec 3.4.4 | Native protocol v4]
Use HELP for help.
cassandra@cqlsh>
First, let's tighten up security. Let's start by creating a new superuser to work with.
New users can only be created if authentication and authorization are properly set in the cassandra.yaml file:
cassandra@cqlsh> CREATE ROLE cassdba WITH PASSWORD='flynnLives' AND LOGIN=true and SUPERUSER=true;
Now, set the default cassandra user to something long and indecipherable. You shouldn't need to use it ever again:
cassandra@cqlsh> ALTER ROLE cassandra WITH PASSWORD='dsfawesomethingdfhdfshdlongandindecipherabledfhdfh';
Then, exit cqlsh using the exit command and log back in as the new cassdba user:
cassandra@cqlsh> exit
bin/cqlsh 192.168.0.101 -u cassdba -p flynnLives
Connected to PermanentWaves at 192.168.0.101:9042.
[cqlsh 5.0.1 | Cassandra 3.11.2 | CQL spec 3.4.4 | Native protocol v4]
Use HELP for help.
cassdba@cqlsh>
Now, let's create a new keyspace where we can put our tables, as follows:
cassdba@cqlsh> CREATE KEYSPACE packt WITH replication =
{'class': 'NetworkTopologyStrategy', 'ClockworkAngels': '1'}
AND durable_writes = true;
With the newly created keyspace, let's go ahead and use it:
cassdba@cqlsh> use packt;
cassdba@cqlsh:packt>
Now, let's assume that we have a requirement to build a table for video game scores. We will want to keep track of the player by their name, as well as their score and game on which they achieved it. A table to store this data would look something like this:
CREATE TABLE hi_scores (name TEXT, game TEXT, score BIGINT,
PRIMARY KEY (name,game));
Next, we will INSERT data into the table, which will help us understand some of Cassandra's behaviors:
INSERT INTO hi_scores (name, game, score) VALUES ('Dad','Pacman',182330);
INSERT INTO hi_scores (name, game, score) VALUES ('Dad','Burgertime',222000);
INSERT INTO hi_scores (name, game, score) VALUES ('Dad','Frogger',15690);
INSERT INTO hi_scores (name, game, score) VALUES ('Dad','Joust',48150);
INSERT INTO hi_scores (name, game, score) VALUES ('Connor','Pacman',182330);
INSERT INTO hi_scores (name, game, score) VALUES ('Connor','Monkey Kong',15800);
INSERT INTO hi_scores (name, game, score) VALUES ('Connor','Frogger',4220);
INSERT INTO hi_scores (name, game, score) VALUES ('Connor','Joust',48850);
INSERT INTO hi_scores (name, game, score) VALUES ('Avery','Galaga',28880);
INSERT INTO hi_scores (name, game, score) VALUES ('Avery','Burgertime',1200);
INSERT INTO hi_scores (name, game, score) VALUES ('Avery','Frogger',1100);
INSERT INTO hi_scores (name, game, score) VALUES ('Avery','Joust',19520);
Now, let's execute a CQL query to retrieve the scores of the player named Connor:
cassdba@cqlsh:packt> SELECT * FROM hi_scores WHERE name='Connor';
name | game | score
--------+-------------+--------
Connor | Frogger | 4220
Connor | Joust | 48850
Connor | Monkey Kong | 15800
Connor | Pacman | 182330
(4 rows)
That works pretty well. But what if we want to see how all of the players did while playing the Joust game, as follows:
cassdba@cqlsh:packt> SELECT * FROM hi_scores WHERE game='Joust';
InvalidRequest: Error from server: code=2200 [Invalid query] message="Cannot execute this query as it might involve data filtering and thus may have unpredictable performance. If you want to execute this query despite the performance unpredictability, use ALLOW FILTERING"
Evidently, Cassandra has some problems with that query. We'll discuss more about why that is the case later on. But, for now, let's build a table that specifically supports querying high scores by game:
CREATE TABLE hi_scores_by_game (name TEXT, game TEXT, score BIGINT,
PRIMARY KEY (game,score)) WITH CLUSTERING ORDER BY (score DESC);
Now, we will duplicate our data into our new query table:
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Dad','Pacman',182330);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Dad','Burgertime',222000);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Dad','Frogger',15690);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Dad','Joust',48150);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Connor','Pacman',182330);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Connor','Monkey Kong',15800);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Connor','Frogger',4220);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Connor','Joust',48850);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Avery','Galaga',28880);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Avery','Burgertime',1200);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Avery','Frogger',1100);
INSERT INTO hi_scores_by_game (name, game, score) VALUES ('Avery','Joust',19520);
Now, let's try to query while filtering on game with our new table:
cassdba@cqlsh:packt> SELECT * FROM hi_scores_by_game
WHERE game='Joust';
game | score | name
-------+-------+--------
Joust | 48850 | Connor
Joust | 48150 | Dad
Joust | 19520 | Avery
(3 rows)
As mentioned previously, the following chapters will discuss why and when Cassandra only allows certain PRIMARY KEY components to be used in the WHERE clause. The important thing to remember at this point is that in Cassandra, tables and data structures should be modeled according to the queries that they are intended to serve.
Shutting down Cassandra
Before shutting down your cluster instances, there are some additional commands that should be run. Again, with your own, local node(s), these are not terribly necessary. But it is a good idea to get used to running these, should you ever need to properly shut down a production node that may contain data that people actually care about.
First, we will disable gossip. This keeps other nodes from communicating with the node while we are trying to bring it down:
bin/nodetool disablegossip
Next, we will disable the native binary protocol to keep this node from serving client requests:
bin/nodetool disablebinary
Then, we will drain the node. This will prevent it from accepting writes, and force all in-memory data to be written to disk:
bin/nodetool drain
With the node drained, we can kill the PID:
kill 'cat cassandra.pid'
We can verify that the node has stopped by tailing the log:
tail logs/system.log
INFO [RMI TCP Connection(2)-127.0.0.1] 2018-03-31 17:49:05,789 StorageService.java:2292 - Node localhost/192.168.0.101 state jump to shutdown
INFO [RMI TCP Connection(4)-127.0.0.1] 2018-03-31 17:49:49,492 Server.java:176 - Stop listening for CQL clients
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:11,312 StorageService.java:1449 - DRAINING: starting drain process
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:11,313 HintsService.java:220 - Paused hints dispatch
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:11,314 Gossiper.java:1540 - Announcing shutdown
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:11,314 StorageService.java:2292 - Node localhost/192.168.0.101 state jump to shutdown
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:13,315 MessagingService.java:984 - Waiting for messaging service to quiesce
INFO [ACCEPT-localhost/192.168.0.101] 2018-03-31 17:50:13,316 MessagingService.java:1338 - MessagingService has terminated the accept() thread
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:14,764 HintsService.java:220 - Paused hints dispatch
INFO [RMI TCP Connection(6)-127.0.0.1] 2018-03-31 17:50:14,861 StorageService.java:1449 - DRAINED
Summary
In this chapter, we introduced Apache Cassandra and some of its design considerations and components. These aspects were discussed and a high level description of each was given, as well as how each affects things like cluster layout and data storage. Additionally, we built our own local, single-node cluster. CCM was also introduced, with minimal discussion. Some basic commands with Cassandra's nodetool were introduced and put to use.
With a single-node cluster running, the cqlsh tool was introduced. We created a keyspace that will work in a plural data center configuration. The concept of query tables was also introduced, as well as running some simple read and write operations.
In the next chapter, we will take an in-depth look at Cassandra's underlying architecture, and understand what is key to making good decisions about cluster deployment and data modeling. From there, we'll discuss various aspects to help fine-tune a production cluster and its deployment process. That will bring us to monitoring and application development, and put you well on your way to mastering Cassandra!