themondays

Appearance

On this page

Building an Internal-First Database That Stays Boring in Production ​

Most internal platforms don’t fail because they lack features. They fail because correctness, indexing, integration, and operations drift apart over time.

QSDB was built to solve that drift.

It is a table-oriented, transactional key-value database for internal service-to-service data. The goal is simple: predictable behavior under load, explicit invariants, and practical operations that don’t depend on tribal knowledge.

Why We Built It ​

Teams often start with something convenient and fast to adopt. That works well until scale, evolving query patterns, and integration demands collide.

The common pain points are familiar:

  • indexes added quickly without lifecycle discipline
  • retries and async pipelines with unclear consistency semantics
  • ad-hoc ETL scripts that become critical infrastructure
  • poor visibility into lag, rebuild state, and operational risk
  • cost and performance surprises caused by hidden read/write amplification

QSDB exists to make these concerns first-class, not afterthoughts.

Core Design Direction ​

QSDB is intentionally strict about a few rules:

  1. Base table storage is the source of truth.
  2. Secondary indexes are derived, rebuildable views.
  3. Correctness semantics are specified and tested, not implied.
  4. Operational limits are explicit and enforced.
  5. Every major behavior is observable in /stats, metrics, and UI.

This keeps the architecture stable as surface area grows.

Data Model and Query Model ​

QSDB uses tables with typed primary keys (partition key + optional sort key), predictable capacity controls, and consistent query/scan pagination semantics.

It supports:

  • table CRUD and item CRUD
  • conditional writes
  • range query over sort keys
  • scan/query pagination with stable tokens
  • secondary indexes with lifecycle controls

The system avoids “magic” behavior. If an operation is eventual, it is labeled eventual. If it is strict, it is tested as strict.

Built-In ETL: Integration and Indexing Without Glue-Code Sprawl ​

ETL is built into QSDB by design because integration is not optional in real systems.

What ETL covers ​

  • source connectors (manual event push and CouchDB changes feed)
  • policy-based filtering
  • field transforms (rename/drop/set/cast)
  • dynamic schema handling with explicit modes
  • checkpointing + replay-safe dedupe
  • dead-letter queue behavior and failure policies

Why this matters ​

Built-in ETL solves two hard problems together:

  1. Integration challenge External events are normalized and mapped into table shape with strict policies.

  2. Indexing challenge Derived index updates stay aligned with transformed sink writes, with measurable lag and replay safety.

Instead of writing custom workers for every pipeline, teams get one consistent ingestion contract.

Operational Features That Matter ​

QSDB treats operations as product features:

  • process-level single-writer lock
  • backup/verify/restore tooling
  • rebuild jobs with progress and control actions
  • compaction controls (manual + bounded automatic policy)
  • readiness/degraded probes
  • structured logs with correlation IDs
  • dashboard and stats endpoints for day-to-day visibility

The result is less guesswork during incidents.

Security and Control Plane Basics ​

QSDB includes practical security foundations for internal environments:

  • token/JWT-based authentication paths
  • role-scoped admin endpoints
  • policy-driven controls
  • optional at-rest encryption workflows with key management hooks

This is intentionally pragmatic: enough to run safely in real internal systems while keeping the core predictable.

Where QSDB Fits Best ​

QSDB is a strong fit when you need:

  • internal persistent or transactional state between services
  • strict control over behavior and indexing semantics
  • integrated ETL and operational visibility
  • a system you can evolve without changing your whole infrastructure story

It is not trying to be every database. It is optimized for one job: dependable internal data workflows with clear contracts.

What We Learned ​

The biggest lesson is that correctness is easier when the model is boring:

  • one source of truth
  • derived indexes
  • explicit invariants
  • measurable async boundaries
  • tested conformance across engine combinations

When those foundations are in place, feature growth becomes manageable instead of risky.

What’s Next ​

Near-term priorities continue to focus on reliability and maintainability:

  • deeper fault-injection and crash conformance
  • stronger index lifecycle orchestration and lag controls
  • continued UI modularization for long-term maintainability
  • tighter operational docs and runbook coverage

The direction stays the same: less accidental complexity, more explicit behavior.

QSDB is built for teams that want internal data systems to be understandable, testable, and operationally calm. Not flashy. Not vague. Just dependable.