Chronos DB, self-hosted
Worlds for long tasks
Expiry at use, nesting limits, rights on one world, handing a world over, budgets, durable worlds, pinned checkpoints, RESUME and AT WORLD. Next release.
Self-hostedChronos DB is one binary you run yourself. Releases and install script. To put agents on a database you already run, with approvals: Chronos Gateway
Which release
A world is an instant, isolated copy of the database that an agent works in and merges back. The first world shows the basics. This page is about worlds that live a long time: an agent working for hours, handing work to helpers, coming back after a restart. Everything here is SQL, run on the Postgres port or in the shell.
Expiry, at use
alter world agent_7 set ttl '1 hour'; -- capped at its parent's; its forks' shortened to italter world agent_7 reset ttl; -- never expires (agents need admin for either)- Read-only the moment its time is up. A write,
MERGE WORLDfrom it or into it,MERGE ... INTO, a fork of it, and aCOMMITof a transaction that wrote in it are refused with55000. Before, only the background sweeper (every 30 s) ended a world, so it took writes until then. - Reads keep working until the sweeper discards it, read-only transactions included. The sweeper discards it with every world forked from it, and the transactions open in them, the deepest first.
- A fork never outlives its parent. Its expiry is capped at the parent’s when it is forked (an agent’s
world_ttltoo) and whenever its TTL is set or reset. Shortening a parent’s TTL shortens its forks’ that would outlive it; lengthening it leaves theirs as they are.
How deep, how many
alter system set max_depth = 4; -- forks between a world and main, at most (0: no limit)alter system set max_children = 50; -- live forks of one world, at most (main's are counted by max_worlds)create agent bot with (can = 'read,fork,write_own', max_depth = 2, max_children = 10); -- per agent too- Depth: a world forked from main is 1 deep. A fork past
max_depthis refused with54000. - Children:
max_childrencounts the live forks of one world. Main’s forks are counted bymax_worldsinstead. - Both are database settings (
ALTER SYSTEM) and agent settings. A transaction’s own world counts toward neither.
Rights on one world
An agent may change its own worlds. To let another agent help with one, grant it rights on that world alone:
grant write, merge on world agent_7 to helper until '2026-12-01 09:00+00'; -- READ, WRITE, MERGE, FORKrevoke write on world agent_7 from helper;- What they cover:
READ,WRITE,MERGEandFORKinwand every world forked from it, besides the agent’s own rights. Never in main: a grant on main is refused, and merging into main still needswrite_main. MERGEis the right to merge the world. Merging a fork ofwintowtakesMERGEandWRITEonw.- Who may grant: only rights the grantor holds on
w. What it holds only by a grant it hands on for no longer than its own lasts. The database’s own users and admins grant any. UNTIL: a grant past it counts for nothing.- Who may revoke:
w’s owner, the grantor, or an admin. Revoking does not take back what the grantee granted on. - Where they are kept: in the world’s metadata (
_sonos_grants). Both statements are inSHOW SECURITY AUDIT.
Handing a world over
transfer world agent_7 to reviewer_bot; -- world, owner, epoch- Who:
w’s owner or an admin. The new owner must be able to change the worlds it owns (write_own), be of the world’s tenant if the world is held to one, and have room under itsmax_worlds. - The lease epoch (
_sonos_epoch, 0 for a world never transferred) moves on by one. - The old owner is fenced. Its writes and merges of the world get
55P03(lease lost), whatever rights it has, until the world is transferred back to it. - Attached to a database, the world is written back as its new owner’s role (
pg_role). - Audited, as grants are.
Budgets
create world trial with (budget_rows = 10000, budget_statements = 500);alter world trial set (budget_rows = 20000); -- the database's own users and admins onlybudget_rowscounts table rows written, not index entries.budget_statementscounts writes: each statement that changes rows, each HTTPputorbatch.- They count as it happens, in the world and every world forked from it, transactions included whether they commit or not. Past the budget the statement is refused with
53400and writes nothing. - A fork’s budget is at most what its parent, and each world above it, has left (
53400if more). - Kept in memory. After a restart the counts start again from zero.
Durable worlds
Writes to a world other than main are normally kept in memory and logged in batches, so a crash can lose them and flags the world (see What is durable, and when). A durable world waits for the disk as main does:
create world task_9 with (durable, check_reads = true);alter world task_9 set (durable = true); -- or turn it on later- Each write it acknowledges is on disk first, in the same group fsync as main’s; so are merges into it, its rebases and its metadata. A crash loses none, so the world is not flagged at the next open and its merge needs no version.
- Turning it on puts the writes it held in memory on disk first.
- Its read set too. A durable world that checks its reads logs what it read at the end of each statement that read something new, before the answer goes out. After a crash its merge is checked as usual instead of held for reads the database lost.
synchronous_commit = offwaits for nothing, main included.
Pinned checkpoints and rollback
checkpoint world task_9 as step3 pin '1 day'; -- kept for a day, past history_retentioncheckpoint world task_9 as step3; -- taken again without PIN: the pin goes, the label names the newer momentrollback world task_9 to checkpoint step3; -- back to it (RESTORE WORLD ... TO CHECKPOINT does the same)PIN '<interval>'keeps the world as it is now (its tree’s pages) until the pin runs out, whateverhistory_retentiondrops.- Without
PIN, a checkpoint is a moment in history, gone with it. - A label taken again replaces it, with
PINor without. - On disk only: a database kept in memory refuses a pin (
0A000).
Where a world is: SHOW WORLD STATE and RESUME
An agent coming back to a world, after a restart or from another process, asks where it stands:
show world state task_9; -- world, version, epoch, durable, flagged, check_reads, stale_reads, parent_changes, tokenresume world task_9 token 'w1a2b...:12:0'; -- the same, once the token still holds| Column | What it says |
|---|---|
| version | Writes since the fork. A merge into the world that changes it (a child’s, a partial merge, a transaction’s commit) moves it on too. |
| epoch | How many times the world was transferred. |
| durable, flagged, check_reads | As set; flagged after a crash lost writes. |
| stale_reads | What the world read that changed in its parent since (a world that checks its reads). |
| parent_changes | How many rows its parent changed since its fork point. |
| token | <world id>:<version>:<epoch>: what to hand to RESUME next time. |
RESUME WORLD w TOKEN answers as SHOW WORLD STATE when nothing moved. A write or a merge into the world since gives 40001; another epoch (the world was handed to another holder) 55P03; another world’s token or a malformed one 22023. Without TOKEN it is SHOW WORLD STATE.
Reading another world: AT WORLD
-- another world's table, in the same query as this world's (read only)select a.sku, a.price as before, b.price as afterfrom prices a join prices at world pricing_17 b using (sku)where a.price <> b.price;select * from prices at world 'pricing_17@-1 hour'; -- a world as it wasAT WORLD wafter a table inFROM, before or after its alias, reads that table aswhas it now: its rows and its definition there.'name@when'reads it as it was. Several worlds can be joined in one query.- Read only.
UPDATE,DELETEandINSERTrefuse a targetAT WORLD(0A000). A write may read another world in itsFROMorUSING. - Rights hold there too. An agent needs the right to read each world it names (
42501); another session’s transaction is no one else’s. Row security, an agent’s tenant and masked columns apply to the other world’s table as to its own. - Not in the read set. What is read there goes in no world’s read set.
- Every world of a set:
AT WORLDS OF SET s. See World sets.
Codes
| SQLSTATE | When |
|---|---|
| 55000 | A write, merge, fork or commit in a world whose time is up. |
| 54000 | A fork past max_depth or max_children. |
| 53400 | A write past a world’s budget, or a fork’s budget above what its parent has left. |
| 55P03 | The old owner of a transferred world writes or merges it; a RESUME token of another epoch. |
| 40001 | A RESUME token whose version moved on. |
| 22023 | A RESUME token of another world, or malformed. |
| 0A000 | A pinned checkpoint in memory; a write to a table AT WORLD. |
| 42501 | A grant on main; reading a world the agent may not read. |