Data architecture
Kilimanjaro's data model is structurally simple: every project owns three Postgres schema families; collections are tables in the user-data family; records are JSON-serialisable rows with two reserved fields. The same surface composes structured SQL, document, full-text, and vector queries behind a single chainable API. The data reference covers the API surface; this page describes the model.
Project as the isolation unit
A project is the platform's unit of tenant isolation. Every project owns:
- A pinned region (sovereignty boundary; immutable post-creation).
- A pinned Postgres shard within that region.
- Three schema families on that shard.
- A region-co-located object-storage bucket.
The project boundary is cryptographically and structurally enforced. Cross-project reads and writes are impossible by architecture, not by policy — the platform's connection-pool routing, query-planner scoping, and per-project DB credentials all narrow to the project's schemas independently.
Three schema families
| Schema | Contents | SDK access |
|---|---|---|
k9o_<proj_id> | User-defined collections — your application's tables | k9o.from(collection) |
k9o_<proj_id>_sys | Platform system tables (audit log, policies, gate tokens, idempotency log, end-user identity tables) | Typed APIs: k9o.audit, k9o.policies, gate.* — never via k9o.from() |
k9o_<proj_id>_ext_<name> | Extension-owned tables (one schema per installed extension) | The extension's own tables API, with the extension's plugin token only |
Collection names are unprefixed within k9o_<proj_id> — schema-level isolation makes cross-project collisions structurally impossible. A user-named audit_log in your project does not collide with the platform's system audit_log; the two live in different schemas and route through different SDK paths.
Collections
A collection is a Postgres table in k9o_<proj_id>. Collections are created, altered, and deleted exclusively through migrations — there is no ad-hoc DDL at the SDK layer. This is structural: schema drift is impossible because the schema is always the result of an auditable sequence of migration files.
Records
Every collection row is a JSON-serialisable object on the SDK surface. The platform reserves two top-level fields:
| Field | Type | Description |
|---|---|---|
id | string | Auto-generated Stripe-style identifier: rec_<12-char base62>. Immutable. |
metadata | object | Platform-managed. Always present. |
All other fields are caller-defined; the Postgres column type is the enforcement surface.
record.metadata carries shardId (the shard this record's project lives on), createdAt, and updatedAt. Callers never write metadata — any attempt to set metadata fields via insert or update is silently stripped at the gateway.
One query surface
Collections are read through the chainable query builder:
| Method | Use case |
|---|---|
k9o.from(collection).select()... | Filter, paginate, count — the chainable default |
The builder produces the standard {data, meta} envelope, respects the project-scoping invariant, and composes with RLS — policy filters apply as additional AND constraints.
RLS as the enforcement substrate
JSON policies authored in migration files compile to Postgres RLS clauses on the affected tables. The developer never writes RLS directly; the JSON-policy language is the single authoring surface. RLS is the innermost isolation layer — it enforces intra-project access control. Cross-project isolation has three independent layers (DB credential scoping, query-planner scoping, connection-pool routing) that operate independently of RLS.
A policy entry that would let a row escape its project schema cannot be expressed — the project-scoping invariant is unconditional.
Object storage co-located with the relational data
Object storage is a first-class primitive, not an add-on. Buckets are named namespaces within a project; objects are paths within a bucket. Buckets live in the project's pinned sovereignty region, alongside the Postgres shard — the same residency boundary covers both.
Storage objects carry caller-defined key-value metadata; storage and collection metadata together form a cross-cutting metadata surface.
ID prefix catalogue
Every persistent resource the platform addresses carries a Stripe-style identifier (<noun>_<12-char base62>):
| Prefix | Resource |
|---|---|
org_ | Organization |
proj_ | Project (= tenant) |
usr_ | User identity |
rec_ | Collection record |
tok_ | Service token |
key_ | Kibo key reference |
apr_ | Gate (approval) token |
wp_ | Governed Operation |
ext_ | Extension installation |
req_ | Request correlation id |
evt_ | Audit log entry / subscription mutation |
eu_ | Project-level end-user identity |
The full catalogue and the URL-prefix elision rule are in conventions §3.2.