[GEOMESA-3435] Added scyllaDB tests and documentation (#3437)

Author: andrii-kysylevskyi

docs/conf.py

@@ -33,6 +33,8 @@ def ultimateReplace(app, docname, source):
   "{{accumulo_required_version}}": "2.0.1 or " + target.versions.accumulo_version,
   "{{cassandra_supported_versions}}": "version " + target.versions.cassandra_version,
   "{{cassandra_required_version}}": target.versions.cassandra_version,
+  "{{scylladb_supported_versions}}": "version " + target.versions.scylladb_version,
+  "{{scylladb_required_version}}": target.versions.scylladb_version,
   "{{geoserver_version}}": target.versions.geoserver_version,
   "{{hbase_supported_versions}}": "version " + target.versions.hbase_version,
   "{{hbase_required_version}}": target.versions.hbase_version,

docs/user/index.rst

@@ -22,6 +22,7 @@ User Manual
    accumulo/index
    hbase/index
    cassandra/index
+   scylladb/index
    postgis/index
    kafka/index
    redis/index

docs/user/install.rst

@@ -8,6 +8,7 @@ Installation instructions are available for each data store implementation:
 * :doc:`/user/accumulo/install`
 * :doc:`/user/hbase/install`
 * :doc:`/user/cassandra/install`
+* :doc:`/user/scylladb/install`
 * :doc:`/user/kafka/install`
 * :doc:`/user/redis/install`
 * :doc:`/user/filesystem/install`

docs/user/scylladb/index.rst

@@ -0,0 +1,25 @@
+ScyllaDB Data Store
+===================
+
+.. note::
+
+    GeoMesa currently supports ScyllaDB {{scylladb_supported_versions}}.
+
+The GeoMesa ScyllaDB Data Store is an implementation of the GeoTools
+``DataStore`` interface that is backed by `ScyllaDB`_.
+It is found in the ``geomesa-cassandra`` directory of the GeoMesa
+source distribution, as ScyllaDB is a high-performance, drop-in replacement
+for Apache Cassandra.
+
+ScyllaDB offers superior performance and scalability compared to Cassandra,
+while maintaining full compatibility with the Cassandra Query Language (CQL)
+and wire protocol. This means GeoMesa can use ScyllaDB without any code changes,
+simply by connecting to a ScyllaDB cluster instead of Cassandra.
+
+.. _ScyllaDB: https://www.scylladb.com/
+
+.. toctree::
+    :maxdepth: 1
+
+    install
+    usage

docs/user/scylladb/install.rst

@@ -0,0 +1,81 @@
+Installing GeoMesa ScyllaDB
+===========================
+
+.. note::
+
+    GeoMesa currently supports ScyllaDB {{scylladb_supported_versions}}.
+
+Connecting to ScyllaDB
+-----------------------
+
+The first step to getting started with ScyllaDB and GeoMesa is to install
+ScyllaDB itself. You can find good directions for downloading and installing
+ScyllaDB online. For example, see Scylla's official `getting started`_ documentation.
+
+.. _getting started: https://opensource.docs.scylladb.com/stable/getting-started/index.html
+
+Quick Start with Docker
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest way to get started with ScyllaDB is using Docker:
+
+.. code-block:: bash
+
+    $ docker run --name scylla -d -p 9042:9042 scylladb/scylla:latest
+
+This starts a ScyllaDB container listening on the default CQL port (9042).
+
+Once ScyllaDB is running, create a keyspace for GeoMesa. Connect using ``cqlsh``:
+
+.. code-block:: bash
+
+    $ docker exec -it scylla cqlsh
+
+Then create a keyspace:
+
+.. code-block:: bash
+
+    CREATE KEYSPACE IF NOT EXISTS geomesa_scylla WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
+
+.. note::
+
+    For production deployments, use a higher replication factor and consider
+    using ``NetworkTopologyStrategy`` instead of ``SimpleStrategy``.
+
+Setting Up for GeoMesa
+~~~~~~~~~~~~~~~~~~~~~~~
+
+After creating the keyspace, note your ScyllaDB contact point. For a local Docker installation,
+this will be ``127.0.0.1:9042``. You can verify the port in the ScyllaDB configuration.
+
+Since ScyllaDB is wire-compatible with Cassandra, GeoMesa uses the same libraries and
+configuration. Set the ``CASSANDRA_HOME`` environment variable to point to a Cassandra
+installation, or let GeoMesa download the necessary JARs automatically (see below).
+
+Installing GeoMesa Tools and Plugins
+------------------------------------
+
+ScyllaDB uses the **same GeoMesa Cassandra distribution** for all components including:
+
+* Binary distribution and command line tools
+* Building from source
+* GeoServer plugins
+
+Please refer to the :ref:`Cassandra installation documentation <cassandra_install_source>` for complete
+instructions on:
+
+* :ref:`Installing from the binary distribution <cassandra_install_source>`
+* :ref:`Building from source <cassandra_install_source>`
+* :ref:`Setting up command line tools <setting_up_cassandra_commandline>`
+* :ref:`Installing the GeoServer plugin <install_cassandra_geoserver>`
+
+.. note::
+
+    All ``geomesa-cassandra`` command line tools work identically with ScyllaDB. Simply point them
+    at your ScyllaDB cluster using the contact point parameter.
+
+.. note::
+
+    The same Cassandra client JARs work with both Cassandra and ScyllaDB due to wire protocol compatibility.
+    When using ``$CASSANDRA_HOME`` or installing dependencies, use the Cassandra client libraries as documented
+    in the Cassandra installation guide.

docs/user/scylladb/usage.rst

@@ -0,0 +1,61 @@
+Using ScyllaDB with GeoMesa
+============================
+
+ScyllaDB is a high-performance, drop-in replacement for Apache Cassandra that is fully
+compatible with the Cassandra Query Language (CQL) and wire protocol.
+
+Data Store Parameters and Usage
+--------------------------------
+
+ScyllaDB uses the **exact same parameters and API** as the Cassandra Data Store.
+Please refer to the :ref:`cassandra_parameters` documentation for complete details on:
+
+* Data store parameters
+* Programmatic access
+* Command line tools
+* Configuration options
+
+The only difference is that you point the ``cassandra.contact.point`` parameter to your
+ScyllaDB cluster instead of a Cassandra cluster.
+
+Quick Example
+~~~~~~~~~~~~~
+
+.. code-block:: java
+
+    Map<String, Serializable> parameters = new HashMap<>();
+    parameters.put("cassandra.contact.point", "127.0.0.1:9042");  // Your ScyllaDB cluster
+    parameters.put("cassandra.keyspace", "geomesa_scylla");
+    parameters.put("cassandra.catalog", "mycatalog");
+    org.geotools.api.data.DataStore dataStore =
+        org.geotools.api.data.DataStoreFinder.getDataStore(parameters);
+
+ScyllaDB-Specific Notes
+-----------------------
+
+Differences with Cassandra
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ScyllaDB is designed as a performance-focused alternative to Cassandra. For detailed comparisons
+and benchmarks, see ScyllaDB's `comparison documentation <https://www.scylladb.com/compare/scylladb-vs-apache-cassandra/>`_
+
+Compatibility
+~~~~~~~~~~~~~
+
+* All Cassandra DataStore features work with ScyllaDB
+* Same client drivers and CQL syntax
+* ScyllaDB 2025.x or 6.x+ recommended
+* No code changes required - true drop-in replacement
+
+Migration from Cassandra
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To migrate from Cassandra to ScyllaDB:
+
+1. Export data: ``bin/geomesa-cassandra export``
+2. Set up ScyllaDB with same keyspace structure
+3. Import data: ``bin/geomesa-cassandra ingest``
+4. Update connection string to point to ScyllaDB
+
+Alternatively, use ScyllaDB's native migration tools to preserve all tables and data.
+See the `ScyllaDB migration guide <https://opensource.docs.scylladb.com/stable/operating-scylla/procedures/cassandra-to-scylla-migration-process.html>`_.

docs/versions.py

@@ -14,6 +14,7 @@
 accumulo_version = accumulo_version_full[:accumulo_version_full.rindex('.')]
 cassandra_version_full = '${cassandra.server.version.recommended}'
 cassandra_version = cassandra_version_full[:cassandra_version_full.rindex('.')]
+scylladb_version = '${scylladb.version.recommended}'
 geoserver_version = '${geoserver.version}'
 hadoop_min_version = '${hadoop.min.version}'
 hbase_version_full = '${hbase.version.recommended}'

geomesa-cassandra/geomesa-cassandra-datastore/src/test/scala/org/locationtech/geomesa/cassandra/data/CassandraDataStoreTest.scala

@@ -39,10 +39,13 @@ class CassandraDataStoreTest extends Specification with BeforeAfterAll {
 
   sequential
 
-  val container =
+  protected def createContainer(): CassandraContainer = {
     new CassandraContainer(DockerImageName.parse("cassandra").withTag(sys.props.getOrElse("cassandra.docker.tag", "3.11.19")))
       .withLogConsumer(new Slf4jLogConsumer(LoggerFactory.getLogger("cassandra")))
       .withFileSystemBind(MountableFile.forClasspathResource("init.cql").getResolvedPath, "/init.cql", BindMode.READ_ONLY)
+  }
+
+  val container: CassandraContainer = createContainer()
 
   lazy val params: Map[String, String] = Map(
     Params.ContactPointParam.getName -> s"${container.getContactPoint.getHostString}:${container.getContactPoint.getPort}",

geomesa-cassandra/geomesa-cassandra-datastore/src/test/scala/org/locationtech/geomesa/cassandra/data/ScyllaDBDataStoreTest.scala

@@ -0,0 +1,40 @@
+/***********************************************************************
+ * Copyright (c) 2013-2025 General Atomics Integrated Intelligence, Inc.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Apache License, Version 2.0
+ * which accompanies this distribution and is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ ***********************************************************************/
+
+package org.locationtech.geomesa.cassandra.data
+
+import org.junit.runner.RunWith
+import org.slf4j.LoggerFactory
+import org.specs2.runner.JUnitRunner
+import org.testcontainers.cassandra.CassandraContainer
+import org.testcontainers.containers.BindMode
+import org.testcontainers.containers.output.Slf4jLogConsumer
+import org.testcontainers.utility.{DockerImageName, MountableFile}
+
+/**
+ * Test suite for GeoMesa Cassandra DataStore using ScyllaDB as a drop-in replacement.
+ * This test extends CassandraDataStoreTest and overrides the container definition
+ * to use ScyllaDB instead of Apache Cassandra.
+ *
+ * Note: Uses --reactor-backend=epoll for compatibility with Docker Desktop on Mac/Windows.
+ * Requires ScyllaDB 2025.1.4+ for best Docker compatibility.
+ */
+@RunWith(classOf[JUnitRunner])
+class ScyllaDBDataStoreTest extends CassandraDataStoreTest {
+
+  override protected def createContainer(): CassandraContainer = {
+    new CassandraContainer(
+      DockerImageName.parse("scylladb/scylla")
+        .withTag(sys.props.getOrElse("scylladb.docker.tag", "2025.1.4"))
+        .asCompatibleSubstituteFor("cassandra")
+    )
+      .withCommand("--reactor-backend", "epoll", "--smp", "1")
+      .withLogConsumer(new Slf4jLogConsumer(LoggerFactory.getLogger("scylladb")))
+      .withFileSystemBind(MountableFile.forClasspathResource("init.cql").getResolvedPath, "/init.cql", BindMode.READ_ONLY)
+  }
+}

pom.xml

@@ -142,6 +142,7 @@
         <protobuf.version>3.25.6</protobuf.version> <!-- see also confluent.protobuf.version, hbase.protobuf.version -->
         <cassandra.driver.version>3.11.5</cassandra.driver.version>
         <cassandra.version>3.11.19</cassandra.version>
+        <scylladb.version>2025.1.4</scylladb.version>
         <kafka.version>3.9.1</kafka.version> <!-- needs to align with confluent version -->
         <confluent.version>7.8.0</confluent.version> <!-- confluent 7.8.x corresponds to kafka 3.8.x -->
         <confluent.protobuf.version>3.25.6</confluent.protobuf.version>
@@ -232,6 +233,7 @@
         <accumulo.version.recommended>${accumulo.version}</accumulo.version.recommended>
         <cassandra.driver.version.recommended>${cassandra.driver.version}</cassandra.driver.version.recommended>
         <cassandra.server.version.recommended>${cassandra.version}</cassandra.server.version.recommended>
+        <scylladb.version.recommended>${scylladb.version}</scylladb.version.recommended>
         <confluent.version.recommended>7.8.0</confluent.version.recommended>
         <hadoop.version.recommended>${hadoop.version}</hadoop.version.recommended>
         <hbase.version.recommended>${hbase.version}</hbase.version.recommended>