← Back to Hub

Developer & Operations Guide

The manual for building, testing, deploying, and integrating with PomaiDB.

1. Build Instructions (Runbook)

Debug Build (Development)

cmake -S . -B build_debug \
    -DCMAKE_BUILD_TYPE=Debug \
    -DPOMAI_BUILD_TESTS=ON \
    -DPOMAI_ENABLE_CRASH_TESTS=ON \
    -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined"
cmake --build build_debug -j

Release Build (Production)

cmake -S . -B build_release \
    -DCMAKE_BUILD_TYPE=Release \
    -DPOMAI_BUILD_TESTS=OFF
cmake --build build_release -j

Debugging

Use pomai_inspect to diagnose file integrity:

./build_debug/pomai_inspect checksum /path/to/wal_0_0.log
./build_debug/pomai_inspect dump-manifest /path/to/MANIFEST

2. CI/CD Reference

PomaiDB CI runs on Linux only (ubuntu-latest).

Local Verification Steps

1) Unit Tests

ctest --test-dir build --output-on-failure

2) TSAN (Thread Sanitizer)

CC=clang CXX=clang++ cmake -S . -B build-tsan ... -fsanitize=thread
ctest --test-dir build-tsan --output-on-failure -L tsan

3) Performance Gate

python3 tools/perf_gate.py --baseline benchmarks/perf_baseline.json

3. C API Reference (Stable ABI)

The FFI boundary contract for embedding PomaiDB.

Thread Safety Contract

Handle Thread-safe? Notes
pomai_db_t* Yes Safe for concurrent reads; writes are serialized internally.
pomai_snapshot_t* Yes Immutable point-in-time view.
pomai_iter_t* No Iterator handles are NOT thread-safe.

Design Principles