SDK guides
Branch a database for an agent
A SerenDB branch is a full copy-on-write Postgres database that shares storage with its parent until it diverges. Because a branch is cheap and fast to create, you can hand an agent its own isolated environment, let it work, and discard the branch without ever applying its changes to the primary.
Step 1
Start from a project
Databases live inside a project. List your projects, or create one, to get the parent that branches will fork from. The Seren SDK covers the full project and branch workflow.
import { serenDbListProjects } from "@serendb/sdk";
const { data, error } = await serenDbListProjects();
if (error) throw error;
console.log(data.data);Step 2
Create a branch for the task
Create a branch off the project. It starts as an exact copy-on-write clone of its parent, so the agent sees real data without the cost of a full copy and without risk to the source. Name branches per task or per agent run so they are easy to track and clean up.
Step 3
Hand the agent a connection string
Fetch the branch connection string and pass it to the agent worker as the database it should use. From the agent's perspective it is an ordinary Postgres connection; everything it writes stays on the branch. Roles and branch details are available through the same SDK when you need scoped access.
Step 4
Discard or promote
When the task finishes, delete the branch to throw the work away, or keep it if you want to inspect or promote the result. Either way the primary was never touched, which makes branches a safe unit of isolation for agents, previews, and tests.