⚡︎ BoxLang+ Module: Redis

|:------------------------------------------------------:  |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------:  |

This module provides standalone Redis and Redis Cluster cache providers for BoxLang runtimes.

Installation

To include the module in your boxlang runtime, follow the instructions for module installation appropriate to your runtime, using bx-redis as the module name/slug.

Versions 1.0.0 and above will require a Boxlang+ Subscription. Without subscription, the module will operate within trial mode for 30 days. After this period, the module will be placed in developer mode, which will limit cache host connections only to 127.0.0.1 and localhost.

Bug Reporting

Feature Requests and Bug Reports may be submitted via JIRA.

If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files that we might need to replicate your issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix for it. All issues that do not contain a way to replicate will not be addressed.

Support Questions

If you have any questions on usage, professional support or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.

• Ortus Community Discourse: https://community.ortussolutions.com
• Box Slack Team: http://boxteam.ortussolutions.com/
• Professional Support: https://www.ortussolutions.com/services/support

Configuration

boxlang.json configuration

The JSON configuration structure for boxlang for a single redis connection would be placed in the caches object in boxlang.json

Single Node Provider Configuration example

{ 
	"caches" : {
		"sessions": {
			"provider": "Redis",
			"properties": {
				"cacheKeyCaseSensitivity": "false",
				"database": "0",
				"idleConnections": "5",
				"maxConnections": "50",
				"password": "",
				"timeout": "2000",
				"useSSL": "false",
				"host": "127.0.0.1",
				"keyprefix": "resources",
				"port": "6379",
				"timeout" : 2000,
				"readTimeout" : 2000,
				"socketTimeout" : 2000,
				"poolWaittimeout" : 1000,
				"maxAttempts" : 10,
				"maxConnections": 1000, 
				"maxIdleTime" : 30000,
				"maxIdleConnections" : 20,
				"trackExpirations": false
			}
		}
	}
}

trackExpirations (default false): When true, the provider subscribes to Redis keyspace expiry notifications so the getSize() counter decrements automatically when TTL-based expiry occurs, keeping it exact rather than approximate. Requires notify-keyspace-events to include Kx (e.g., Kx or KEA) on the Redis server — this setting cannot be configured from the client on Valkey Serverless or AWS ElastiCache without a parameter group change at the infrastructure level. Also requires a non-empty keyprefix to safely filter expiry events. When false (default), getSize() is still O(1) but may slightly over-count entries that expired naturally via TTL.

Cluster Provider Configuration example

{ 
	"caches" : {
		"resources": {
			"provider": "RedisCluster",
			"properties": {
				"hosts": "node1.myrediscluster,node2.myrediscluster,node3.myrediscluster,",
				"keyprefix": "boxlang-cluster",
				"username": "${REDIS_CLUSTER_USERNAME}",
				"password": "${REDIS_CLUSTER_PASSWORD}",
				"port": "6379",
				"useSSL": "${REDIS_CLUSTER_USE_SSL:false}",
				"timeout" : 2000,
				"readTimeout" : 2000,
				"socketTimeout" : 2000,
				"poolWaittimeout" : 1000,
				"maxAttempts" : 10,
				"maxConnections": 1000, 
				"maxIdleTime" : 30000,
				"maxIdleConnections" : 20
				"cacheKeyCaseSensitivity": "false",
			}
		}
	}
}

Sentinel Provider Configuration example

{ 
	"caches" : {
		"resources": {
			"provider": "RedisSentinel",
			"properties": {
				"sentinels": "sentinel1.myhost.com:26379,sentinel2.myhost.com:26379",
				"keyprefix": "boxlang-sentinel",
				"username": "${REDIS_SENTINEL_USERNAME}",
				"password": "${REDIS_SENTINEL_PASSWORD}",
				"cacheKeyCaseSensitivity": "false",
				"database": "0",
				"idleConnections": "5",
				"maxConnections": "50",
				"password": "",
				"timeout": "2000",
				"useSSL": "false",
				"keyprefix": "resources",
				"timeout" : 2000,
				"readTimeout" : 2000,
				"socketTimeout" : 2000,
				"poolWaittimeout" : 1000,
				"maxAttempts" : 10,
				"maxConnections": 1000, 
				"maxIdleTime" : 30000,
				"maxIdleConnections" : 20
			}
		}
	}
}

