Review an agent's proposal

Read this when an agent connected to Seqora has proposed a schema change and a toast says so. An agent never runs DDL. It sends ordinary SQL to propose_change, and Seqora turns it into a design on the live schema and checks it. The change reaches the database only when you apply it here. Proposal review is Pro. Giving an agent Propose access is on Connect an AI agent.

What a proposal is

A proposal is a schema change, stored in Seqora as a design with numbered revisions. In 0.6.1 that is the only kind. On PostgreSQL the agent may send CREATE TABLE, ALTER TABLE, CREATE INDEX, DROP INDEX, RENAME and COMMENT. Anything else is refused, by statement, line and column, to the agent.

Say an agent was asked to make the web orders report faster. It calls propose_change with schema set to commerce, the title Index for web orders, and:

CREATE INDEX orders_channel_placed_idx ON commerce.orders (channel, placed_at DESC);

Seqora applies that to commerce.orders as it is now, runs the design and read-only data checks, and tests the index with check_index. The agent gets the change list as c1, c2, the checks and a seqora://proposal/ link, and can fix its own blockers with revise_proposal before you look.

Open it

1. Click Review on the toast. After Later, the proposal waits under Proposals in the sidebar, which appears once a proposal exists. Open proposal… in the command palette and the agent's seqora://proposal/ link open the same tab.
2. Read the header: the client's maker mark and name, the title, the counts, and a button per revision, r1, r2. The trail under it lists each revision with its author, time and blocker count, then what you did.

The toolbar shows the connection with a lock, because the tab never writes. When Seqora found a migrations table, a chip names the tool and its newest migration.

Read the changes, the SQL and the locks

1. Read the rows. They are grouped by table, with the table's row estimate, or new for a table the agent creates. A blocker or a warning sits at the end of its row with a short label. Hover it for the whole sentence.
2. Read the script. Click a statement to select its rows, or a row to light its statements.
3. Read Before you apply. Blockers come first, then each warning with a checkbox, then Snapshot · and the connection's name.

For the index above, the row for orders carries Statement 1 blocks writes to commerce.orders while the index builds. The tooltip says how many rows are read and gives the CREATE INDEX CONCURRENTLY form to run outside the transaction instead. Had check_index found the index unneeded, the row would also warn index not needed.

See it on the diagram

1. Click Diagram in the toolbar.

The canvas opens framed on the tables the proposal touches. What the agent proposes is dashed and hatched in the agent color, and each new or changed table carries the client's mark and name. Click a table or a column to select its rows and statements. The ER diagram tab itself does not show proposals.

Apply it, approve it or send it back

1. Untick a row to leave that change out. Its statements stay in the script, struck through. Changes that depend on it, such as a new table's indexes, are left out with it. Leaving out a blocked change unblocks the rest.
2. Pick one way out:
   • Review and apply opens the review dialog design mode uses: the data checks, a snapshot, a dry run, the typed database name on production, then the apply. The proposal becomes Applied. See the review dialogs.
   • Approve for migration stores the SQL for the agent to write as a migration file. It waits until every warning in Before you apply is ticked. The proposal becomes Approved.
   • Send back needs a Note for the agent or a left-out change. The proposal becomes Sent back.

Approve for migration is the primary button when Seqora found a migrations table, and Review and apply when it didn't. Both wait while there are blockers, and their tooltip says Fix 1 blocker. Proposal actions holds Discard, and Edit in designer, which opens the design workbench. Saving there makes a revision authored by you.

What the agent sees afterwards

Seqora sends nothing to the agent. It learns what you did the next time it calls get_proposal: the status, your note, the changes you left out as c1, c2, the checks, the DDL it sent last, and the approved SQL once you approve. A revision replaces the whole DDL. Seqora applies it to the schema as it is then, and says so when the live schema changed in between. A revision that arrives while the tab is open adds its button with a dot, and the view stays on the revision you are reading. Applied and discarded proposals can't be revised.