core-db is Kumoss’s system of record: who the users are, what they asked for, and what each run produced. Thirteen tables hold it. Everything else — traces, cached session facts, the generated files themselves — lives outside this database.
Pan, zoom, search, trace a relationship, switch themes. Open in a new tab
Conventions
Every table follows the same three rules, so they are stated once here rather than repeated per table:
-
Each table has an auto-incrementing integer
idprimary key, pluscreated_atandupdated_attimestamps that carry a time zone. -
A child’s foreign key is named after its parent —
session_id,round_id,user_id,artifact_id— and is indexed. -
Two uniqueness rules exist:
usersis unique on(issuer, subject), androundsis unique on(session_id, number).
The tables
| Table | Belongs to | What it records |
|---|---|---|
|
— |
One row per identity, keyed by the OIDC |
|
|
One request from creation to completion: a public |
|
|
One turn within a session — its |
|
|
The repository the session works against: |
|
|
Which clouds the session targets, and the |
|
|
The conversation carried across rounds: the |
|
|
The progress trail. Each row is one |
|
|
A pull request the round opened: the git |
|
— |
Metadata for one stored object: its |
|
|
A plan produced by a round, with the |
|
|
A report produced by a round, tagged with its |
|
|
The compliance audit of a generate round: its |
|
|
One generated or modified file, by |
The four artifact-metadata tables — terraform_plans, reports,
compliance_checks, and code_changes — each point at both a round and
an artifact. The round says which turn produced it; the artifact says
where the bytes are. The bytes themselves are never in the database.
Enumerated columns
Seven columns are constrained to a fixed set of values:
| Column | Table | Values |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note that apply is a report type and a progress status, but not a
session operation: an apply runs inside the session that generated the
plan rather than starting one of its own.
For what the two role columns actually permit, see Roles and permissions.
Deleting a session
Deleting a session removes the five tables that hang off it — its workspaces, terraform providers, histories, statuses, and rounds — and, through the rounds, their pull requests, plans, reports, compliance checks, and code changes. Deleting a user removes that user’s sessions the same way. This is the dashed region in the diagram.
Two things stay behind. artifacts rows are shared and are never removed
with a session; the objects they describe are managed in object storage
on their own schedule. And the link from a round to its statuses does not
cascade — statuses are cleaned up through the session that owns them, not
through the round. That is the dashed edge in the diagram.
|
These cascades are enforced by the application’s object mapper, not by
database |
Changing the schema
There is no migration tooling. The schema is created from the application’s model definitions at startup, which creates missing tables but never alters existing ones. A column added to a model will not appear in a database that was created before it.
In practice this means an existing core_db_data volume has to be migrated
by hand or recreated whenever the model changes. The upgrade that introduced
authentication is the case most deployments hit: sessions used to be keyed by
a username column and there was no users table at all.
Enum values are the one exception. At startup the core also adds any value
the models define but an existing PostgreSQL enum type lacks (ALTER TYPE
… ADD VALUE IF NOT EXISTS), so a core_db_data volume created before
vmware existed accepts vmware sessions without a manual migration.
Tables and columns are still never altered; only enum values are added.
For the other stores — Phoenix, Redis, object storage, and the workspaces volume — see Data and state.