Why your coding agent guesses your schema, and how to stop it
Published
You ask your coding agent for a query and it joins on orders.customer_id. Your
column is orders.user_id. The query looks right, reads right, and fails. The
agent did not make a reasoning error. It was never shown the schema, so it wrote the most
likely one.
An agent that cannot see your tables will guess them, and its guesses are the average of every schema it has read. Yours is not average in the places that matter. The fix is not a better model. It is giving the agent the schema, in a form that stays true.
How agents get the schema wrong
- Plausible names.
created_atwhere you haveinserted_at;customerswhere you haveaccounts. - Plausible types. An integer id where yours is a UUID, or a float for a column you store as integer cents.
- Invented relationships. A join through a table that does not exist, because a schema like yours usually has one.
- Missing constraints. An insert that leaves out a column your table requires, or a delete that a foreign key will refuse.
Each of these costs a round trip: run, fail, paste the error, wait. All of them go away when the agent reads the schema first.
The usual fixes, and why they go stale
Pasting the schema into the conversation
It works for that conversation. It is gone in the next one, it is whatever version you happened to copy, and a large schema uses up context on tables the task never touches.
A schema file in the repository
Better, because the agent can find it. But a dump committed in March describes March. Nothing fails when it drifts, so nobody notices until the agent is confidently wrong in a new way.
Letting the agent read the ORM models
The models are current, but they describe the database as the code sees it. A column added by a hand-written migration, a constraint that exists only in the database, a table another service owns: none of it is there. And in a large codebase the agent has to find and read dozens of files to assemble one picture.
Connecting the agent to the database itself
This gives a true schema, and a great deal more than was asked for: the agent can now read rows. For a task that only needs table shapes, that is a credential and a privacy question you did not need to take on. The difference is covered in database MCP servers explained.
What works: a schema the agent can look up
The pattern that holds is the one you already use for people. Keep the schema in one place that is maintained, and let anyone who needs it, a new engineer or an agent, read it there when they need it. For an agent, “read it there” means a tool it can call.
DB Planner’s MCP server is that tool. The schema is a set of DBML documents in a project your team already edits and reviews. Connected, the agent can list the documents, read them, list the tables, and render the diagram. It reads what it needs for the task at hand, and it reads the current version every time.
{
"mcpServers": {
"db-planner": {
"type": "http",
"url": "https://api.dbplanner.io/mcp"
}
}
}The first call opens a browser to sign in. On the consent screen, turn write access off. A read-only connection is enforced by the server, so an agent that only needs to look can only look. Reading over MCP is part of the free plan.
Tell the agent to use it
A tool the agent may use is not a tool it will use. Put the instruction where your agent
reads its standing rules: CLAUDE.md for Claude Code, a rules file for Cursor.
## Database
The schema lives in the DB Planner project "Storefront", available through the
db-planner MCP server. Before writing a query, a migration, or a model:
1. Read the relevant documents from that project. Do not rely on memory or on
model files, which can lag behind.
2. Use the column names and types exactly as they appear there.
3. If the change needs a schema change, propose it in DB Planner first. Do not
write a migration for a design nobody has reviewed.The third rule is the one that pays off over time. It moves schema changes out of the middle of a coding task, where they happen as a side effect, and into a place where someone looks at them.
Keeping that one place true
A schema the agent can look up is only as good as its last update. Three ways it stays current:
- Design there first. If changes start as a proposal on the diagram and become a migration afterwards, the design is never behind.
- Link the code. A
schema.prisma, a Railsschema.rb, Django models, TypeORM entities, or an EF Core model in a GitHub repository can be linked to a project, which is then flagged when a push changes the file. - Re-import the database. A fresh dump from PostgreSQL, MySQL, or SQL Server replaces the picture with what is really there.
What changes once the agent can see
The obvious change is that queries run the first time. The less obvious one is that the agent starts catching things. Asked to add a feature, an agent that has read the schema will tell you the column it needs does not exist, instead of writing code against one it imagined. That is the moment to stop coding and design the change properly, with the agent drafting and a person deciding. For prompts that work in both modes, see prompts for designing a database with an AI agent.