elodin-db

name	elodin-db
description	Work with Elodin-DB, the time-series telemetry database. Use when running elodin-db, writing client integrations (C, C++, Rust, Python), configuring replication/follow mode, querying data via the Lua REPL, or connecting the Elodin Editor to a database.

Elodin-DB

Elodin-DB is a high-performance time-series database for telemetry data. It stores components, messages, and metadata using the Impeller2 protocol, and serves as the central data bus between simulations, flight software, and the Elodin Editor.

Quick Start

# Install (from source)
just install

# Run the database
elodin-db run [::]:2240 $HOME/.local/share/elodin/db --config libs/db/examples/db-config.lua --log-level warn

# Connect the Elodin Editor
elodin editor 127.0.0.1:2240

# Launch the Lua REPL
elodin-db lua

Running the Database

elodin-db run <bind_addr> <data_dir> [--config <lua_file>] [--log-level <level>]

Parameter	Example	Purpose
bind_addr	[::]:2240	Listen address (IPv4/IPv6 + port)
data_dir	$HOME/.local/share/elodin/db	Storage directory
--config	libs/db/examples/db-config.lua	Lua configuration script
--log-level	warn	Log verbosity: error, warn, info, debug, trace

Lua REPL

Interactive database shell for debugging and exploration:

elodin-db lua

db> client = connect("127.0.0.1:2240")
db> client:dump_metadata()
db> :help

Client Integration

C Client

cc examples/client.c -lm -o /tmp/client && /tmp/client

See libs/db/examples/client.c for streaming fake sensor data.

C++ Client

c++ -std=c++23 examples/client.cpp -o /tmp/client-cpp && /tmp/client-cpp

The C++ library is C++20 compatible. See libs/db/examples/client.cpp for subscription example.

Rust Client

See libs/db/examples/rust_client/ for a complete Rust client using Impeller2.

C++ Header Generation

Generate the single-header C++20 library with message definitions:

cargo run --bin elodin-db gen-cpp > libs/db/examples/db.hpp

Python (via Simulation)

Simulations automatically create an embedded database, or connect to an external one:

# Embedded (temporary)
w.run(system)

# Explicit path
w.run(system, db_path="./my_data")

# Connect to external DB
w.run(system, db_addr="127.0.0.1:2240")

Follow Mode (Replication)

Replicate data from one database to another over TCP:

# Source database
elodin-db run [::]:2240 $HOME/.local/share/elodin/source-db

# Follower database (replicates from source)
elodin-db run [::]:2241 $HOME/.local/share/elodin/follower-db --follows 127.0.0.1:2240

The follower:

1. Synchronizes all existing metadata and schemas
2. Backfills historical component data and message logs
3. Streams real-time updates as they arrive

Packet Size Tuning

Default batches outgoing data into ~1500-byte TCP writes (standard Ethernet MTU):

elodin-db run [::]:2241 ./follower-db --follows 127.0.0.1:2240 --follow-packet-size 9000

Dual-Source Example

Run a simulation on source, follow on target, and add local streams:

# Source machine
elodin editor examples/video-stream/main.py

# Target — follow source
elodin-db run [::]:2241 ./follower-db --follows SOURCE_IP:2240

# Target — connect editor
elodin editor 127.0.0.1:2241

# Target — add local video stream
examples/video-stream/stream-video.sh

Merging Databases

Combine two databases (e.g. SITL and real telemetry) with optional time alignment and component prefixes.

# Basic merge with prefixes
elodin-db merge -o merged --prefix1 sitl --prefix2 real ./sitl-db ./real-db

# Align using timestamps from the Elodin Editor's playback timeline
elodin-db merge -o merged --prefix1 sitl --prefix2 real \
  --align1 15000000 --align2 14000000 --from-playback-start ./sitl-db ./real-db

Use --from-playback-start when alignment timestamps come from the Editor's playback timeline (relative to recording start). Without it, --align1/--align2 are absolute timestamps.

Trimming a Database

Remove data from the beginning or end of a recording. Values are in microseconds. Without --output, modifies in place.

# Remove the first 3 minutes from a recording
elodin-db trim --from-start 180000000 ./my-db

# Remove the last 2 minutes from a recording
elodin-db trim --from-end 120000000 --output ./trimmed ./my-db

# Trim 1 minute from the start and 2 minutes from the end
elodin-db trim --from-start 60000000 --from-end 120000000 --output ./window ./my-db

# Preview without modifying
elodin-db trim --from-start 180000000 --dry-run ./my-db

Editor Connection

The Elodin Editor connects to any running database:

elodin editor 127.0.0.1:2240

From a simulation, the editor connects automatically when launched via elodin editor sim.py.

Architecture

Elodin-DB uses the Impeller2 protocol internally:

• Components: Time-series data indexed by entity + component name + timestamp
• Messages: Ordered log entries (commands, events)
• Metadata: Schema information, entity names, component types

Storage is append-only with configurable retention. The database supports concurrent readers and writers with lock-free data structures.

Key References

• Full documentation: libs/db/README.md
• C client example: libs/db/examples/client.c
• C++ client example: libs/db/examples/client.cpp
• Rust client example: libs/db/examples/rust_client/
• Lua config example: libs/db/examples/db-config.lua
• DB architecture docs: docs/public/content/home/db/