Baradb/docs/en/api-websocket.md

WebSocket API

Full-duplex streaming for real-time data feeds and push notifications.

Connection

ws://localhost:9471/ws

Client Example

const ws = new WebSocket('ws://localhost:9471/ws');

ws.onopen = () => {
  console.log('Connected');
  ws.send(JSON.stringify({
    type: 'query',
    sql: 'SELECT * FROM users'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Message Format

{
  "type": "query",
  "id": "uuid",
  "sql": "SELECT * FROM users"
}

Message Types

Query Request

{
  "type": "query",
  "id": "123",
  "sql": "SELECT * FROM users"
}

Query Response

{
  "type": "result",
  "id": "123",
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
}

Error Response

{
  "type": "error",
  "id": "123",
  "error": {
    "code": "INVALID_QUERY",
    "message": "Syntax error"
  }
}

Subscription

Subscribe to changes:

{
  "type": "subscribe",
  "id": "sub1",
  "table": "users"
}

Push Notification

Server push:

{
  "type": "push",
  "table": "users",
  "action": "insert",
  "data": {"id": 3, "name": "Charlie"}
}

JavaScript Client

class BaraDBClient {
  constructor(url) {
    this.ws = new WebSocket(url);
    this.pending = new Map();
  }

  query(sql) {
    return new Promise((resolve, reject) => {
      const id = crypto.randomUUID();
      this.pending.set(id, { resolve, reject });
      this.ws.send(JSON.stringify({ type: 'query', id, sql }));
    });
  }
}