Skip to content

NoSQL: Add Cassandra driver configuration and session support - #6088

Open
snazy wants to merge 3 commits into
apache:mainfrom
snazy:nosql-cassandra-1
Open

snazy wants to merge 3 commits into
apache:mainfrom
snazy:nosql-cassandra-1

Conversation

@snazy

@snazy snazy commented Nov 13, 2026

Copy link
Copy Markdown
Member

A Cassandra persistence backend needs connection configuration that works with Polaris configuration sources and supports both standalone use and Quarkus deployments.

Add the Cassandra module and Java-driver dependencies, typed driver-option mapping, and programmatic session creation. Integrate CDI-managed sessions and authentication providers, the Quarkus TLS Registry, and Micrometer metrics. Validate conflicting configuration and manage session and authentication-provider lifecycles.

This establishes the connection layer for the Cassandra backend.

Related to #6024, the illustrative Cassandra commit-stack PR.

A Cassandra persistence backend needs connection configuration that works with Polaris configuration sources and supports both standalone use and Quarkus deployments.

Add the Cassandra module and Java-driver dependencies, typed driver-option mapping, and programmatic session creation.
Integrate CDI-managed sessions and authentication providers, the Quarkus TLS Registry, and Micrometer metrics.
Validate conflicting configuration and manage session and authentication-provider lifecycles.

This establishes the connection layer for the Cassandra backend.

Related to apache#6024, the illustrative Cassandra commit-stack PR.
@snazy
snazy force-pushed the nosql-cassandra-1 branch from 4f0c9d7 to 3f2c999 Compare November 13, 2026 13:20
Comment on lines +77 to +87
@WithName("advanced.ssl-engine-factory.hostname-validation")
@WithDefault("true")
boolean hostnameValidation();

/**
* Session-wide Cassandra request timeout. Defaults to the larger of {@code ddl-timeout} and
* {@code dml-timeout} when omitted.
*/
@WithName("request.timeout")
@JsonFormat(shape = JsonFormat.Shape.STRING)
Optional<Duration> requestTimeout();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two properties look like driver option paths (advanced.ssl-engine-factory.hostname-validation, request.timeout) but live outside the driver. subsection, which is confusing next to e.g. driver.advanced.ssl-engine-factory.hostname-validation. Also, hostname-validation is only used when tls-configuration-name is set; otherwise it's silently ignored.

Maybe use Polaris-style names instead (e.g. tls-hostname-validation, request-timeout), and document (or warn) that hostname validation only applies together with tls-configuration-name?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed these properties to tls-hostname-validation and request-timeout, and documented that the hostname setting applies only with tls-configuration-name. Updated the configuration tests, generated reference, and mTLS startup example to use the new names.

