Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agno.com/llms.txt

Use this file to discover all available pages before exploring further.

DatabaseContextProvider gives agents read/write access to any SQL database via SQLAlchemy. Two tools: query_database for reads, update_database for writes.

​
Prerequisites

uv pip install -U agno sqlalchemy
# Plus your database driver:
uv pip install -U psycopg2-binary  # PostgreSQL
uv pip install -U pymysql          # MySQL

​
Example

from sqlalchemy import create_engine
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.context.database import DatabaseContextProvider

# Two engines: one read-only, one writable
readonly_engine = create_engine("postgresql://reader:pass@localhost/mydb")
sql_engine = create_engine("postgresql://writer:pass@localhost/mydb")

db = DatabaseContextProvider(
    sql_engine=sql_engine,
    readonly_engine=readonly_engine,
    schema="public",
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.4"),
    tools=db.get_tools(),
    instructions=db.instructions(),
)

agent.print_response("How many orders were placed last month?")
Both engines are required. The read sub-agent uses readonly_engine exclusively. Even if the model tries to run a write query, the database connection physically cannot execute it.

​
Provider Params

ParameterTypeDefaultDescription
sql_engineEnginerequiredSQLAlchemy engine for writes.
readonly_engineEnginerequiredSQLAlchemy engine for reads. Use a read replica or a user with SELECT-only permissions.
schemastr | NoneNoneScope queries to a specific schema.
idstr"database"Provider ID. Tools become query_<id> and update_<id>.
namestr | NoneNoneDisplay name. Defaults to id (“database”).
read_instructionsstr | NoneNoneCustom instructions for the read sub-agent.
write_instructionsstr | NoneNoneCustom instructions for the write sub-agent.
modeContextModedefaultTool exposure mode. See Architecture.
modelModel | NoneNoneModel for the sub-agents. Defaults to Agno’s default model.
readboolTrueExpose query_database tool.
writeboolTrueExpose update_database tool.

​
Tools Exposed

ToolDescription
query_databaseRun SELECT queries, describe tables, explore schema. Uses readonly_engine.
update_databaseRun INSERT/UPDATE/DELETE queries. Uses sql_engine.

​
Privilege Separation

The read and write sub-agents use separate database connections: 
query_database  → readonly_engine → read replica / SELECT-only user
update_database → sql_engine      → writable connection
This is infrastructure-level protection. The read sub-agent’s connection cannot execute writes regardless of what SQL the model generates.

​
Multiple Databases

Use different id values to expose multiple databases: 
orders_db = DatabaseContextProvider(
    id="orders",
    sql_engine=orders_write_engine,
    readonly_engine=orders_read_engine,
)

inventory_db = DatabaseContextProvider(
    id="inventory",
    sql_engine=inventory_write_engine,
    readonly_engine=inventory_read_engine,
)

agent = Agent(
    model=...,
    tools=[*orders_db.get_tools(), *inventory_db.get_tools()],
)
# Agent sees: query_orders, update_orders, query_inventory, update_inventory

​
Read-only Mode

db = DatabaseContextProvider(
    sql_engine=engine,
    readonly_engine=readonly_engine,
    write=False,
)
# Agent only sees query_database

​
Cookbook

Database Context Provider

Read/write with separate engines