Skip to content

Home

Jump to bottom
przemek edited this page May 16, 2026 · 2 revisions

usageDb

Embedded append-only usage database in Rust, designed as a billing-safe usage truth layer for AI token / credit / tool-call metering. Developed alongside usagebox.com.

The product bar isn't "more SQL" or "more DB features." It's:

accepted usage is never lost
same usage is never counted twice
monthly totals are explainable from raw events
rollups can be rebuilt
late/corrected events are handled
queries are fast because storage layout matches billing queries

Pages

  • Architecture — modules, data flow, ingest path, query path
  • Segment Format — on-disk columnar layout with per-column encodings
  • Operations — recovery, manifest generations, rebuilding rollups, durability modes
  • HTTP API — endpoint reference
  • Roadmap — phase status and what's pending

Status at a glance

  • 82 tests (unit + integration + 7 randomized property tests with 32 cases each)
  • CI: cargo build --all-targets + cargo test --all-targets with -D warnings on push and PR
  • Released: v0.2.2

Quick reference

cargo build
cargo test
cargo run     # HTTP server on 127.0.0.1:8080

Endpoints (spec §9.1, §12.2, §12.3):

POST /v1/usage/batch                            { "events": [UsageEvent, ...] }
GET  /v1/accounts/{account_id}/usage            ?from&to&group_by&product_id&meter_id&model_id&source
GET  /v1/accounts/{account_id}/usage/events     ?from&to&meter_id&product_id
POST /v1/query/sql                              { "query": "SELECT meter_id, SUM(quantity) FROM usage_events ..." }
GET  /health

See HTTP API for full reference and Architecture for how requests flow through the system.

Clone this wiki locally