Change the database schema from your agent

Your business's backend is a Postgres database. Your agent can read its schema with any token and change it with a read + act token. This guide shows the safe order: look, change on the draft, check, publish.

1. Look before changing

willo_db_schema with no arguments lists the tables. With table, it describes one: columns, types, defaults, constraints, indexes and access rules. Every result carries a [Backend: …] line saying whether the draft or the live backend answered.

willo_db_query runs one read-only SELECT. Pass as_role: "anon" to see what a logged-out visitor can read, or as_role: "authenticated" with jwt_sub for a particular member.

2. Make the change

There are two ways in. Prefer the typed tools; use SQL for what they don't cover.

Typed tools

Tool	What it does	Card?
`willo_db_create_table`	One `CREATE TABLE`. Willo switches on row level security for it.	No
`willo_db_alter_table`	Add a column, an index or an access rule.	No
`willo_db_alter_table`	Drop or retype a column, drop or rewrite an access rule, add a trigger, or a rule that lets visitors or members change every row.	Yes
`willo_db_grant`	Grant or revoke what visitors and members can read or change.	Yes
`willo_db_insert`, `willo_db_update`, `willo_db_delete`	Write rows.	Yes

Results include security findings, for example a table that visitors could read in full.

Any SQL: `willo_execute_sql`

willo_execute_sql runs one or more statements your agent wrote: functions, policies, triggers, data fixes. It always raises a card. The card shows the statements word for word, a summary Willo computes from them (never from the agent's own description), the objects they touch, and security findings. After approval the agent sends exactly the same sql again and it runs. It returns command tags and row counts, never row data.

Some statements are refused before any card: BEGIN and COMMIT, role and login changes, and changes to the objects Willo manages on your backend. The refusal says why. There is no undo for SQL, so the card is the moment to check it.

3. Check it on the draft

While the business is drafting, every schema change lands on the draft backend, and rows there are scratch data. Describe the table again, query it as the site's roles, and open the draft preview to try the form or page that uses it.

With drafting off, changes apply to the live database at once, and a card for SQL says LIVE in red.

4. Publish

Publishing replays every approved change on the live backend, in order, and the publish card lists them. A change made with the typed tools replays the same way. See Draft and live.

Good habits for agents

Describe a table immediately before changing it, so the change matches the real columns.
Prefer adding a column to retyping one: an additive change runs at once and can't lose data.
Write access rules for every table the site reads. A table with row level security and no rule is invisible to visitors, which is the safe default.
Never put a secret in SQL. It is refused, and secrets belong on the dashboard.