Documentation

Getting started

Docker (recommended)

The fastest way to get DoDB running.

# Start the server
$ docker compose up -d

# Verify it's running
$ curl http://localhost:7777/health

# Connect with the CLI
$ dodb-cli

Install the CLI

The CLI works on macOS, Linux, and Windows.

# Install from source (requires Rust toolchain)
$ cd client && cargo install --path .

# Or build without installing
$ cd client && cargo build --release

First queries

# Start the REPL
$ dodb-cli

dodb> CREATE TABLE users (id INT, name VARCHAR, age INT);
Table 'users' created.

dodb> INSERT INTO users VALUES (1, 'Alice', 30);
dodb> INSERT INTO users VALUES (2, 'Bob', 25);
dodb> INSERT INTO users VALUES (3, 'Charlie', 35);

dodb> SELECT * FROM users WHERE age > 25;
| id | name    | age |
|----|---------|-----|
| 1  | Alice   | 30  |
| 3  | Charlie | 35  |

dodb> SELECT COUNT(*), AVG(age) FROM users;
dodb> SELECT name FROM users ORDER BY age DESC LIMIT 1;

SQL reference

Data definition

CREATE TABLE table_name (
  column_name TYPE [, ...]
);

DROP TABLE table_name;

Data manipulation

INSERT INTO table_name VALUES (value, ...);

UPDATE table_name SET column = value [, ...]
  [WHERE condition];

DELETE FROM table_name
  [WHERE condition];

Queries

SELECT [columns | * | aggregates]
  FROM table_name
  [JOIN other_table ON condition]
  [WHERE condition]
  [GROUP BY column]
  [ORDER BY column [ASC|DESC]]
  [LIMIT n [OFFSET m]];

Aggregate functions

Transactions

BEGIN;
-- ... statements ...
COMMIT;
-- or
ROLLBACK;

REST API

Default: http://localhost:7777. All responses are JSON.

Authentication

# JWT token
$ curl -H "Authorization: Bearer eyJ..." http://localhost:7777/sql

# API key
$ curl -H "X-API-Key: your-key" http://localhost:7777/sql

WebSocket protocol

Connect to ws://localhost:7777/ws for real-time subscriptions.

Subscribe to a query

// Send subscription request
{
  "type": "subscribe",
  "query": "SELECT * FROM users WHERE age > 25"
}

// Initial result set
{
  "type": "initial",
  "subscription_id": "sub_1",
  "rows": [...]
}

// Subsequent deltas
{
  "type": "delta",
  "subscription_id": "sub_1",
  "inserts": [...],
  "deletes": [...]
}

Unsubscribe

{
  "type": "unsubscribe",
  "subscription_id": "sub_1"
}

CLI reference

# Interactive REPL
$ dodb-cli
$ dodb-cli -H http://myserver:7777
$ dodb-cli --token "eyJ..."

# One-shot SQL
$ dodb-cli -e "SELECT * FROM users WHERE age > 25"

# Run SQL file
$ dodb-cli --file test/smoke_test.sql

# REST operations
$ dodb-cli rest get users
$ dodb-cli rest get users 1
$ dodb-cli rest post users -d '{"name":"Eve"}'
$ dodb-cli rest put users 1 -d '{"age":31}'
$ dodb-cli rest delete users 5

# Real-time subscriptions
$ dodb-cli subscribe "SELECT * FROM users WHERE age > 25"

# Reducers
$ dodb-cli reducer transfer --args '{"from":1,"to":2}'

# Health check
$ dodb-cli health

REPL meta-commands