cassandra

Kind	ffi-zig
Capabilities	ffi net
Categories	database network
Keywords	cassandra cql database nosql zig-ffi

Apache Cassandra client for Kit using CQL Native Protocol

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic parity-safe example
`kit.toml`	Package manifest with metadata and dependencies
`src/cassandra.kit`	Kit API and typed Cassandra errors
`tests/cassandra.test.kit`	Tests for cassandra
`zig/cassandra.zig`	Zig FFI entrypoints and Kit value conversion
`zig/connection.zig`	TCP connection and CQL handshake logic
`zig/kit_ffi.zig`	Kit FFI value helpers for local Zig tests
`zig/protocol.zig`	CQL native protocol encoding and parsing

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-cassandra.git

Usage

import Kit.Cassandra as Cassandra

main = fn() =>
  # Connect to a Cassandra node. This requires a running server on port 9042.
  match Cassandra.connect ["127.0.0.1:9042"]
    | Err e ->
      println "Failed to connect: ${Error.message e}"
    | Ok conn ->
      defer Cassandra.close conn

      println "Connected to Cassandra"

      # Select a keyspace for later queries.
      match Cassandra.use conn "my_keyspace"
        | Err e -> println "Keyspace error: ${Error.message e}"
        | Ok _ ->
          match Cassandra.query conn "SELECT * FROM users LIMIT 10" []
            | Err e -> println "Query error: ${Error.message e}"
            | Ok rows ->
              println "Query returned ${List.length rows} rows"

main

The package exposes typed errors through CassandraError:

err = CassandraConnectionError {message: "connection refused"}
println "Error kind: ${show (Error.kind err)}"
println "Error message: ${Error.message err}"

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

The checked-in basic example is a dry-run example so parity checks do not require a live Cassandra server.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Run the Zig unit tests:

zig test zig/cassandra.zig

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Type check examples in examples/
Run tests in tests/ with coverage

Running Parity

Compare interpreter and compiled output for examples:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/cassandra/, making it available for import as Kit.Cassandra in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`CassandraError`

Cassandra error type for typed error handling. Variants distinguish between different failure modes.

Variants

CassandraConnectionError {message}

CassandraQueryError {message}

CassandraKeyspaceError {message}