Query Cache Using GridGain 8

Query Cache is a provisioning add-on for MariaDB Provisioned services that adds an in-memory cache for SQL query results, powered by GridGain 8. Repeated read queries are served from the GridGain in-memory cache instead of the underlying database, reducing read latency for read-intensive workloads with high query reuse. The add-on integrates with the Semi-Sync HA topology and uses the same MaxScale endpoint, so applications continue connecting to the existing MariaDB Cloud endpoint.

Architecture Overview

The cache is positioned between MaxScale and MariaDB. MaxScale intercepts cacheable reads and checks GridGain before querying the database; MariaDB remains the authoritative data store for all writes and for any read that is not served from cache.

Simplified Technical View

Core Components

MaxScale Cache Filter

The endpoint and routing layer. It classifies cacheable reads, performs the GridGain lookup, applies the configured TTL when it fills the cache, and fails through to MariaDB on a miss or when the cache is unavailable.

MariaDB Server

The OLTP (online transactional processing) engine and the authoritative data store. All writes, and all reads that are not served from cache, run here. It is unchanged by adding the cache.

GridGain 8 (Cache Engine)

A single-node, in-memory query result store. It holds cached SELECT results only, has no persistence, and is reachable only from MaxScale inside the service.

Freshness and Consistency

TTL-Bounded Freshness

Cached results are time-bounded, not invalidated on every write. Each cached result lives for at most the configured hard TTL (gg8_mxs_hard_ttl, see Configuration Reference), after which it is refreshed from the database on the next read.

No Read-Your-Own-Writes From Cache

The cache does not guarantee you will see a write you just made until the TTL expires and the result is refilled. Queries that must always reflect the latest write are not good caching candidates.

Cache-Miss Fallthrough

On a miss, MaxScale forwards the query to MariaDB, returns the result to the client application, and stores it for subsequent identical queries.

Cache-Bypass Failover

If the cache becomes unreachable, MaxScale routes reads directly to MariaDB. There are no application errors. You only lose the caching speed-up until the cache recovers. Because the cache is a single in-memory node with no persistence, losing it means a cold cache, not data loss; it re-warms as queries re-execute. A rolling restart behaves the same way: no errors, only a temporary drop in hit rate.

Launching a Query Cache Service

Query Cache is enabled on a MariaDB Provisioned service that uses Semi-Sync HA. You can enable it at launch or add it to an existing service later.

Via MariaDB Cloud Portal (UI)

1. In the MariaDB Cloud portal, launch a new Provisioned service or open an existing one.

2. Under High Availability, choose Semi-sync, which Query Cache requires.

3. Under Add-ons, enable Query Cache and pick a cache node size (Sky-4x16 to Sky-16x128, Intel/AMD only).

Launch - Enable Query Cache

Via MariaDB Cloud REST API

For API keys, client IP allow list, checking service ready status, and fetching credentials, follow Launch DB using the REST API. The MariaDB Cloud REST API reference and API docs cover the full request model.

Query Cache fields — On POST /provisioning/v1/services, set "cache_backend": "GridGain8QueryResultCache" to provision the cache on top of the replicated es-replica (Semi-Sync HA) topology. Use amd64 for architecture and a supported cache size, consistent with the portal. Optionally set gg8_size, gg8_replicas, and gg8_mxs_hard_ttl (see Configuration Reference).

Example (adjust tier, region, availability_zone, size, version, and add allow_list or other required keys per the launch guide):

Discover available cache sizes — list the valid gg8_size values for a provider and topology:

Add, modify, or remove the cache on an existing service — use the gg8_cache sub-resource. Each call returns 202 Accepted; the service moves to pending_modifying, then back to ready. The service must be ready before you call it.

Managing the Cache

You can manage the cache from the service's MANAGE menu → Manage Query Cache:

• Enable or disable the cache with the Enable Query Cache checkbox.

• Change the TTL in Query Cache TTL (seconds), from 5 to 600 (default 120).

• Resize the cache node by selecting a size from Sky-4x16 up to Sky-16x128 to scale up or down.

Manage Query Cache

The same operations are available through the REST API. See Via MariaDB Cloud REST API above.

Configuration Reference

Common API Errors

Observability

When the cache is enabled, the service's Monitoring view gains a Cache dashboard (select Cache in the top-right of the Monitoring tab). It shows the health of the GridGain 8 cache over the selected time interval:

Monitoring - Cache

For the full list of panels, see Service Monitoring Panels. The same metrics are also available through the Observability API.

Known Issues and Limitations

The Tech Preview scopes Query Cache to the following:

• Requires Semi-Sync HA. The cache is not available on the Insync (Galera) or None HA options, or on Serverless.

• Freshness is TTL-bounded. Cached results may be stale for up to the configured hard TTL because there is no per-write invalidation.

• Large results are not cached. Result sets larger than the per-entry limit (1 MB) are retrieved directly from MariaDB instead of being cached.

• Single cache node. gg8_replicas is locked to 1. Cached data is not replicated. If the cache node becomes unavailable, requests are served from MariaDB until the cache is repopulated.

• Single availability zone. The cache runs in the same AZ as MaxScale; multi-AZ is planned for a later phase.

• No persistence or backups for the cache; it is in-memory only.

• No autoscaling. The initial release supports a single cache node only. The node can be vertically resized independently of the MariaDB Server.

• Fixed memory layout. The JVM heap and off-heap memory allocation are determined by the selected node size and cannot be customized.

• No direct GridGain access. GridGain is not exposed to customers. Direct access to GridGain features such as key-value operations, SQL, Compute, Transactions, or Data Streamer is not supported. The GridGain version is managed by the platform and is not user-configurable.

_{This page is: Copyright © 2026 MariaDB. All rights reserved.}