cassandra is one of the most popular open source nosql databases, but it’s only a few years old, and therefore tools support is still limited, especially when it comes to free open source software.

if you are working with cassandra, sooner or later you will have to analyse its content on a remote cluster. most of the available tools are desktop applications that connect to cassandra over its protocol. getting such access might be a hard task, because usually databases are installed in restricted networks in order to minimize data breach risk. security policies are changing frequently to cover new findings, and the fact that you have access to your database today does not necessarily mean that it will last long.

gaining access over ssh and the command line interface should be easier, but i do not have to convince anyone that using a terminal to query database content is painful, especially when it holds wide rows!

but there is one solution that is almost always available: web based applications! every company knows how to secure them, how to run penetration tests, locate security leaks, and so on…. actually it does not matter what happens behind the scenes.  you, the end user, always has access to such an application – at least in theory.

here comes the good news: cyclop is 100% web based, and it’s based on the latest wicket release! once you’ve managed to install it, you can query your database from a web browser and still enjoy native application feeling (it’s almost fully based on ajax, so page reloads are rare).

there is also another cool thing: if your security experts will run penetration tests against cyclop they will come up with findings like database script injection. this will be the first time in your life when you can honestly say: “it’s not a bug, it’s a future!”. anyway –  i would suggest to restrict access to cyclop to some trusted networks. it’s definitely not a usual web application, but once you have managed to deploy it, you can enjoy simple access to your data over cql.

user management

cyclop does not manage users – it passes authorization and authentication to cassandra. once a cassandra session has been opened, it’s being stored in an http session, and that’s it. from now on, each query will be passed to cassandra over its active session, and the result is successful or not – based on access rights defined in cassandra for this particular user.

providing support for persistent data like query history gets a bit tricky if there is no such thing as user. we could reference the credentials used to open the cassandra session, but it’s a common use case that many users share them – like “read only user for it on third floor”.

as you might have noticed, the uuid is a solution to all our problems, and this time it worked too! cyclop generates a random cookie based on uuid and stores it in the browser. this is the replacement solution for missing user management. we do not recognize the user itself, but the browser. of course a valid cassandra session is always required, so it’s not possible that an unauthorized user could access restricted data (like query history) only because he has access to the browser, or “knows” the cookie value, he would have to log in in the first place.

user preferences cover things like the amount of rows in the result table, import settings or button state. those are stored in the browser as a cookie in json format. firstly, there is no security issue, because it’s not sensitive data,  secondly we can access it directly from javascript.

query editor

query completion

• completion is supported for almost the whole cql 3 syntax
• completion hint shows all possible keywords that are valid for the actual query position. tables, keyspaces and columns are grouped together and sorted. groups are also highlighted with a different font color
• if the keyspace has been set in the previous query (“use cqldemo” in the screen shot below), the completion for the following queries will be narrowed to tables from this keyspace, assuming that the keyspace is not explicitly provided in the query
• completion contains only tables that belong to the keyspace provided in the current query
• completion contains only columns of a table that has been provided in current query
• query syntax help has been copied from the cassandra documentation. it is decorated with color highlighting matching the completion hint colors
• 

keyboard navigation

• enter – confirms currently highlighted completion
• tab – next completion value
• ctrl+enter – executes query
• esc – cancel completion

query results table

• the results table is column-oriented, it’s reversed when compared to traditional sql editors – rows are displayed horizontally, and columns vertically. when scrolling the page from left to right you will switch between rows. scrolling from top to bottom shows the follow-up columns
• columns are displayed in the order returned by the query, but in addition they are grouped into two sections divided by a blue separator line. the top of the table contains “static columns” – their values are not empty in multiple rows returned by the executed query. the second section contains columns, whose value is non-empty only for a single row. cassandra supports dynamic columns, and the idea is to have “static” columns at the top of the table, and “dynamic” ones at the bottom, because those are mostly empty
• the table header for each row displays the partition key value, assuming the query returns it
• long text is trimmed in order to fit into table cells. such cells have a blue icon in the left top corner. clicking on it opens a pop-up containing the whole text

query history

