Skip to main content

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.

Projectunit of tenant isolation · pinned region, immutablePINNED POSTGRES SHARDk9o_<proj_id>user-defined collectionsyour application's tablesk9o.from(collection)k9o_<proj_id>_sysplatform system tablesk9o.audit, k9o.policies, gate.*never via k9o.from()k9o_<proj_id>_ext_<name>extension-owned tablesone schema per extensionits own API, plugin token onlyObject-storage bucketregion-co-located with the shard; the same residency boundary covers bothcross-project access narrowed independently by credentials, planner scoping, and pool routing
The project boundary holds three schema families and one bucket inside a single region and shard; schema-level isolation keeps user, system and extension tables apart.

Three schema families​

SchemaContentsSDK access
k9o_<proj_id>User-defined collections — your application's tablesk9o.from(collection)
k9o_<proj_id>_sysPlatform 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:

FieldTypeDescription
idstringAuto-generated Stripe-style identifier: rec_<12-char base62>. Immutable.
metadataobjectPlatform-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:

MethodUse 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>):

PrefixResource
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.