from_db Query Tools

#Tool Surface

Agent.from_db() replaces provider-specific database tool names with a stable db_* surface where possible.

#SQL Sources

Tool	Purpose
`db_plan_query`	Convert a question into a structured query plan
`db_validate_sql`	Validate SQL against schema without executing it
`db_query`	Execute a read-only SQL query
`db_count`	Count rows in a table
`db_sample`	Return a small row sample
`db_execute`	Execute mutating SQL when `read_only=False`

#MongoDB Sources

Tool	Purpose
`db_find`	Find documents in a collection
`db_aggregate`	Run an aggregation pipeline
`db_count`	Count documents in a collection

#Planning Before SQL

Agents can use db_plan_query for analytic or multi-table questions:

text

User: What were total paid orders by customer segment last quarter?
Agent tool: db_plan_query
Agent tool: db_query

The plan can capture the goal, candidate tables, required fields, joins, filters, grouping, ordering, assumptions, and answer checks.

#SQL Validation

db_validate_sql checks generated SQL against the discovered schema before execution:

text

Tool: db_validate_sql
Args: {"sql": "SELECT customer_id, SUM(total) FROM orders GROUP BY customer_id"}

Validation can catch unknown tables, missing columns, invalid SQL shape, and required-field mismatches before the query runs.

#Query Execution

db_query executes read-only SQL:

text

Tool: db_query
Args: {"sql": "SELECT status, COUNT(*) AS orders FROM orders GROUP BY status LIMIT 20"}

When SQL omits LIMIT, the configured query_default_limit is applied. Results are bounded by query_max_rows, query_max_chars, query_timeout, and the tool result compaction policy.

#Counting and Sampling

Agents can use lightweight helpers before writing heavier SQL:

text

Tool: db_count
Args: {"table": "orders", "filter": "created_at >= CURRENT_DATE - INTERVAL '7 days'"}
 
Tool: db_sample
Args: {"table": "orders", "n": 5}

These tools are useful for orienting the model, checking table shape, and debugging assumptions.

#Optional Writes

db_execute is only available when the agent is not read-only:

python

agent = await Agent.from_db(
    "postgresql://user:pass@host/db",
    read_only=False,
)

Most production agents should keep read_only=True, which is the default for all built-in modes.

#Direct Queries vs Agent Tools

The db_* tools are primarily for agent use. If your script needs direct database access, use the underlying plugin directly:

python

from daita.plugins import postgresql
 
async with postgresql(host="localhost", database="analytics") as db:
    rows = await db.query("SELECT * FROM orders LIMIT 10")

Use Agent.from_db() when you want the LLM to plan, validate, run, and synthesize the answer.