Pulpitum
Append-oriented, partition-local hot/cold table routing for CockroachDB and S3-compatible storage.
Pulpitum keeps recent records in CockroachDB and can serve immutable historical buckets from object storage without making callers choose a tier. Its core concern is the cutover protocol: fence writes, verify an immutable archive, publish a durable route, and only then clean up hot rows.
Status: experimental. The supported safe default is a v4 hot-store deployment. Deployment-owned archival is disabled unless explicitly enabled after environment-specific fault acceptance.
Start here
- Getting started — local setup, schema migration, and a safe runtime profile.
- Capability and safety posture — supported features, intentionally blocked capabilities, and production boundaries.
- Architecture — layers and storage contracts.
- Testing and fault inventory — routine and Docker-backed validation.
Core model
((table_id, partition_key, bucket_key), (event_time, sort_key))
table_idisolates logical tables.partition_keyroutes a logical partition.bucket_keyis derived from a UTC calendar strategy.(event_time, sort_key)is the chronological clustering and pagination key.
The built-in chat mapping is:
| Logical column | Core field |
|---|---|
channel_id |
partition_key |
timestamp |
event_time |
id |
sort_key |
value |
record payload |
How the pieces fit together
The editable Mermaid source and its render configuration generate this committed SVG with Mermaid CLI. The hot path stays in CockroachDB. The archival worker is disabled by default because it eventually deletes the hot copy; when explicitly enabled, it claims a durable lease, verifies immutable objects, publishes the archive route, and only then performs cleanup.
Supported deployment profile
Pulpitum currently supports a deliberately narrow operational profile:
- versioned v4 CockroachDB schema migrations;
- secure CockroachDB connections using rustls and optional mTLS;
- secure PgWire sidecar mode using TLS and SCRAM authentication;
- bounded, partition-local SQL reads and single-row inserts;
- append-oriented hot data in CockroachDB;
- immutable, checksummed archive artifacts when archival has been explicitly enabled.
See Capabilities before enabling archival or exposing the SQL sidecar.
Engineering references
- Hot/cold archival lifecycle
- Archival coordinator
- PostgreSQL/DataFusion contract
- Observability assets
- Production-readiness audit
- Staging sidecar benchmark