Swift Cassandra Client

CassandraClient is a Cassandra client in Swift. The client is based on DataStax Cassandra C++ Driver, wrapping it with Swift friendly APIs and data structures.

CassandraClient API currently exposes SwiftNIO based futures to simplify integration with SwiftNIO based servers. Swift concurrency based API is also available in Swift 5.5 and newer.

Usage

Swift concurrency based API

Creating a client instance

var configuration = CassandraClient.Configuration(...)
let cassandraClient = CassandraClient(configuration: configuration)

The client has a default session established (lazily) so that it can be used directly to perform queries on the configured keyspace:

let result = try await cassandraClient.query(...)

The client must be explicitly shut down when no longer needed:

try cassandraClient.shutdown()

Creating a session for a different keyspace

let session = cassandraClient.makeSession(keyspace: <KEYSPACE>)
let result = try await session.query(...)

The session must be explicitly shut down when no longer needed:

try session.shutdown()

You can also create a session and pass in a closure, which will automatically release the resource when the closure exits:

try await cassandraClient.withSession(keyspace: <KEYSPACE>) { session in
  ...
}

Running result-less commands (e.g. insert, update, delete or DDL)

try await cassandraClient.run("create table ...")

Or at session level:

try await session.run("create table ...")

Running queries returning small datasets that fit in memory

Returning a model object, having Model: Codable:

let result: [Model] = try await cassandraClient.query("select * from table ...")

let result: [Model] = try await session.query("select * from table ...")

Or using free-form transformations on the row:

let values = try await cassandraClient.query("select * from table ...") { row in
  row.column(<COLUMN_NAME>).int32
}

let values = try await session.query("select * from table ...") { row in
  row.column(<COLUMN_NAME>).int32
}

Running queries returning large datasets that do not fit in memory

// `rows` is a sequence that one needs to iterate on
let rows: Rows = try await cassandraClient.query("select * from table ...")

// `rows` is a sequence that one needs to iterate on
let rows: Rows = try await session.query("select * from table ...")

SwiftNIO future based API

Creating a client instance

var configuration = CassandraClient.Configuration(...)
let cassandraClient = CassandraClient(configuration: configuration)

The client has a default session established (lazily) so that it can be used directly to perform queries on the configured keyspace:

let resultFuture = cassandraClient.query(...)

The client must be explicitly shut down when no longer needed:

try cassandraClient.shutdown()

Creating a session for a different keyspace

let session = cassandraClient.makeSession(keyspace: <KEYSPACE>)
let resultFuture = session.query(...)

The session must be explicitly shut down when no longer needed:

try session.shutdown()

You can also create a session and pass in a closure, which will automatically release the resource when the closure exits:

try cassandraClient.withSession(keyspace: <KEYSPACE>) { session in
  ...
}

Running result-less commands (e.g. insert, update, delete or DDL)

let voidFuture = cassandraClient.run("create table ...")

Or at session level:

let voidFuture = session.run("create table ...")

Running queries returning small datasets that fit in memory

Returning a model object, having Model: Codable:

cassandraClient.query("select * from table ...").map { result: [Model] in
  ...
}

session.query("select * from table ...").map { result: [Model] in
  ...
}

Or using free-form transformations on the row:

cassandraClient.query("select * from table ...") { row in
  row.column(<COLUMN_NAME>).int32
}.map { value in
  ...
}

session.query("select * from table ...") { row in
  row.column(<COLUMN_NAME>).int32
}.map { value in
  ...
}

Running queries returning large datasets that do not fit in memory

cassandraClient.query("select * from table ...").map { rows: Rows in
  // `rows` is a sequence that one needs to iterate on
  rows.map { row in
    ...
  }
}

session.query("select * from table ...").map { rows: Rows in
  // `rows` is a sequence that one needs to iterate on
  rows.map { row in
    ...
  }
}

DataStax Driver and libuv

The library depends on the DataStax driver and libuv, which are included as git submodules. Both of them have source files that are excluded in Package.swift.

DataStax driver

The git submodule is under Sources/CDataStaxDriver/datastax-cpp-driver. To update, do git fetch then checkout the desired tag/release. The driver’s config files are located in Sources/CDataStaxDriver/extras.

libuv

The git submodule is under Sources/Clibuv/libuv. To update, do git fetch then checkout the desired tag/release. Note that include and uv.h in Sources/Clibuv are symlinked to the corresponding directory/file in Sources/Clibuv/libuv.

Development Setup

The library’s tests require running a Cassandra database.

With docker (takes about 1 minute to be ready to accept connections):

$ docker run --name cassandra -p 127.0.0.1:9042:9042 -d cassandra:3