Skip to content
PulsusDB

Development

Application repository

Section titled “Application repository”
Terminal window
git clone https://github.com/digitalis-io/pulsusdb.git
cd pulsusdb

PulsusDB is a Rust workspace. Its crates separate configuration, ingest, query languages, schema tooling, server concerns, setup, and test infrastructure.

Common starting points:

Terminal window
cargo check --workspace
cargo test --workspace

Some integration suites require ClickHouse, containers, external reference images, or generated fixtures. Read the relevant crate tests and CI workflow before running the entire matrix locally.

Design-first workflow

Section titled “Design-first workflow”

The project keeps detailed design documents in docs/. Changes to API behavior, schemas, query lowering, or compatibility should update the corresponding design and evidence:

  • API routes and wire formats: docs/api.md
  • Configuration: docs/configuration.md
  • Schema and read paths: docs/schemas.md
  • Architecture: docs/architecture.md
  • Feature and milestone scope: docs/features.md
  • Compatibility evidence: benchmark and differential ledgers
  • Durable choices: architecture decision records in docs/decisions/

Documentation site

Section titled “Documentation site”
Terminal window
git clone git@ssh.bitbucket.org:digitalisio/pulsusdb-documentation.git
cd pulsusdb-documentation
npm install
npx astro dev --host 0.0.0.0

Pages live under src/content/docs/. The sidebar is explicit in astro.config.mjs, so add new user-facing pages there as well as in the filesystem.

Before submitting a change:

Terminal window
npx astro check
npx astro build

Documentation principles

Section titled “Documentation principles”
  • Prefer tasks and user outcomes over internal milestone names.
  • Distinguish implemented behavior from planned behavior.
  • Keep warnings about destructive schema operations close to commands that invoke them.
  • Link to the exhaustive application specification instead of copying fast-changing edge-case tables.
  • Use product-neutral PulsusDB routes for new examples; describe compatibility paths as opt-in bridges.
  • Test every code sample against the current application configuration and API documents.

Trademarks

Section titled “Trademarks”

Grafana®, Loki™, and Tempo® are trademarks of Raintank/Grafana Labs. Prometheus is a trademark of The Linux Foundation. ClickHouse® is a trademark of ClickHouse, Inc. PulsusDB is independent and is not affiliated with or endorsed by those projects.