# Change the database schema from your agent

> Add tables and columns to your backend from your agent, when a change runs at once and when it needs a card, and how drafts protect live data.

Last updated: October 15, 2026

Source: https://www.willo.ai/docs/ai-agents/change-the-database-schema

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.

> **Note: Approved SQL that takes a while.**
>
> The first change on a draft may need Willo to create the draft backend, which can take a minute or two. If the approved call returns status `running`, the agent polls `willo_get_approval` with the request id. It must not send the SQL again, which would ask for a second run.

## 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](https://www.willo.ai/docs/ai-agents/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.

Related: [willo_execute_sql](https://www.willo.ai/docs/reference/mcp-tools/willo_execute_sql), [Approvals](https://www.willo.ai/docs/ai-agents/approvals), [Security model](https://www.willo.ai/docs/ai-agents/security-model).