How do you make your database schema understandable to AI models?

How do you make your database schema understandable to AI models?

Many companies have quietly built an invisible barrier between their data and the AI tools they now want to use. The database works — it has run the business for years. But connect an AI assistant or a natural-language query tool to it, and the results disappoint: invented columns, silently broken joins, reports that look right but aren't.

The root cause is rarely the AI. It's the schema. LLMs don't see your data the way the people who built the system do — they see table names, column headers, and constraints, and nothing else. When that text reads A1, val, or cust_sec_typ_v1_i, the model has almost no signal, so it guesses. This is part of the bigger AI-readiness question, but it's the fastest piece to fix.

Why this goes wrong

• Schema hallucinations — the model invents plausible columns (like orders.revenue) that don't exist in your system.
• Ambiguous names (val, flag, date) force the model to guess, and errors compound as queries get more complex.
• Misleading names are the most dangerous failure: a revenue column that actually stores click counts produces a query that runs and looks right, but answers the wrong question.
• Inconsistent naming (customer_id vs custID) breaks joins across tables and corrupts agentic pipelines silently.

What makes a schema legible

• Descriptive, conventional names — order_total, created_at, customer_id, not tot, tm, cid. Standardize _id, _at, _amount across the whole database.
• A semantic layer of descriptions — every table and column gets a natural-language explanation: what it means, valid values, units, NULL semantics. This is the single highest-leverage fix.
• Enums and named constraints — enums define valid values; a constraint named projects_budget_spent_valid encodes a business rule without a separate comment.
• Schema stored as versioned code — files an agent can search and read, not just live database metadata, so you can add comments and tests without a migration. See our companion how-to: writing AI-friendly COMMENT ON descriptions in PostgreSQL.

The evidence

• Tiger Data found text-to-SQL accuracy rising from 58% to 86% on certain schemas after adding COMMENT ON descriptions, though they note results vary by dataset and model. Source
• Atlas benchmarked three agents on the same 43-table PostgreSQL database: one given only a connection string, one the full DDL, one a structured schema directory. The structured version answered all 10 questions correctly using 37% fewer tokens than the single-file version. Source
• AWS and Pinterest have both published similar approaches — enriching metadata and retrieving relevant schema context — for their own text-to-SQL systems.

A quick example

Before:

CREATE TABLE r (id INT, c INT, d DATE, a NUMERIC, s VARCHAR(1));

An AI asked for "revenue by customer last month" has to guess which column is which.

After:

CREATE TABLE orders ( order_id BIGINT PRIMARY KEY, customer_id BIGINT REFERENCES customers(customer_id), order_placed_at TIMESTAMPTZ, order_total NUMERIC(12,2), order_status order_status_enum ); COMMENT ON COLUMN orders.order_total IS 'Gross order value in EUR before discounts, including VAT.';

Now the model knows exactly which column is revenue, which is the join key, and which rows to exclude.

Checklist: is your schema ready for AI?

• Descriptive, conventional names — no A1, val, single-letter columns
• Every table and column has a natural-language description
• Relationships and foreign keys are explicit
• Enums used for bounded values; CHECK constraints are named
• Business logic lives in named functions and views, not buried in raw columns
• Schema is stored as versioned, searchable code
• Field names are locked and never regenerated by an LLM

FAQ

What's the single most impactful fix? Add natural-language descriptions to your tables and columns — it's the change with the best-documented accuracy gains.

Do I have to rename all my columns? No. Renaming is risky since other code depends on exact names. Add descriptions first; rename only where a name is actively misleading.

Won't this get stale as the schema changes? Not if descriptions live in version control alongside the schema itself, so they update the same way your code does.

Start small: pick the handful of tables your analytics and automation touch most, describe them, and measure the difference. If your business runs on a custom database application, a platform like Claris FileMaker can help you organize and expose that schema so both your people and your AI can use it with confidence.

Related reading: Is your company ready for AI? · Clean data as the foundation for AI · What is text-to-SQL?