Worlds

create world agent_7 with (task = 42);switch world agent_7;update orders set status = 'paid' where id = 7;diff;                       -- what agent_7 changedmerge world agent_7;        -- into main; the session moves back to main

Every statement here also has an MCP tool (fork, branches, set_meta, discard) and works from the dashboard’s SQL editor. BRANCH is accepted wherever WORLD is: CREATE BRANCH, USE BRANCH, MERGE BRANCH.

#Names and moments

• Names: a bare name (agent_7), a double-quoted one ("agent-7"), or a string ('agent-7'). A name with a dash must be quoted: unquoted task-1 fails with 42601.
• Not allowed: empty, containing @ (42602), starting with _tx_, or one of MERGE’s own words (using, ours, theirs, confirm, by, resolve, dry, into, only) (42939).
• IDs work too: anywhere a world is named, its ID does (w and 16 hex digits, from SHOW WORLDS).
• A world as it was: 'name@when', read only. In DIFF … TO, FORK WORLD, CREATE WORLD … FROM, SIMULATE … FROM, and as the Postgres database name.

History reaches back as far as the plan keeps it (an hour on the free plan). Earlier than that, or later than now, is 22023.

#CREATE WORLD

CREATE WORLD name [FROM source] [WITH (key = value, ...) | META '<json object>']

• Source: the session’s world, unless FROM names one: a name, an ID, or 'name@when' (the new world holds that past).
• Metadata: WITH values are strings, numbers, true, false or null; META takes a JSON object. At most 64 KB; keys starting with _sonos are the database’s own.
• Which run made it: run_id, prompt_version, model and tool_schema say which run of an agent made the changes, and with what. SHOW AUDIT and Reviews show them, and UNDO AGENT … WHERE run_id puts back one run.
• Scope: may_change, tenant, max_rows, max_deletes declare what the world is meant to change, held to at its merge. See Stale reads and scope.
• The session stays on its world: switch with SWITCH WORLD.

create world agent_7 from main with (owner = 'claude', task = 42);create world run_r42 with (run_id = 'r42', prompt_version = 'triage-v9', model = 'claude-opus-5-5');create world check_it from 'main@-1 hour';

#FORK WORLD

FORK WORLD source [AS] name [WITH (key = value, ...) | META '<json object>']

The same as CREATE WORLD name FROM source, with the source first.

fork world agent_7 as agent_7b meta '{"tags": ["retry"]}';fork world 'main@2026-09-20 10:00' as before_the_deploy;

#SWITCH WORLD

SWITCH WORLD name      -- also SWITCH BRANCH, USE WORLD, USE BRANCH, USE name

The session’s statements run on that world from now on. Over Postgres the database name does the same for the whole connection; see Your app.

#SHOW WORLDS

One row per open world, main included. SHOW BRANCHES is shorter: name, parent, and changes (rows changed since its fork).

#ALTER WORLD

alter world agent_7 set (task = null, reviewer = 'ada');alter world agent_7 set ttl '1 day';

#DROP WORLD

DROP WORLD [IF EXISTS] name [CASCADE]     -- also DELETE WORLD, DROP BRANCH

• Without CASCADE, refused while it has open forks (2BP01); with it, it and every world forked from it go, deepest first.
• A session on the dropped world carries on from its parent.
• main can’t be dropped (0A000).

#Who may do what

None of these run inside BEGIN … COMMIT (25001). A refused statement fails with 42501, naming the right it needs.