Skip to content

feat(db): add Apache Cassandra and ScyllaDB support - #214

Merged
Blankll merged 16 commits into
masterfrom
feat/cassandra-scylladb
Nov 19, 2026
Merged

Blankll merged 16 commits into
masterfrom
feat/cassandra-scylladb

Conversation

@Blankll

@Blankll Blankll commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds Apache Cassandra and ScyllaDB as first-class connection types. Both use the Apache-licensed ING Cassandra JDBC wrapper and share a single cached driver bundle pinned to 4.16.7. This replaces Cassandra's previous driver coordinate, which could not be resolved from Maven Central.

  • Browse keyspaces, tables, and columns through system_schema, including primary-key flags, without reconnecting when the selected keyspace changes. SQLKit supports Cassandra 3.0 and later.
  • Configure a Keyspace and Local Datacenter in the connection form. The defaults are system and datacenter1.
  • Browse CQL tables with a configurable row limit. SQLKit uses a bounded preview because CQL does not support row offsets.
  • Cache direct-download drivers under the same versioned filename in Rust and Java. This also prevents duplicate downloads for GBase 8a.

Review follow-up

  • Qualify row changes, table drops, and truncates with the selected keyspace. Preserve the exact keyspace name when opening a query, including mixed-case names.
  • Use the same CQL statement splitter for Data Studio and MCP authorization and JDBC execution. Preserve complete batches during editor cursor execution and keep dialect selection consistent when the adapter is busy.
  • Hide server-side filters for CQL query results while retaining local sorting and pagination of returned rows.
  • Offer Disable, Require, Verify CA, and Verify Full for CQL. Saved Prefer settings use Require. Choose Disable for plaintext servers.
  • Use the matching versioned JDBC bridge built by the release workflow.

Verification

  • Review fixes passed 609 Rust tests, 894 frontend tests, and 13 Java tests, plus the frontend production build and ESLint.
  • Live checks with disposable Cassandra 4.1.12 instances covered exact keyspace selection, same-named tables in separate keyspaces, complete batch execution, and TLS-only connections.
  • Initial feature verification covered Cassandra and ScyllaDB over the JDBC bridge, Cassandra over SSH, and CQL queries and metadata through Data Studio and MCP.

Both stores connect through ING's open-source Cassandra JDBC wrapper
(Apache 2.0) as first-class connection types, sharing one pre-shaded
bundle JAR downloaded from the wrapper's GitHub releases:

- drivers.toml: replace the dead com.simba placeholder with the wrapper
  bundle (version_cap 4.16.7, GBase-style direct download); pre-flight
  cache naming now matches the Java resolver so a capped direct download
  is stored once under its pinned name (fixes the same double-download
  for GBase 8a)