Application.bx/Application.cfc configuration

Standalone

this.caches[ "sessions" ] = {
	"provider": "Redis",
	"properties": {
		"cacheKeyCaseSensitivity": "false",
		"database": "0",
		"idleConnections": "5",
		"maxConnections": "50",
		"password": "",
		"timeout": "2000",
		"useSSL": "false",
		"host": "127.0.0.1",
		"keyprefix": "boxlang-sessions",
		"port": "6379",
		"timeout" : 2000,
		"socketTimeout" : 2000,
		"poolWaittimeout" : 1000,
		"maxConnections": 1000,
		"idleConnections": 10
	}
};

Cluster

this.caches[ "resources" ] = {
	"provider": "RedisCluster",
	"properties": {
		"hosts": "node1.myrediscluster,node2.myrediscluster,node3.myrediscluster,",
		"keyprefix": "boxlang-cluster",
		"username": myClusterUsername,
		"password": myClusterPassword,
		"port": "6379",
		"useSSL": false,
		"timeout" : 2000,
		"readTimeout" : 2000,
		"socketTimeout" : 2000,
		"poolWaittimeout" : 1000,
		"maxAttempts" : 10,
		"maxConnections": 1000, 
		"maxIdleTime" : 30000,
		"maxIdleConnections" : 20
	}
};

Settings Summary

Redis Standalone

Host

The Redis server IP address or host name.

Port

The port of the Redis server.

Logical Database

The logical database to connect to in Redis. By default we connect to database 0.

Username

The Redis cluster username - only used when enabling user-level access.

Password

The password of the Redis server, if any.

SSL

Enable SSL on the connection to the Redis Server.

Connection Timeout

The time in milliseconds to wait for a connection or throw an exception.

Socket Timeout

The cluster connection socket timeout in milliseconds

Pool Timeout

The the maximum amount of time, in milliseconds, to wait for a connection pool resource to become available

Max Connections

The maximum number of connections to allow to the Redis server.

Idle Connections

The maximum number of idle connections to keep in the pool to the Redis server

Cache Key Prefix

The default key prefix is boxlang-cache. This will automatically prefix EVERY single cache item that goes into Redis. This will allow you to avoid collisions if you decide to register many Lucee caches or just to distinguish what comes from which cache connection.

Cache Key Case Sensitivity

By default all cache keys are transformed to lowercase to avoid any casing issues. However, if you want case sensitivity, then turn this option on.

Redis Cluster Provider Settings

Host(s)

Enter a comma-delimited list of all the IPs or hosts in the cluster. Not all are needed, but you should at least enter some to have redundancy.

Port

The port of the Redis cluster.

SSL

Whether SSL transport is enabled

Username

The Redis cluster username - only used when enabling user-level access.

Password

The Redis cluster password

Connection Timeout

The time in milliseconds to wait for a connection or throw an exception.

Read Timeout

The timeout for a read of data from the cluster - defaults to the connection timeout

Socket Timeout

The cluster connection socket timeout in milliseconds

Pool Timeout

The the maximum amount of time, in milliseconds, to wait for a connection pool resource to become available

Max Connections

The maximum number of connections to the cluster allowed per pool - defaults to 50

Idle Timeout

The max idle time, in milliseconds, for a connection to remain in the pool.

Max Idle Connections

The maximum number of concurrently idle connections to retain in the pool

Max Attempts

The maximum number of connection attempts to make to the cluster.

Cache Key Prefix

The default key prefix is lucee-cache. This will automatically prefix EVERY single cache item that goes into Redis. This will allow you to avoid collisions if you decide to register many Lucee caches or just to distinguish what comes from which cache connection.

Cache Key Case Sensitivity

By default all cache keys are transformed to lowercase to avoid any casing issues. However, if you want case sensitivity, then turn this option on.

Copyright Since 2023 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

 

Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions