Pro Tip

Changefeeds are ephemeral. If you get disconnected, you may miss events. For persistent replication, use the write-ahead log.

Real-time Changefeeds

Subscribe to live data changes using WebSockets. Build reactive, real-time applications that update instantly.

Overview

Ephemeral Nature

Changefeeds are ephemeral streams. They do not provide historical data replay, only real-time events that occur while the connection is active.

Changefeeds allow clients to open a WebSocket connection and receive JSON events whenever documents in a collection are inserted, updated, or deleted. This is ideal for:

Real-time dashboards

Collaborative apps

Live Activity feeds

Triggering workflows

WebSocket Protocol

To start a changefeed, connect a WebSocket client to the following endpoint:

ws://host:port/_api/ws/changefeed

Subscription

Once connected, send a JSON message to subscribe to a collection. You can optionally filter by a specific document key.

subscribe.json

{
    "type": "subscribe",
    "collection": "users",
    "database": "_system", // Optional: database name
    "key": "user_123" // Optional: filter by key
  }

Event Types

The server streams events as they happen:

Insert Event payload

{
    "type": "insert",
    "key": "user_123",
    "data": { "name": "Alice", "age": 30 }
  }

Update Event payload

{
    "type": "update",
    "key": "user_123",
    "data": { "name": "Alice", "age": 31 },
    "old_data": { "name": "Alice", "age": 30 }
  }

Delete Event payload

{
    "type": "delete",
    "key": "user_123",
    "old_data": { "name": "Alice", "age": 31 }
  }

Client Implementation

Here is a robust JavaScript example using the browser's native WebSocket API:

client.js

// Connect to SoliDB Changefeed
  const token = 'YOUR_JWT_TOKEN';
  const ws = new WebSocket(`ws://localhost:6745/_api/ws/changefeed?token=${token}`);
  
  ws.onopen = () => {
      console.log('Connected');
      
      // Subscribe to 'orders' collection
      ws.send(JSON.stringify({
          type: 'subscribe',
          collection: 'orders'
      }));
  };
  
  ws.onmessage = (event) => {
      const change = JSON.parse(event.data);
      
      if (change.type === 'insert') {
          console.log('New Order:', change.data);
          updateDashboard(change.data);
      }
  };
  
  ws.onclose = () => console.log('Disconnected');

Limitations

1

At-most-once delivery

If the connection drops, events occurring during the disconnection are lost.
2

No ordering guarantees

Order is not strictly guaranteed in high-concurrency scenarios.

Performance

Zero Blocking

Write operations are not delayed by slow WebSocket clients.

Low Overhead

Negligible impact (<1μs) when no clients are subscribed.

Bounded Memory

Buffers are capped. Slow clients will skip events rather than leak memory.

Contents