Detect Database Changes with StarbaseDB Plugin

In today’s data-driven world, real-time insights are no longer optional—they’re essential. Whether you're building a live dashboard, syncing data across systems, or triggering workflows in response to database changes, Change Data Capture (CDC) is the secret sauce for enabling these capabilities.

With the new Change Data Capture Plugin in StarbaseDB, you can now effortlessly subscribe to database changes, listen to mutation events, and implement custom callback functionality. In this post, we’ll walk you through how to get started with this feature and explore the possibilities it unlocks.

Step 1: Subscribe to table and column mutations

The first step is to define what you want to monitor. The Change Data Capture Plugin allows you to target specific tables and columns, so you can focus only on the changes that matter to your application. This eliminates unnecessary overhead and makes it easy to scale.

Example Configuration

Here’s how to set up the plugin to monitor mutations:

const cdcPlugin = new ChangeDataCapturePlugin({
    stub,
    broadcastAllEvents: false,
    events: [{
        action: 'INSERT',
        schema: 'main',
        table: 'users',
    }, {
        action: 'DELETE',
        schema: 'main',
        table: 'orders',
    }]
})

In the example above:

• The users table is monitored for inserts of new users.

• The orders table is monitored for deletions of orders.

By registering the plugin with your database instance, StarbaseDB will start capturing mutation events for the specified tables and columns.

Step 2: Listen to events

Once you've subscribed to mutations, the next step is to listen to the events. StarbaseDB provides two powerful ways to do this: WebSocket connections and the onEvent callback.

Using WebSocket Connections

StarbaseDB supports real-time event streaming over WebSockets. This allows your application to receive mutation events as they happen, with minimal latency.

const socket = new WebSocket("wss://starbasedb.YOUR-IDENTIFIER.workers.dev/cdc?token=ADMIN_AUTH_TOKEN");

socket.onopen = () => {
    // Socket is open
};

socket.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'cdc_event') {
        console.log("Mutation Event:", data);
    }
};

This code:

• Connects to the WebSocket endpoint provided by your StarbaseDB instance and authorized by the CDC route.

• Sends an admin authentication token to authenticate the connection.

• Logs each incoming mutation event, which includes details like the table, column, and type of change.

Using the onEvent Callback

For more granular control, you can use the onEvent callback provided by the Change Data Capture Plugin. This callback allows you to programmatically handle events within your application logic.

cdcPlugin.onEvent(async (payload) => {
    if (payload.action === 'INSERT' && payload.table === 'users') {
        console.log('A new user was created!')
    }
}, ctx)

This flexibility lets you respond to database changes in real time, whether that means notifying users, syncing data, or performing any other custom action.

Conclusion

The Change Data Capture Plugin transforms StarbaseDB into a real-time powerhouse. With its ability to subscribe to specific table and column mutations, stream events via WebSockets, and handle custom logic with the onEvent callback, it’s easier than ever to build event-driven applications.

Use Cases

Here are just a few ways we imagine you can use this feature:

• Real-time Dashboards – Update your UI instantly as data changes.

• Third-Party Integrations – Sync data to external systems like CRM's or analytics tools.

• Workflow Automation – Trigger background jobs or workflows in response to database events.

We’re excited to see what you begin building with it. For more details about the code contributions involved you can reference the introduction pull request.