Caching options:
This is list of options for caching:
These options are inside given virtual database configuration file. For example: postgresTest-vdb_1.conf. The filename depends on the name of the vdb → nameOfVdb.conf.
⚠️ Note: You can use SHIFT with mouse scroll to scroll horizontally!
| Key | Requirements | Conf File field | Description | Possible values | Default |
|---|---|---|---|---|---|
| Enable Query Caching | - (Unlocks this section) | cacheEnabled | Check to enable caching–if not checked, no cache rules will trigger caching, although rule processing will be done as normal. | Boolean | false |
| PCI/HIPAA Cache | - | pciHipaaCache | When enabled, no cached objects will actually be transmitted to the grid-cache, but the cache will be used to message invalidation requests. This is to avoid transmitting possible sensitive data across unencrypted connections, while maintaining cache synchronization integrity. This option is mutually exclusive with disabling the grid cache offload function, and will remove the benefit of the cache in cold-start scenarios. | Boolean | false |
| Cache Type | - | cacheType | Select the desired cache type. Options will adjust based on the cache type selected, see below tables to see their options. Hazelcast, Valkey/Redis/KeyDB | String | Hazelcast |
| Use soft references | - | cacheSoftValues | If enabled, soft references will be used for caching, highly advised. | Boolean | true |
| Duplicate request tracking | - | preCacheTracking | Track the query hash in a temporary list with the same TTL as a cache itself, and only cache if we have a "hit" in this temporary list. This prevents caching of unique queries that will never return from cache. | Boolean | false |
| Max Expiry | - | cacheMaxExpiry | If set to a value above zero, this value (in minutes) is the maximum TTL the L1 cache will cache an object for. This overrides the TTL in the cache rules if it is lower than the TTL set there FOR L1 cache queries. This value does not impact the TTL in the L2 cache such as Redis. | Long | 5 |
| Max Cached Objects | - | cacheObjectCount | If set to a value other than 0, this limits the total number of objects in the L1 cache layer to a fixed maximum. This can assist in reducing memory garbage collection time under heavy load, and is advised under very high request volume. | Long | 100000 |
| Max Cached Size | Access type = Proxy | cacheObjectSize | In proxy mode, this setting controls how much of a result-set's transmit buffer is saved before caching is aborted. Any result-set larger than this will not be cached. This value should not exceed 1/50 of the proxy heap size. | Long | 64000000 |
| Customize Query Cache Key | - | customKey | This allows the key used to access cached objects to be customized in order to expand when the result is considered the same. By default, all queries will include a hash of the complete SQL query, but also includes the VDB name the request was made through, the database user, catalog and schema. These fields can be removed to allow, for example, multiple VDBs to share the same data in the cache. | Boolean | false |
| Exclude VDB Name | Customize Query Cache Key | excludeKeyVdb | Should virtual database name be excluded from the hash key? | Boolean | false |
| Exclude JDBC to DB User | Customize Query Cache Key | excludeKeyUser | Should connected database user be excluded from the hash key? | Boolean | false |
| Exclude DB Catalog | Customize Query Cache Key | excludeKeyCatalog | Should catalog be excluded from the query cache hash key? | Boolean | false |
| Exclude DB Schema | Customize Query Cache Key | excludeKeySchema | Should schema be excluded from the query cache hash key? | Boolean | false |
| Exclude SQL Comments | Customize Query Cache Key | excludeKeySqlComments | Should sql comments be excluded from the query cache hash key? | Boolean | false |
| Grid Cache Offload | PCI/HIPAA Cache = false AND Cache Type != Local only | localCacheEnable | This option, if enabled, enables a first-tier local cache, which allows hot content to be served out of local heap. In the local cache, the objects will be stored in the performance optimal format (binary streaming format for a proxy, and Java objects when not a proxy). | Boolean | true |
| Cluster manager via cache | Cache Type = Hazelcast or Valkey/Redis/KeyDB | clusterCacheManager | This option allows a VDB to be managed by multiple management nodes at once, via the cache interface. For this to work, all management nodes must be populated with the vdb, and the cache settings configured to be identical. Once done, configuration changes for that VDB will be synchronized between nodes, and the cache will be used to propagate metrics as well, allowing the dashboard to be used at the same time on both nodes. Further, if one management node goes offline, the access layer nodes will remain unaffected. | Boolean | false |
Hazelcast
This is a Cache Type option, visible when it is set to Hazelcast, and it has given configuration items:
| Key | Requirements | Conf File field | Description | Possible values | Default |
|---|---|---|---|---|---|
| API Cache Name | - | gridCacheName | For interfaces that utilize a “named” cache interface, this is the name of the cache to use, i.e. Hazelcast. | String | - |
| Cache Configuration File | - | cacheConfig | When supported, this is an external configuration file to configure the cache, i.e. a Hazelcast client or server XML configuration file. The location of the file should be relative to the current working directory of the JDBC driver or proxy, which will be printed on startup. On a proxy install, when this file is not present, it will be pulled from the Heimdall Server. | String | - |
| Group ID | - | cacheGroupId | When using a hazelcast, the hazelcast group id (optional). | String | - |
| Group Password | - | cacheGroupPassword | When using a hazelcast, the name of the group password to use (optional). | String | - |
When using Hazelcast with AWS Auto-discovery, these options may be necessary for proper discovery of other Hazelcast nodes:
| Key | Conf File field | Possible values | Default |
|---|---|---|---|
| AWS Access Key | cacheAwsAccessKey | String | - |
| AWS Secret Key | cacheAwsSecretKey | String | - |
| AWS Tag Key | cacheAwsTagKey | String | - |
| AWS Tag Value | cacheAwsTagValue | String | - |
Valkey/Redis/KeyDB
This is a Cache Type option, visible when it is set to Valkey/Redis/KeyDB, and it has given configuration items:
| Key | Requirements | Conf File field | Description | Possible values | Default |
|---|---|---|---|---|---|
| Server | - | gridServer | For external grid cache interfaces, specifies the server name or IP to connect to. | String | - |
| Port | - | gridPort | When using an external grid cache, specifies the TCP port to connect to. | Integer | 0 |
| Database Number | - | databaseNumber | For Redis, which database "number" is used, not supported when the Redis instance is in cluster protocol mode. | Integer | 0 |
| Cache Username | - | gridUsername | If necessary cache username to use | String | - |
| Cache Password | - | gridPassword | For interfaces with a password authenticated interface, the password to connect to the cache with. Note: The username and password can be stored in the Secrets Manager. | String | - |
| Use SSL | - | useSsl | When connecting to the cache, should SSL be used for the connection (Redis) | Boolean | false |
| Verify Peer | Use SSL | verifyPeer | When using SSL, verify the peer TLS certificate | Boolean | false |