Skip to main content

Connecting an Agent

By the end of this page an agent's connection will be established, scoped to the right database, authenticated as its own role, and briefed on ScramDB's SQL surface before it generates a single query.

1. Connect over the standard PostgreSQL wire protocol​

ScramDB speaks the PostgreSQL wire protocol on port 5432 by default. Any standard PostgreSQL driver or client works unchanged, so an agent-generating code needs no special client library.

The already-published quick start shows the interactive form:

psql -h localhost -p 5432 -U scramdb scramdb

For programmatic use, most drivers accept a connection URL instead:

postgresql://scramdb@localhost:5432/scramdb

Both forms name the same three things: host, port (5432), user, and database. See Quick Start for getting a server running in the first place.

2. Choose a database, including a branch, by connection string​

The database name in the connection string (dbname in a URL, the trailing argument to psql) is what selects which database the session attaches to. This is also how an agent connects to a disposable branch: name the branch's database in the connection string, nothing more. There is no separate USE statement or session command.

# connect to the default database
psql -h localhost -p 5432 -U scramdb scramdb

# connect to a branch named agent_run_142
psql -h localhost -p 5432 -U scramdb agent_run_142

The same shape as a URL:

postgresql://scramdb@localhost:5432/agent_run_142

An unrecognized database name is refused loudly, not silently redirected: you get a database "..." does not exist error rather than a connection to something unexpected. One exception: leaving the database name empty falls back to the server's configured default database, and naming postgres explicitly (many drivers default to this if you configure nothing) aliases to that same default, unless you have actually created a real database named postgres, which always wins. If an agent is meant to land on a specific branch, always name that branch explicitly; do not rely on a default.

See Branching for Agents for how a branch like agent_run_142 gets created in the first place.

3. Give the agent its own role​

Connect the agent as its own role, not a shared human or bootstrap credential, so its privileges and its audit trail are its own.

CREATE ROLE agent_writer LOGIN PASSWORD 'a-real-password';

Once a role has a password, ScramDB authenticates it with SCRAM-SHA-256. The published Docker image runs with authentication disabled by default (--pg-no-auth), which is convenient for local development but means anyone who can reach the port connects as anyone. See Quick Start for enabling authentication before an agent touches anything beyond a laptop.

4. Fetch the machine-readable docs before generating SQL​

Before an agent writes SQL against ScramDB, have it pull the documentation itself rather than guess at the surface. Three real, fetchable endpoints exist:

EndpointWhat it isWhen to fetch it
https://scramdb.com/llms.txtA short, curated brief written specifically for AI coding agents. Names a NOT YET IMPLEMENTED section listing what does not work today.First, always. It is small and tells the agent what to avoid before it generates anything.
https://scramdb.com/docs/<page>.mdThe exact source markdown of any single docs page, at that page's own URL with .md appended.Once the agent already knows which page it needs, for the exact source with no HTML or navigation chrome.
https://scramdb.com/llms-full.txtThe entire documentation corpus concatenated into one file.A one-shot ingest into a context window or a RAG index. It is the whole site, so it is the most expensive of the three to fetch repeatedly.
curl https://scramdb.com/llms.txt
curl https://scramdb.com/docs/ai-agents/branching-for-agents.md
curl https://scramdb.com/llms-full.txt

Treat llms.txt's NOT YET IMPLEMENTED section as a hard "do not generate this" list. It is written and maintained specifically so an agent does not need to discover a gap in ScramDB's SQL surface by trial and error against a real database.

5. Confirm the connection​

Once connected, run a query that has nothing to do with your schema, just to confirm which database and role the session actually landed on:

SELECT current_database(), current_user;

Expected result: one row, two text columns, matching whatever database and role you connected with. For example, after connecting as agent_writer to agent_run_142:

 current_database | current_user
-------------------+---------------
 agent_run_142     | agent_writer

If it fails:

  • database "..." does not exist - the branch name is wrong, or the branch was never created. See Branching for Agents.
  • An authentication or password error - the role has no password set yet, or authentication is required and the connection did not supply one. Revisit step 3, and see the quick start's ALTER ROLE ... WITH PASSWORD example for setting one on an existing role.

What ScramDB does not add here​

There is no dedicated agent SDK and no separate REST or HTTP API for querying data today. The PostgreSQL wire protocol, plus the static docs endpoints above, is the whole surface. That is deliberate: it is the interface every driver, ORM, and code-generating model already knows.