Skip to main content

AI Agents on ScramDB

By the end of this page you will know why ScramDB is a good fit for building AI agents that read and write real data, and where to go next to actually build one.

An agent is only as good as what it can see and touch. Most stacks force a choice: give the agent a stale, ETL'd copy of your data that is safe to break, or give it live production access that is risky to break. ScramDB removes that trade-off. Three properties make it work.

One live copy, no ETL lag​

ScramDB is a UTAP database: Unified Transactional Analytical Processing. Transactions, analytics, and vector search all run on one live copy of your data, not a nightly-synced replica or a vector store an ETL job populates hours later. When an agent runs retrieval-augmented generation, a semantic search over embeddings_cosine_similarity, or a plain analytical rollup, it is reading whatever the last committed transaction wrote, in the same statement. There is no second system to keep in sync and nothing to explain to the agent about freshness.

Branch-per-agent isolation​

CREATE DATABASE ... CLONE gives an agent, an agent run, or even a single tool call an instant, full, real copy of production data to work against. The clone is a true peer database: the agent can read it, write it, break it, and query it with ordinary SQL. When the run ends, DROP DATABASE throws the whole thing away. No separate sandbox environment to provision, no synthetic or subsetted fixture data that behaves differently from the real thing, no risk to the source database, because nothing the agent writes is visible outside its own branch unless you deliberately move it back out.

This is the centerpiece of building safely with agents on ScramDB. See Branching for Agents for the full, step-by-step walkthrough.

SQL is the tool surface an LLM already knows​

Every model an agent might run on has already seen millions of lines of SQL. There is no custom SDK to teach it, no proprietary query language, no bespoke tool-calling protocol standing between the model and your data: ScramDB speaks the PostgreSQL wire protocol, so any driver a model already knows how to generate code for just works. That does not mean handing an agent unrestricted write access is a good idea. It means the constraints you already know from SQL access control (roles, GRANT, row-level security) are the guardrails, and they are real and enforced. See Agent Patterns for the concrete versions of this.

Docs an agent can ingest directly​

Part of building against ScramDB with an agent is letting the agent read the documentation itself, without an HTML scrape. Every page on this site is also served as its exact source markdown, the whole corpus is available as one concatenated file for a one-shot ingest, and there is a curated, hand-written brief written specifically for coding agents that names what does and does not work yet. An agent (or the tool you're building around one) can fetch these directly instead of guessing at ScramDB's SQL surface. See Connecting an Agent for the exact URLs and when to use each one.

What's in this section​

  1. Connecting an Agent - how an agent connects, picks a database, and pulls the machine-readable docs before it generates SQL.
  2. Branching for Agents - give an agent a disposable branch of real data, let it do whatever it likes, then throw the branch away.
  3. Agent Patterns - retrieval over live data, guardrails for agent-written SQL, tool surfaces, and keeping an agent inside a role's privileges.
  4. Building Agent Features - embedding similarity, full-text relevance, and geospatial context using the bundled packages.
  5. Using Graphs - model nodes and edges as ordinary tables and traverse them with recursive SQL, no separate graph database.