Want Better AI-Generated SQL? Describe Your Schema.

When an AI agent writes a bad query against your database, the instinct is to blame the model. Sometimes that's fair. More often, the model did a reasonable job with terrible information, because your schema, on its own, doesn't actually say what your data means. A column named status that holds the integers 1 through 4 is a riddle, and you handed it to the model with no key.

The single highest-leverage thing you can do to improve AI-generated SQL isn't a better model. It's telling the model what your columns mean.

What the model sees vs what you know

You look at your schema and see a lifetime of accumulated context. You know users.type = 2 means an enterprise account, that deleted_at being non-null means soft-deleted so you have to filter it out, that amount is in cents not dollars, that the real revenue table is transactions and orders is a legacy thing nobody uses anymore.

The model sees column names and types. That's it. It doesn't know your conventions, your history, or which of your three user tables is the real one. So it does the only thing it can: it guesses from the names. And it guesses pretty well, which is exactly the danger, because a confident wrong guess returns a number that looks fine.

The gap between "what you know" and "what the schema literally says" is where almost every bad AI query comes from. Close that gap and the quality jump is dramatic and immediate.

The cheapest version: column comments

Postgres lets you attach comments to tables and columns, and they live right in the database where any tool can read them:

comment on column users.type is
  '1 = free, 2 = enterprise, 3 = internal/test account (exclude from revenue)';
 
comment on column orders.amount is
  'Total in cents (USD). Divide by 100 for dollars. Includes tax, excludes refunds.';
 
comment on table orders is
  'Legacy. New purchases write to transactions. Only pre-2024 data lives here.';

That's three comments, and they preempt three of the most common ways an agent gets your data wrong: misreading an enum, treating cents as dollars, and querying the dead table. Comments are free, they version with your schema, and good tooling surfaces them to the model automatically.

What to actually write down

You don't need to document everything. Document the things that would trip up a smart new hire on their first day, because that's exactly what the model is.

Write down the enums and what their values mean. Write down units (cents, milliseconds, bytes) wherever a number could be misread. Write down which columns are soft-delete flags that always need filtering. Write down which tables are deprecated and what replaced them. Write down the non-obvious joins, especially relationships your schema doesn't encode as foreign keys. And write down the definitions that are actually decisions — what "active" means, what counts as revenue — because the model can't infer a choice your company made in a meeting.

Skip the obvious. users.email doesn't need a comment. The point is to capture the tribal knowledge, not to annotate the self-explanatory.

Why this beats waiting for a smarter model

People assume better SQL is coming from better models, and some is. But there's a ceiling the model can't break through on its own, because the missing information was never in the schema to begin with. No model, however good, can know that status = 3 means "refunded" if that fact exists only in your head. That's not a reasoning problem. It's an information problem, and you're the only source.

This is why I think the leverage is so lopsided. A weaker model with good schema descriptions will write better queries for your database than a stronger model flying blind, because the descriptions supply the one thing no amount of model capability can substitute for: ground truth about what your data means.

It's also why QueryBear makes the descriptions a first-class thing rather than an afterthought — you annotate tables and columns once, and every query the agent writes inherits that context. But the principle stands wherever you point your agent. If you want better AI SQL, stop tuning the prompt and start documenting the schema. The model isn't the bottleneck. The missing context is.