Flask-CQLAlchemy handles connections to Cassandra clusters and gives a unified easier way to declare models and their columns


$ pip install flask-cqlalchemy


As such Flask-CQLAlchemy depends only on the cassandra-driver. It is assumed that you already have flask installed.

Flask-CQLAlchemy has been tested with versions 2.6.0, 2.7.2, 3.0.0, 3.1.0, 3.1.1, 3.2.0 and 3.2.1 of cassandra-driver. It is known to work with all versions >=2.5, but use it at your own risk. All previous versions of Flask-CQLAlchemy are deprecated.


import uuid
from flask import Flask
from flask.ext.cqlalchemy import CQLAlchemy

app = Flask(__name__)
app.config['CASSANDRA_HOSTS'] = ['']
app.config['CASSANDRA_KEYSPACE'] = "cqlengine"
db = CQLAlchemy(app)

class User(db.Model):
    uid = db.columns.UUID(primary_key=True, default=uuid.uuid4)
    username = db.columns.Text(required=False)


Start a python shell

>>from example_app import db, User
>>user1 = User.create(username='John Doe')

For a complete list of available method refer to the cqlengine Model documentation

Configuration Options

CQLAlchemy provides all the option available in the cqlengine connection.setup() method

  • CASSANDRA_HOSTS - A list of hosts
  • CASSANDRA_KEYSPACE - The default keyspace to use
  • CASSANDRA_CONSISTENCY - The global default ConsistencyLevel
  • CASSANDRA_LAZY_CONNECT - True if should not connect until first use
  • CASSANDRA_RETRY_CONNECT - True if we should retry to connect even if there was a connection failure initially
  • CASSANDRA_SETUP_KWARGS - Pass-through keyword arguments for Cluster()


CQLAlchemy provides some helper methods for Cassandra database management

sync_db() - Creates/Syncs all the tables corresponding to the models declared in the application

set_keyspace() - Sets the keyspace for a session. Keyspaces once set will remain the default keyspace for the duration of the session. If the change is temporary, it must be reverted back to the default keyspace explicitly.