Redis

DieselEngine provides a Redis client (powered by Lettuce) for caching, key-value storage, and pub/sub messaging.

Getting the Service

const redis = diesel.getRedisService();

Connection

Connect to a Redis server using a Redis URI:

redis.connect("redis://localhost:6379");

In Docker Compose, use the service name:

redis.connect("redis://redis:6379");

TIP

Typically, you connect to Redis in a startup script so the connection is available for all subsequent scripts.

Check Connection

if (redis.isConnected()) {
  console.log("Redis is ready");
}

Key-Value Operations

redis.set(key, value)

Store a string value.

• Parameters: key: string, value: string

redis.set("user:123:name", "Alice");
redis.set("config:theme", JSON.stringify({ dark: true, accent: "blue" }));

redis.get(key)

Retrieve a string value.

• Parameters: key: string
• Returns: string | null

const name = redis.get("user:123:name");
// → "Alice"

const config = JSON.parse(redis.get("config:theme"));
// → { dark: true, accent: "blue" }

Pub/Sub

redis.subscribe(channel, handler)

Subscribe to a channel. The handler is called for each message received.

• Parameters: channel: string, handler: (topic: string, data: string) => void

redis.subscribe("notifications", (topic, message) => {
  const data = JSON.parse(message);
  console.log(`[${topic}] Notification:`, data.title);
});

redis.publish(channel, data)

Publish a message to a channel.

• Parameters: channel: string, data: string

redis.publish("notifications", JSON.stringify({
  title: "New order",
  orderId: 42,
  timestamp: Date.now()
}));

Common Patterns

Caching

function getCachedUser(userId) {
  const redis = diesel.getRedisService();
  const cacheKey = `user:${userId}`;

  // Check cache first
  const cached = redis.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }

  // Miss — load from database
  const ps = diesel.prepareStatement(
    'SELECT id, data FROM engine."users" WHERE id = ?'
  );
  ps.setLong(1, userId);
  const rs = ps.executeQuery();
  if (!rs.next()) return null;

  const user = {
    id: rs.getLong("id"),
    ...JSON.parse(rs.getString("data"))
  };

  // Store in cache
  redis.set(cacheKey, JSON.stringify(user));
  return user;
}

Event Broadcasting

// Publisher (e.g., in an HTTP handler)
function onOrderCreated(order) {
  const redis = diesel.getRedisService();
  redis.publish("events:orders", JSON.stringify({
    type: "order.created",
    orderId: order.id,
    timestamp: Date.now()
  }));
}

// Subscriber (e.g., in a startup script)
const redis = diesel.getRedisService();
redis.subscribe("events:orders", (topic, message) => {
  const event = JSON.parse(message);
  if (event.type === "order.created") {
    // Send notification, update dashboard, etc.
    console.log("New order:", event.orderId);
  }
});

Session Store

function createSession(userId) {
  const redis = diesel.getRedisService();
  const sessionId = diesel.randomUUID();
  redis.set(`session:${sessionId}`, JSON.stringify({
    userId,
    createdAt: Date.now()
  }));
  return sessionId;
}

function getSession(sessionId) {
  const redis = diesel.getRedisService();
  const data = redis.get(`session:${sessionId}`);
  return data ? JSON.parse(data) : null;
}

API Reference

Method	Description
redis.connect(url)	Connect to a Redis server
redis.isConnected()	Check if connected
redis.get(key)	Get a string value
redis.set(key, value)	Set a string value
redis.subscribe(channel, handler)	Subscribe to a pub/sub channel
redis.publish(channel, data)	Publish to a pub/sub channel