colibri/docs/wiki/sl/store-schema.md

title	description
Shema shrambe	Koordinacijska shramba Colibri — ena sama podatkovna zbirka SQLite, ki hrani tablo opravil, register agentov in veščin ter preslikavo najemnikov.

← kazalo

Colibrijeva koordinacijska shramba je ena sama podatkovna zbirka SQLite v lasti storitve colibri. Hrani tablo opravil, register agentov in veščin ter preslikavo najemnikov trezorja. Ni predpomnilnik — je trajno stanje. Večina pisanj gre skozi API vtičnice procesa v ozadju, vendar shema pripada colibri-store.

→ crates/colibri-store/src/schema.rs

→ crates/colibri-store/src/lib.rs

Odločitve

SQLite, ne PostgreSQL, za shrambo krmilne ravnine

Shramba je SQLite, ker krmilna ravnina potrebuje enodatotečno podatkovno zbirko, ki jo je enostavno varnostno kopirati, posneti, pregledati in odpremiti. PostgreSQL s pgvector je načrtovan za iskanje/dolgoročni spomin, vendar tabla opravil in register agentov ne potrebujeta strežniškega procesa.

Demon paketno združuje povezana pisanja in se zanaša na način WAL v SQLite za sočasne bralce. To ohranja operaterski sklad samozadosten na majhnem gostitelju brez diska.

WAL + tuji ključi privzeto

Store::open ob vsakem zagonu zažene tri pragme:

• journal_mode=WAL — bralci ne blokirajo piscev.
• synchronous=NORMAL — varna sredina med polno-sinhronim in OFF.
• foreign_keys=ON — FK opravilo/agent je uveljavljen.

Te niso nastavljive med izvajanjem. Če bomo kdaj potrebovali drugačna jamstva glede trajnosti ali sočasnosti, naj bo to eksplicitno, namesto da bi povezava podedovala privzetke.

→ crates/colibri-store/src/lib.rs (Store::open)

Samo idempotentne migracije

Migracije tečejo ob vsakem Store::open. Uporabljajo tabele in indekse IF NOT EXISTS, tako da so ponovni teki varni. Ne odpremljamo migracij navzdol; razvoj sheme so aditivne tabele in stolpci. Če bo kdaj potrebna destruktivna migracija, mora biti to nameren ročni korak, dokumentiran v predaji.

→ crates/colibri-store/src/schema.rs

Štiri tabele za štiri skrbi

Tabela	Skrb	Ključna entiteta
tasks	Tabla opravil	Task
agents	Registrirani sodelavci	Agent
skills	Katalog veščin ekipe	Skill
tenants	Preslikava najemnikov/trezorja	Tenant

Opravila nosijo tuji ključ agent_id v agents. Vsako drugo razmerje je ohlapno — veščine niso povezane z agenti, najemniki pa so referencirani po svojem tenant_id v ukazih vtičnice in kljukah za oskrbo.

→ crates/colibri-store/src/schema.rs

Omejitev CHECK stanja opravila je vir resnice

tasks.status je omejen na ('queued','claimed','started','done','failed'). Enum TaskStatus v Rustu ga zrcali, vendar je podatkovna zbirka zadnje preverjanje. Ukaz, ki poskusi vstaviti neznano stanje, pade ob času pisanja.

→ crates/colibri-store/src/schema.rs

Zmožnosti agenta shranjene kot JSON, ne normalizirane

agents.capabilities je JSON blob, na primer ["code","rust","freebsd"]. Izognili smo se ločeni tabeli zmožnosti, ker so oznake zmožnosti samo nizi, register ekipe pa je majhen. Normalizirani stiki bi dodali zapletenost sheme brez izboljšanja moči poizvedb.

Če metapodatki zmožnosti zrastejo (uteži, različice, zahtevane veščine), lahko to kasneje razcepimo; trenutna shema namenoma ostaja pragmatična.

→ crates/colibri-store/src/lib.rs (register_agent)

Najemniki kodirajo preslikavo 1:1:1 ječa/trezor/zbirka

tenants hrani tenant_id, jail_root_path in collection_id kot UNIQUE stolpce. Pravilo je tenant_id = ime ječe = zbirka Vaultwarden. To omogoča colibri-vault, da poišče ječo po imenu in natančno ve, katero pot gostitelja in zbirko Vaultwarden uporabiti pri pisanju datoteke okolja.

Stolpec status najemnika sledi življenjskemu ciklu: provisioned → active → stopped → destroyed. Neodvisen je od tega, ali proces ječe teče; upravljanje življenjskega cikla je ločena skrb.

→ crates/colibri-store/src/schema.rs (komentarji na tenants)

Privzeta pot podatkovne zbirke je specifična za platformo

Privzetek shrambe je:

• COLIBRI_DB_PATH, če je nastavljeno.
• FreeBSD: /var/db/colibri/colibri.sqlite.
• Linux/macOS: $XDG_DATA_HOME/colibri/colibri.sqlite, s padcem na $HOME/.local/share/colibri/colibri.sqlite, nato /tmp.

FreeBSD privzeto uporablja /var/db, ker je to običajni imenik za lokalno stanje storitev. Linuxov padec spoštuje XDG, tako da je razvoj na delovni postaji normalen.

→ crates/colibri-store/src/lib.rs (default_db_path)

Izvoz JSON za varnostne kopije in paritetne teste

Store::export_json() izvozi vse štiri tabele v en objekt JSON. Obstaja za paritetne dife dvojnega teka, priložnostne varnostne kopije in razhroščevanje. Ni primarni poizvedovalni API; večina bralcev naj uporablja tipizirane metode.

Razmerja entitet

tasks.agent_id ----------> agents.id

 tasks        agents        skills        tenants
 -----        ------        ------        -------
 id           id            id            tenant_id
 agent_id FK  name          name          jail_root_path
 status       capabilities  description   collection_id
 title        status        category      status
 description  created_at    created_at    created_at
 created_at                              updated_at
 updated_at

Glej tudi

• task-board — življenjski cikel opravila in ujemanje zmožnosti
• operator-cli — ukazi vtičnice, ki pišejo v te tabele
• vault-provision — kako tabela najemnikov poganja oskrbo datotek env
• jail-confinement — imena ječ se preslikajo v vrstice najemnikov
• skills-catalog — bralni porabnik veščin