• the history contains the last 500 queries that have been successfully executed from this particular browser (we recognize users based on persistent cookies)
• each entry in the history contains the query itself, the runtime and response size
• next to the query there is a blue icon. clicking on it will trigger a redirect to the editor and paste the query into it, so you can execute it again

history filtering

• the filter supports live update – you get results while typing. just remember that words shorter than three characters will be ignored
• multiple keywords are joined by or.  this means that the filter result will contain queries with at least one keyword
• pressing enter resets the filter (you can also click on the “clean” icon)
• you can specify multiple keywords in the filter. is such case the top of the filtered history will contain queries with most hits. this builds groups, like queries with four hits, then three, and in the end those with a single hit. the queries within those groups are sorted by execution time

data on the server

the history itself is stored on server in the file: [filestore.folder]\queryhistory-[user-uuid].json. the file itself contains the serialized history in json form. the solution is also secure, so you can use cyclop from any computer without restrictions. a random cookie is the only information stored in the browser – but this does not matter, because the history can be viewed only by authenticated users.

export

query results can be exported to a csv file. you can influence its format trough a configuration file

import

it’s meant to import files containing cql queries separated by ;\n. a single query can span multiple lines. results of the import are displayed in a table which contains each single query, the runtime and eventually an error – in this case the row is highlighted in red. you can also specify a few options, so that script execution will break (or not) after the first error, or executed queries can be included in the query history, or parallel import. the last option will divide the import file into chunks (6 by default) and execute each one in a separated thread. be aware that queries will be executed in unspecified order.

installation

1. download the last release: https://github.com/maciejmiklas/cyclop/releases/latest
2. edit the property file: cyclop/src/main/resources/cyclop.properties and set connection settings for cassandra

cassandra.hosts: localhost
cassandra.port: 9042
cassandra.usessl: false
cassandra.timeoutmilis: 3600000

1. you can also overwrite each property from cyclop.properties by setting it as jvm parameter. for example to connect to a different cassandra host set: -dcassandra.hosts=server1,server2 . this gives you a simple possibility to change properties after the war file has been assembled.

2. optionally change logger settings by editing logback.xml . by default it logs to /var/lib/tomcat7/logs/cyclop-${time}.log
3. build war file: mvn package
4. drop war file into tomcat

the created war can connect only to one cassandra cluster. in order to serve multiple clusters from one tomcat you have to deploy a few cyclop war archives, each one with a different cassandra.hosts value

technical details

the project can be found on github: https://github.com/maciejmiklas/cyclop

it’s based on the following technologies:

• web app – v3.x
• maven – v3.x
• spring – v3.x
• wicket – v6.x
• wicket-auth-roles – v6.x
• bootstrap – v3.x (theme: cyborg from bootswatch)
• jquery ui – v1.10.x
• cassandra-driver-core – v1.x
• slf4j/logback – v1.7.x
• hibernate validator – v4.x
• guava – v15.x (cassandra 2.0 does not work with v16)

live demo

there is a demo deployment of cyclop, so that you can get a first impression. i’m hosting it at home, so it can be down sometimes because i have no static ip, and when it changes propagation takes some time.

different links below contain different queries. clicking on a link will open cyclop and paste into its editor the query from the link. try to edit those queries using cyclop’s editor to see how the code completion is working. the provided user has read-only access, so only part of the functionality is available.

• user: democasusr, password: cassandra123 written backwards (32…ac)
• http://maciejmiklas.no-ip.biz/cyclop
• http://maciejmiklas.no-ip.biz/cyclop/main/ced?cql=select%20*%20from%20cqldemo.mybooks
• http://maciejmiklas.no-ip.biz/cyclop/main/ced?cql=select%20id%2cauthors%2cgenre%20from%20cqldemo.mybooks%20where%20pages%20%3d%20121
• http://maciejmiklas.no-ip.biz/cyclop/main/ced?cql=select%20id%2cauthors%20from%20cqldemo.mybooks%20where%20id%3d6ff12f41-cfb1-45ff-9e89-fb20f95ffc5d
• http://maciejmiklas.no-ip.biz/cyclop/main/ced?cql=select%20*%20from%20system.schema_columnfamilies