Comment on lines +163 to +166
METRICS_SESSION_ENABLED,
Arrays.stream(DefaultSessionMetric.values()).map(DefaultSessionMetric::getPath).toList());
options.put(
METRICS_NODE_ENABLED,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This enables all session metrics and all per-node metrics. Node-level metrics (several of which are timers) are tagged per node, so on larger clusters this can produce a lot of metric series. And since advanced.metrics.* options are rejected in the driver subsection, operators currently have no way to reduce this.

Would it make sense to enable a smaller default set (e.g. session-level metrics plus a few node-level ones like pool.open-connections and the errors.* counters), and let operators opt into more?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reduced the defaults to session connected-nodes and cql-requests, plus node pool.open-connections and selected request/connection error counters. Operators can replace either category with an explicit list through driver.advanced.metrics.session.enabled or driver.advanced.metrics.node.enabled; an empty value disables that category. Histogram tuning is also allowed. Polaris still owns the Micrometer factory and metric naming. Added tests for defaults, overrides, and empty lists, including empty values read from properties.

Comment on lines +45 to +46
private static final Set<DriverOption> POLARIS_MANAGED_OPTIONS =
Set.of(REQUEST_TIMEOUT.getRawOption());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heads-up for the next PR in the stack: in #6024 the backend sets LOCAL_QUORUM/LOCAL_SERIAL explicitly on every statement, so basic.request.consistency and basic.request.serial-consistency configured through the driver subsection would be silently ignored, although the CassandraConfiguration Javadoc uses driver.basic.request.consistency=LOCAL_QUORUM as an example.

Since this PR defines the configuration surface, it seems like the right place to settle this: either add those options to POLARIS_MANAGED_OPTIONS (and change the Javadoc example), or, preferably, expose the regular and serial consistency levels as Polaris configuration, defaulting to LOCAL_QUORUM/LOCAL_SERIAL (which suit an active-passive setup), and have the backend use them.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. The driver fixes commit now rejects both native consistency options and replaces the Javadoc example with driver.basic.request.page-size=500. The backend commit introduces Polaris consistency-level and serial-consistency-level settings, defaulting to LOCAL_QUORUM/LOCAL_SERIAL, and uses them on statements. Regular consistency accepts LOCAL_QUORUM, QUORUM, or ALL; serial consistency accepts LOCAL_SERIAL or SERIAL. Unsupported values fail before connecting. Added statement-level tests and updated the deployment examples and generated reference.

@orca-review-bot orca-review-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, clean connection layer. I traced auth resolution, the conflicting-option checks and the disposers, and they look right. Main gap: CassandraDriverOptions has no tests, and it holds most of the logic. Can we add a parameterized test covering list/map parsing, dotted-path normalization, unknown paths, and each rejection rule (request timeout, metrics, config reload, TLS with tls-configuration-name, auth with auth.username, the same option set twice)? Small tests for requestTimeout defaulting and QuarkusTlsSslEngineFactory would help too. Also, CassandraBackendConfig, driverOptions(configuration) and cqlSessionBuilder(configuration, options) have no callers yet. Can we move them to the backend-factory PR, or say in the PR description that they're placeholders? No CHANGELOG entry needed while the backend can't be selected.

🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.


## Runtime integration

`CassandraBackendFactory` supports programmatic, non-Quarkus use. In a Quarkus runtime,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CassandraBackendFactory, the readiness health check, and the table creation/UCS notes at the end of the file aren't in this PR. Can we trim those until the follow-up PRs that add them land?

🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping the README as an overview of the complete Cassandra backend illustrated in #6024. The factory, readiness check, and schema handling arrive in the later commits in that stack.

import java.util.List;
import java.util.Map;
import java.util.Set;
import org.jspecify.annotations.NonNull;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

jspecify isn't declared in this module's build file. It only arrives transitively through guava. Can we add compileOnly(libs.jspecify) like mongodb/inmemory do, or drop the @NonNull on this private helper?

🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added compileOnly(libs.jspecify) directly to the Cassandra module, matching the existing backend modules.

*
* <p>Disabling this option is unsafe and should not be used in production.
*/
@WithName("advanced.ssl-engine-factory.hostname-validation")

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This key looks like a driver option path, but it lives outside driver.* and only matters when tls-configuration-name is set. Someone could easily try driver.advanced.ssl-engine-factory.hostname-validation instead. Can we rename it (e.g. tls-hostname-validation), or say in the Javadoc that it only applies with Quarkus TLS?

🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed the property to tls-hostname-validation and documented that it applies only with tls-configuration-name. Also renamed request.timeout to request-timeout and updated the tests, generated reference, and mTLS startup example.

import java.util.Arrays;
import java.util.Optional;

@ApplicationScoped

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mongodb and dynamodb keep their Quarkus adapters in a quarkus subpackage (#5565). Can this producer and QuarkusTlsSslEngineFactory follow the same layout?

🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved the producer, TLS engine factory, authentication qualifier, and CDI authentication lifecycle wrapper into the quarkus subpackage. The backend builder and readiness check added in the next commit follow the same layout. Moved the corresponding tests as well.

METRICS_SESSION_ENABLED,
Arrays.stream(DefaultSessionMetric.values()).map(DefaultSessionMetric::getPath).toList());
options.put(
METRICS_NODE_ENABLED,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This turns on every node-level metric, histograms included, for every node in the cluster. On a large cluster that's a lot of meters. Is that intended, or should node metrics be opt-in?

🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reduced the node defaults to pool.open-connections and selected error counters; node timers are no longer enabled by default. Operators can replace the defaults with an explicit metric list, or disable all node metrics with an empty driver.advanced.metrics.node.enabled value. The changes and regression tests are prepared locally.

Let operators select explicit session and node metric lists instead of enabling every metric. Use conservative defaults, support empty lists, and retain Polaris ownership of the metrics factory and naming settings.

Use distinct Polaris timeout and TLS property names, clarify TLS applicability, declare JSpecify directly, and move Quarkus adapters into their own package. Reject native consistency overrides so the backend follow-up can introduce Polaris consistency settings without silently ignoring driver configuration.
@snazy
snazy requested a review from adutra November 16, 2026 10:27
val quarkusRuntimeOnly =
configurations.dependencyScope("quarkusRuntimeOnly") {
extendsFrom(configurations.implementation.get(), configurations.runtimeOnly.get())
// spotbugs-annotations has only a GPL license.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see spotbugs anywhere, are you sure we need this?

I checked with:

./gradlew :polaris-server:dependencyInsight --configuration runtimeClasspath --dependency spotbugs-annotations
./gradlew :polaris-persistence-nosql-cassandra:dependencyInsight  --configuration runtimeClasspath --dependency spotbugs-annotations

* <p>Applications can provide an {@link AuthProvider} with this qualifier and select it with {@code
* auth.provider-name}.
*/
@Qualifier

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: use @Identifier from smallrye-common-annotation, and you get Literal for free.

@snazy
snazy requested a review from adutra November 19, 2026 09:20

This branch has not been deployed

No deployments
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.

3 participants