- CQL metadata semantics: the wrapper maps keyspaces to JDBC schemas,
  not catalogs — the JDBC adapter folds catalog into schema for both
  stores, and list_databases reads keyspaces from system_schema
  (the wrapper's catalog listing reports the cluster name)
- localdatacenter: driver 4.x requires an explicit local DC with
  explicit contact points — the connection form gains a Local
  Datacenter field (default datacenter1, i18n in 7 languages), composed
  into the keyspace value; resolveDatabase backfills a bare keyspace
  with system?localdatacenter=datacenter1
- ScyllaDB ships its own logo (simple-icons official mark) and the
  connection list entry; the shared bundle/cache serves both

Verified end to end against Docker Cassandra 4.1.12 and ScyllaDB:
connect, DDL/DML, keyspace/table/column browsing with primary keys.
Note: ScyllaDB 6.x rejects SimpleStrategy (tablet replication) —
create keyspaces with NetworkTopologyStrategy.
The wrapper's DatabaseMetaData only reports objects of the keyspace bound
at connect time and ignores the catalog/schema arguments. Switching
keyspace in the UI does not reconnect, so browsing a keyspace other than
the one used at connect returned empty lists — reproducible over SSH
tunnels and plain connections alike.

list_tables and list_columns now query system_schema directly, which also
keeps working when the session keyspace is `system`. Primary-key flags
come from system_schema.columns.kind (partition_key/clustering), and
key columns are ordered first to mirror CQL's layout.

Found while validating Cassandra through an SSH bastion.
The Cassandra icon was a gray database-cylinder placeholder unrelated to
the project's branding. Replace it with the official Cassandra mark
(the eye), via simple-icons' apachecassandra vector in the brand color.
ScyllaDB keeps its official sea-monster mark (simple-icons scylladb).
The simple-icons scylladb path is a simplified stylization that loses the
mascot's identity at icon size (no face details). Use the official
mascot asset from scylladb.com (228x228 transparent PNG, vite/client
already types png imports).
The connection-type picker renders unranked types in enum order, and both
stores sat near the bottom of the list. Move their enum entries next to
TimescaleDB so they surface in the PG-family neighborhood instead.
The databasePlaceholderFor entries were lost in a branch switch; the
field fell back to the generic 'database_name' placeholder instead of
hinting at the keyspace semantics.
The generic Database label misrepresents the field for CQL stores —
what users enter is a keyspace, and calling it Database invites
relational assumptions (schema-in-database, cross-keyspace joins).
Route the existing databaseLabel computed through the
Cassandra-family check and add the keyspace label in all six
non-default locales (ScyllaDB shares the treatment via
isCassandraFamily).
The JDBC wrapper throws ('does not support this method', 'closed
ResultSet' on empty results) for getImportedKeys/getExportedKeys and
getViews — the Data Studio foreign-key panel surfaced these as errors.
Cassandra has no foreign keys and no wrapper-visible views, so an empty
list is the truthful answer: short-circuit list_foreign_keys,
get_foreign_keys and list_views for CQL types before reaching the
wrapper.
Two parser gates rejected every CQL-specific construct (PER PARTITION
LIMIT, ALLOW FILTERING, USING TTL) because sqlparser has no Cassandra
dialect:

1. capabilities/sql_write.rs::classify_sql — the MCP/AI risk classifier
   parsed statements into an AST to bucket them Read/Write/Delete/Ddl.
   CQL now short-circuits to a keyword classifier (SELECT -> Read,
   INSERT/UPDATE -> Write, DELETE/TRUNCATE -> Delete, CREATE/ALTER/DROP
   -> Ddl, everything else -> Other) plus a literal- and comment-aware
   multi-statement scan; ambiguous scripts stay Other, which keeps a
   destructive statement from riding a read-only grant.

2. database/sql_service.rs::wrap_query — the Data Studio grid wrapper
   parsed to inject sort/filter/paging. CQL statements now pass through
   unparsed, and a grid sort/filter/paging request returns an explicit
   CQL-semantics error (sorting is clustering-key-only, no OFFSET) rather
   than a parser failure.

Both gates keyed on `adapter_db_type`, which reported "generic" for every
JdbcBridge connection — so the CQL path could never trigger, and every
JDBC engine (ClickHouse included) was classified under GenericDialect.
It now reads the adapter's real type via the new DatabaseType::slug();
execute_sorted_query does the same.

Full suite: 605 Rust tests pass, including new CQL classification cases
for keywords, leading comments, quoted semicolons and destructive tails.
Aligns the storage layer across sqlkit / dockit / data-studio-agent on
rusqlite 0.43 (libsqlite3-sys 0.40, bundled SQLite 3.54.1, SQLCipher
4.20.0) — the links = sqlite3 rule forbids two versions in one build,
so all three consumers must move together.

data-studio-agent v0.2.2 additionally carries the SqlDatabase whitelist
fix that surfaces the SQL capability set for Cassandra/ScyllaDB
connections (geek-fun/data-studio-agent#38), which is what makes the
CQL tools visible to the AI assistant and MCP bridge.

609 Rust tests pass unchanged; no source code touched beyond Cargo.
sslmode=prefer is a libpq artifact: the PG wire protocol negotiates TLS
inline (SSLRequest probe, instant fallback), while the CQL native
protocol has no negotiation — the server is fixed to TLS-or-plaintext
at startup, and a TLS attempt against a plaintext server only produces
a 10s handshake timeout. Both DBeaver and the reference Go-driver tooling
treat Cassandra TLS as an explicit boolean (default off) for exactly
this reason, so mapping libpq's prefer onto the CQL driver as
force-TLS broke default connections to stock Cassandra deployments.

- bridge: requiresCqlTls no longer fires on prefer — prefer connects
  plaintext, same as disable; require/verify-ca/verify-full keep
  enforcing TLS with their certificate stores
- frontend: normalizeSslMode maps legacy prefer to disable for CQL
  types (the mode picker already hides prefer for these engines), so
  existing connections saved with prefer display and connect honestly
The adapter's ssl_mode translation turned Prefer into "require" for
Cassandra/ScyllaDB, so every stock deployment (client-to-node
encryption disabled, the Cassandra default) failed with a 10s
SslHandshakeTimeout through the whole MCP/Data Studio path — while the
same default connects fine to PostgreSQL, whose wire protocol
negotiates TLS inline.

prefer now maps to plaintext for CQL engines: the CQL native protocol
has no TLS negotiation, so there is nothing to "prefer" — TLS must be
an explicit require/verify-ca/verify-full. require keeps enforcing
TLS (verified: plaintext/prefer succeed, require fails against a
non-TLS server as intended).
Captures the architecture knowledge accumulated while building
Cassandra/ScyllaDB support so future agents do not rediscover it:

- JDBC bridge build + deployment commands, and the rule that a deployed
  jar swap requires restarting the bridge JVM (in-place rewrites desync
  the running JVM's zip directory and surface as NoClassDefFoundError)
- Bridge protocol shape and live smoke test
- CQL engine notes: wrapper bundle driver, keyspace-to-schema mapping,
  system_schema metadata path, sslmode=prefer plaintext semantics (no
  TLS negotiation in the CQL protocol), keyword-classifier gates, grid
  limitations, ScyllaDB 6.x SimpleStrategy rejection
- rusqlite/data-studio-agent version alignment: links = sqlite3 forces
  one rusqlite across sqlkit/dockit/data-studio-agent; upgrade all three
  in the same train; 0.43's chrono feature is implicit
- Adds an end-to-end "Adding a Database Engine" checklist consolidating
  the adapter steps, and fixes the stale dev-server port (1420 -> 1521)
rusqlite 0.43 rejects empty and comment-only SQL with Error::Empty
(rusqlite#1956), while 0.32 silently returned zero affected rows. The
query editor legitimately produces such statements (comment-only runs,
trailing comments left after statement splitting), so the editor path
surfaced a hard error for input that previously succeeded.

The non-SELECT branch now checks for an executable keyword first and
reports zero affected rows for empty/comment-only input; statements
with a real keyword execute unchanged (trailing comments included).

Verified against a legacy database file created by the previous
rusqlite/bundled SQLite: PRAGMA integrity_check ok, all agent tables
and rows readable. Compatibility review of 0.32 -> 0.43 changes:
PRAGMA-name validation (0.41) passes for our standard pragma set,
u64/usize ToSql removal and Iterator-returning column APIs are
compile-checked, SQLCipher stays on the v4 on-disk format (4.17 -> 4.20
bundled bump), and no community 0.43 regressions overlap our API
surface.
@Blankll
Blankll merged commit 4068627 into master Nov 19, 2026
3 checks passed
@Blankll
Blankll deleted the feat/cassandra-scylladb branch November 19, 2026 02:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant