SQL Agent to Database Schema & Business Definitions

Updated 5 November 2026 · Standard formula, shown below

This guide walks you through connecting a SQL agent (an AI assistant that translates natural language into SQL queries) to your database schema and business definitions. By the end, the agent will understand your table structures, column meanings, and business rules, so it can generate accurate, context-aware queries.

What You’ll Need

Access to your database (read-only credentials are recommended for safety).
A SQL agent tool that supports custom schema and metadata configuration (e.g., LangChain, Vanna, or a proprietary assistant).
Your database’s connection string or host/port/database name.
A list of business terms and definitions (can be a simple text document or spreadsheet).
Permission to create or modify the agent’s configuration files or environment variables.

Step-by-Step

Identify your tables and views. Run a query to list all tables and views in your schema. For example, in PostgreSQL: SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'; In MySQL: SHOW TABLES; Note the ones that are relevant to your business questions.
Extract column metadata. For each table, get column names, data types, and nullability. In PostgreSQL: SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'your_table'; In MySQL: DESCRIBE your_table; Save this as a structured list (JSON or CSV).
Identify foreign keys and relationships. Look up foreign key constraints to understand how tables join. In PostgreSQL: SELECT conname, conrelid::regclass, pg_get_constraintdef(oid) FROM pg_constraint WHERE contype = 'f'; In MySQL: SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE WHERE REFERENCED_TABLE_NAME IS NOT NULL; Record these relationships.
Write business definitions. For each table and important column, write a plain-language description. For example: “orders.status: Current state of an order. Values: pending, shipped, delivered, cancelled.” Also define business terms like “active customer” (e.g., placed an order in the last 90 days) and “net revenue” (gross minus discounts and returns).

Format the schema for the agent. Most SQL agents accept a JSON or YAML schema file. Structure it like:

{
  "tables": [
    {
      "name": "orders",
      "description": "Customer orders",
      "columns": [
        {"name": "id", "type": "integer", "description": "Unique order ID"},
        {"name": "customer_id", "type": "integer", "description": "FK to customers.id"},
        {"name": "status", "type": "varchar", "description": "Order status: pending, shipped, delivered, cancelled"}
      ]
    }
  ]
}

If your tool has a UI, paste the schema there instead.

Load the schema into the agent. Use the tool’s API or configuration file to point to your schema file. For example, in LangChain you might set SQLDatabase.from_uri("postgresql://user:pass@host/db", schema=my_schema). For Vanna, you call vn.train(ddl=ddl_string) with your DDL.
Add business definitions as context. If your agent supports a “glossary” or “context” section, add your definitions there. If not, include them as comments in the schema file or as a separate document that the agent can reference.
Test with simple questions. Ask the agent things like “How many orders are pending?” and verify the SQL is correct. Check that it uses the right table names and columns.
Iterate on ambiguous terms. If the agent misinterprets a term, refine your business definitions. For example, if “active customer” is not defined, add it explicitly.
Set read-only access (recommended). Create a database user with SELECT-only privileges and use that for the agent connection to prevent accidental writes.

Common Mistakes

Not providing column descriptions. Without them, the agent guesses what a column means, leading to wrong joins or filters.
Ignoring relationships. If you don’t specify foreign keys, the agent may not know how to join tables, resulting in cartesian products or errors.
Using vague business terms. “Recent” or “high value” are ambiguous. Define them precisely (e.g., “last 30 days”, “total spend > $500”).
Overloading the schema. Including every table, even irrelevant ones, can confuse the agent. Focus on the tables your questions will use.
Not testing with edge cases. Try questions with date filters, NULL handling, and aggregates to ensure the agent handles them.

Tips

Use consistent naming. If your database uses snake_case, keep it. Don’t rename columns in the schema file unless necessary.
Include example queries. Some agents learn from examples. Provide a few natural language-to-SQL pairs that cover common patterns.
Keep business definitions up to date. When the schema changes, update the agent’s metadata.
Use a version control system for your schema and definitions files so you can track changes and roll back.
Start small. Connect one or two core tables first, test thoroughly, then expand.

Troubleshooting

Agent returns SQL with wrong table names. Check that the schema file matches the actual database. Run a query to list tables and compare.
Agent can’t connect to the database. Verify the connection string, network access, and that the database is running. Test with a simple client like psql or MySQL Workbench.
Agent ignores business definitions. Make sure the definitions are loaded in the correct format and location. Some tools require a separate API call or a specific file path.
Queries are slow. The agent may be generating queries without proper indexes. Review the SQL and add indexes if needed, or restrict the agent to use primary keys in WHERE clauses.
Ambiguous column names. If two tables have a column named “date”, the agent may not know which to use. Add descriptions like “order_date: date when the order was placed” and “ship_date: date when the order was shipped”.
Agent generates non-standard SQL. Ensure the agent is configured for your database dialect (e.g., PostgreSQL vs. MySQL). Some tools have a dialect parameter.

Frequently Asked Questions

Do I need to give the agent write access?

No. For query generation, read-only access is sufficient and safer. Use SELECT-only privileges to prevent accidental data modification.

Can I use a live database connection instead of a schema file?

Yes, many agents can introspect the database directly. However, providing a curated schema with descriptions often yields better results because you can add business context.

How do I handle a database with hundreds of tables?

Focus on the tables relevant to your domain. You can also use schema filtering options in some tools to limit which tables the agent sees.

What if my business definitions change frequently?

Keep them in a separate file that you can update without touching the schema. Reload the agent’s context after each change.

Can the agent learn from my past queries?

Some tools support fine-tuning or memory. Check your agent’s documentation for features like query history or feedback loops.

Is it possible to connect multiple databases?

Yes, but you’ll need to configure each connection separately and ensure the agent knows which database to use for each question.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.