Skip to main content

Quick Start

Get SierraDB running and start storing events in under 2 minutes.

Prerequisites​

  • Docker installed (recommended), or
  • Rust toolchain for building from source

30-Second Start​

The fastest way to try SierraDB is with Docker:

# Start SierraDB server
docker run -p 9090:9090 tqwewe/sierradb

That's it! SierraDB is now running on port 9090.

Your First Events​

Connect to SierraDB using any Redis client. We'll use redis-cli:

# Connect to SierraDB
redis-cli -p 9090

Now let's store some events:

# Append events to a user stream
EAPPEND user-123 UserRegistered PAYLOAD '{"email":"alice@example.com","name":"Alice"}'
EAPPEND user-123 EmailVerified PAYLOAD '{"timestamp":"2024-10-18T10:30:00Z"}'
EAPPEND user-123 ProfileUpdated PAYLOAD '{"bio":"Software engineer"}'

Each command returns the event's version number in the stream.

Reading Events​

Read all events from the user stream:

# Get all events from the beginning
ESCAN user-123 - +

Get just the latest events:

# Get events from version 2 onwards
ESCAN user-123 2 +

Check the current stream version:

ESVER user-123

Real-time Subscriptions​

Subscribe to new events as they arrive:

# Subscribe to all new events from this stream
ESUB user-123 FROM LATEST

In another terminal, append more events and watch them appear in real-time in your subscription!

Using Python​

Here's how to use SierraDB from Python with the redis package:

import redis

# Connect to SierraDB
client = redis.Redis(host='localhost', port=9090, protocol=3)

# Append an event
result = client.execute_command('EAPPEND', 'order-456', 'OrderCreated',
                               'PAYLOAD', '{"total":99.99,"items":["laptop"]}')
print(f"Event stored at version {result}")

# Read events from stream
events = client.execute_command('ESCAN', 'order-456', '-', '+')
for event in events:
    print(f"Event: {event}")

Using JavaScript​

With Node.js and the redis package:

const redis = require('redis');

async function main() {
  const client = redis.createClient({
    socket: { host: 'localhost', port: 9090 },
    RESP: 3
  });

  await client.connect();

  // Append an event
  const version = await client.sendCommand(['EAPPEND', 'cart-789', 'ItemAdded',
    'PAYLOAD', JSON.stringify({item: 'book', quantity: 2})]);
  console.log(`Event stored at version ${version}`);

  // Read events
  const events = await client.sendCommand(['ESCAN', 'cart-789', '-', '+']);
  console.log('Events:', events);

  await client.disconnect();
}

main().catch(console.error);

Next Steps​

Need Help?​