Query Databases with AI

The Database Tool connects to a database using SQLAlchemy under the hood and gives an agent the ability to query the database and get information about its tables. It exposes three functions: list_tables (list the tables in the database schema), describe_tables (describe the schema of a table), and load_data (accepts an SQL query and returns the result). It is designed to be used as a way to load data as a Tool in an Agent.

Use it when an agent needs to explore an existing database's schema or run SQL queries against it -- for example answering "What tables does this database contain," "Describe the first table," and "Retrieve the first row of that table" in sequence. Because SQLAlchemy is doing the connecting, it works with any SQLAlchemy-supported database (the example uses PostgreSQL), but it needs working connection credentials, so it is not usable without an accessible database instance.

Setup takes standard database connection parameters -- scheme, host, port, user, password, and database name -- passed to DatabaseToolSpec, then attached to an agent via to_tool_list():

from llama_index.tools.database import DatabaseToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

db_tools = DatabaseToolSpec(
    scheme="postgresql",  # Database Scheme
    host="localhost",  # Database Host
    port="5432",  # Database Port
    user="postgres",  # Database User
    [REDACTED],  # Database Password
    dbname="postgres",  # Database Name
)
agent = FunctionAgent(
    tools=db_tools.to_tool_list(),
    llm=OpenAI(model="gpt-4.1"),
)

print(await agent.run("What tables does this database contain"))
print(await agent.run("Describe the first table"))
print(await agent.run("Retrieve the first row of that table"))

Developers building LlamaIndex agents that need natural-language access to a SQL database's schema and contents without writing SQL by hand for every request.