Key Takeaways

  • Supabase built a declarative schema library called PG Delta to replace sequential SQL migration histories with static, Git-tracked database definitions.
  • AI coding agents struggle with standard database workflows because reading a thousand historical migration files forces the model to guess the current table shape.
  • Running introspection queries against live database instances introduces round-trip network latency that stalls agent code generation loops.
  • Declarative schema files capture tables, Row Level Security policies, and database comments directly in a local project folder.
  • Code-first schemas treat the database as a set of file-system states so agents can inspect and edit data structures in milliseconds.

Why Sequential Migration Files Break AI Agents

For fifteen years, the software industry treated migration files as gospel. You write a migration, apply it, check it into version control, and append the next one to the bottom of the list. That historical ledger works well enough for human engineers who remember recent pull requests or rely on local test databases.

AI coding agents break this setup completely. Copplestone pointed out the mechanical failure of feeding historical logs to language models: “Imagine putting an agent across a thousand files and asking it, oh, what is the shape of this table? It has to guess through a thousand files.”

An agent examining a mature Postgres schema has two bad choices. It can parse hundreds of sequential SQL scripts, attempting to reconstruct alter table statements, dropped columns, and renamed foreign keys in its context window. Or it can spin up a local Postgres instance, execute the entire migration chain, and run introspection queries over network sockets. Both options crush iteration speed. Agents need instant answers on the file system, not a twenty-second database boot cycle.

Declarative Schemas and PG Delta

To make Postgres native to agentic workflows, Supabase introduced PG Delta. Instead of tracking database evolution as a chain of delta scripts, the tool converts the entire database into a declarative directory structure checked directly into Git.

Copplestone explained the architecture: “This year our big focus is moving to code-first, Git-native. So basically when you launch a Supabase instance inside your local machine you get this Supabase folder and it represents your database. It has all your functions, everything.” He added: “We've done our final change for declarative schemas. This was a really challenging one actually covering all of Postgres, and so now you can have a full file representation of Postgres, the shape of your database declaratively in your folder.”

PG Delta maps tables, Row Level Security policies, and SQL comments directly into static files. An agent trying to add a column or modify a policy does not need to author a new sequence file or query pg_catalog. It reads one file, edits the definition in place, and lets the tooling reconcile the target state. As Copplestone noted: “We know that agents are going to operate mostly on code. They don't want to reach out to anything. They've got to iterate very fast on the file system.”

Where Declarative Schemas Run into Reality

Declarative database management solves file access for agents, but stateful data migration introduces hard trade-offs. Dropping a column in a declarative schema file is a one-line deletion. In production, that same line might execute an irreversible data purge on a table with millions of rows.

Human teams still need drift detection and explicit state transitions for column renames, type coercions, and table partitions. If an agent changes an integer column to a text column in a declarative file, the automated migration engine must generate safe intermediate steps rather than a naive table rewrite. Declarative files give agents clear visibility into current state, but shipping those changes to production still requires human review of the generated diffs.

What to Do With This

Audit your repository's database schema folder before you point coding agents at your backend. If your application relies on a directory of hundreds of legacy migration scripts, extract your current database state into a single declarative schema file or generate a fresh schema dump. Place that current state file in the root context of your agent's workspace so it reads the exact schema in one pass without guessing across migration history.