DivConq Framework

This article provides instructions to download, install and run two major components (one client, one server) of the Cassandra database on your Windows system.

If you do not know what Cassandra is, please read my earlier article on this subject first.

Prerequisites

Cassandra is written in Java.  Please make sure you have installed Java version 6 or a more recent version before proceeding.

Installing Java also usually sets up proper values of the JAVA_HOME and PATH environment variables.  If you see complaints about “JAVA_HOME” or you see errors like “‘java’ is not recognized as an internal or external command”, please see the “JAVA_HOME and PATH Environment Variables” section near the bottom of this article.

Downloading and Expanding Cassandra

Download a package of Cassandra binary-format programs from http://cassandra.apache.org/download/.

Save this file as “apache-cassandra-0.6.3-bin.tar.gz” (with the version number set appropriately).

Unpack this *.tar.gz file using PeaZip or your favorite archive utility into a new folder of your choice.  I used a new folder called “C:\Work\apache-cassandra-0.6.3″.  Your unpacked files should look like this in Windows Explorer:

Running the Cassandra Server

Open up a command-line window.  Run this command so you’ll be able to tell which window is running the client and which is running the server later:

TITLE CassServer

CD into your “C:\Work\apache-cassandra-0.6.3″ folder, type “bin\cassandra” and hit “Enter”.  Behind the scenes this kicks off a batch file (remember, this is a Java application) that checks to make sure you’ve done your homework on the prerequisites and then attempts to launch the server.

If all goes well, you will see something like this.

Note that the Cassandra server will NOT return to the command prompt if it started up successfully. If you see a “Cassandra starting up…” message (without a return to the command prompt), leave the server be and try running the Cassandra client.

Running the Cassandra Client

Open up a command-line window. Run this command so you’ll be able to tell which window is running the client and which is running the server later:

TITLE CassClient

CD into your “C:\Work\apache-cassandra-0.6.3″ folder, type “bin\cassandra-cli -host localhost -port 9160″ and hit “Enter”. Behind the scenes this kicks off a batch file (remember, this is a Java application) that checks to make sure you’ve done your homework on the prerequisites and then attempts to launch the server.

If all goes well, you will see something like this.

Yes, it’s an interactive command prompt – that’s exactly what we were hoping for.

Trying Some Easy Commands

I’ll cover how to actually store and retrieve data in a future article, but let’s at least make sure our client is really talking to our server. Run the following three commands to ask the server to return some basic information about the Cassandra server environment to your Cassandra client.

Unlike relational databases like SQL Server, Cassandra doesn’t organize all its structures and data into “databases” – instead it uses a similar concept called “keyspaces”.

To list all the keyspaces on your new Cassandra server, run the following command.

This server has two keyspaces: a built-in “system” keyspace which contains information about this Cassandra server node’s current state and a user keyspace called “Keyspace1″ that holds data you can insert or read.

Now there’s no “boss key” with Cassandra, so you’ll also need to know how to shut everything down in case you’re trying this on the job at a SQL Server shop. ;)

Shutting Down

To shut down the Cassandra server, go to your “CassServer” window and hit “Ctrl+C”. Answer “y” when asked if you want to terminate the batch file.

To quit the Cassandra command-line client, go to your “CassClient” window and type “exit” at the command prompt. (“Ctrl+C” won’t work here.)

Next Steps: Adding and Retrieving Data

If all is well, please proceed to my article about how to add and retrieve data from your new Cassandra database system.

Troubleshooting

If you get a “NoClassDefFoundError” message which trying to start either the Cassandra client or server, please see my earlier article on that subject.

If you get a “Not connected to a cassandra instance.” message while using the Cassandra client, you probably forgot to specify “-host localhost -port 9160″ on the command line.

JAVA_HOME and PATH Environment Variables

Cassandra’s applications (and many other Java applications) need an environment variable called “JAVA_HOME” defined in order to run.  If you only run a single version of Java on your system, you will probably want to set the value of this environment variable at the system level to something like “C:\Program Files\Java\jre6″ or “C:\Sun\SDK\jdk” (no “bin”, no “lib” – this is just the home directory).

You should also make sure that any Java application you start from the command-line can find its necessary libraries by setting the PATH environment variable appropriately.  If you only run a single version of Java on your system, you may need to APPEND to the value of the PATH environment variable at the system level.  Your appended values will be something like “;C:\Program Files\Java\jre6\bin\” or “C:\Sun\SDK\bin” (don’t point to just the home directory here).

On my Windows systems I often have multiple versions of Java installed so I use an extremely short Windows batch called “prepforjava.bat” which contains two lines to set these environment variables as needed:

SET PATH=%PATH%;C:\Program Files\Java\jre6\bin
SET JAVA_HOME=C:\Program Files\Java\jre6

This batch file is stored in another folder also referenced by my system-level PATH environment variable so I can call it from any command-line window at any time.

About Jonathan Lampe

Author of 43 articles on this blog.

I have about 12 years of experience designing secure, partially distributed systems (e.g., web farm with some extra load in one remote data center), often in industries such as finance and defense. My solutions and software are currently deployed in mission-critical roles at about 1000 enterprises worldwide. In the last 2-3 years I have turned my technical attention toward more geographically distributed systems and heterogeneous environments (e.g., a mix of operating systems or on-premises and cloud deployments) while maintaining my focus on good UX and great security.

• Click here to visit author's personal website.
• Twitter

Published on Monday July 05, 2010 at 09:34am