Database Toolset for Pydantic AI

Empower AI Agents with SQL Database Capabilities

Multi-Backend — SQLite & PostgreSQL  •  Security-First — read-only mode & query validation  •  Resource Control — timeouts & row limits

---

Database Toolset provides everything your Pydantic AI agent needs to explore schemas, query data, and understand database structures — with built-in security and performance controls.

Full framework? Check out Pydantic Deep Agents — complete agent framework with planning, filesystem, subagents, and skills.

Use Cases

What You Want to Build	How This Toolset Helps
Data Analysis Agent	Query databases, explore schemas, sample data
Business Intelligence Bot	Read-only access to production databases
Database Documentation	Auto-discover schemas, tables, relationships
SQL Assistant	Explain query plans, validate queries
Multi-DB Agent	Unified interface across SQLite & PostgreSQL

Installation

pip install database-pydantic-ai

Or with uv:

uv add database-pydantic-ai

Quick Start

import asyncio
from pydantic_ai import Agent
from database_pydantic_ai import (
    SQLiteDatabase,
    SQLDatabaseDeps,
    SQLITE_SYSTEM_PROMPT,
    create_database_toolset,
)

async def main():
    async with SQLiteDatabase("data.db") as db:
        deps = SQLDatabaseDeps(database=db, read_only=True)
        toolset = create_database_toolset()

        agent = Agent(
            "openai:gpt-4o",
            deps_type=SQLDatabaseDeps,
            toolsets=[toolset],
            system_prompt=SQLITE_SYSTEM_PROMPT,
        )

        result = await agent.run(
            "What are the top 5 most expensive products?",
            deps=deps,
        )
        print(result.output)

asyncio.run(main())

That's it. Your agent can now:

• List all tables in the database (list_tables)
• Get full schema overview (get_schema)
• Describe table structures and relationships (describe_table)
• Analyze query execution plans (explain_query)
• Execute SQL queries with safety controls (query)

Available Backends

Backend	Driver	Use Case
SQLiteDatabase	aiosqlite	Local files, prototyping, lightweight apps
PostgreSQLDatabase	asyncpg	Production databases, connection pooling

SQLite

from database_pydantic_ai import SQLiteDatabase

async with SQLiteDatabase("data.db", read_only=True) as db:
    # Zero configuration, file-based
    tables = await db.get_tables()

PostgreSQL

from database_pydantic_ai import PostgreSQLDatabase

async with PostgreSQLDatabase(
    user="postgres",
    password="secret",
    db="mydb",
    host="localhost:5432",
    read_only=True,
) as db:
    # Connection pooling with asyncpg
    schema = await db.get_schema()

Available Tools

The create_database_toolset() provides 5 tools to the agent:

Tool	Returns	Description
list_tables	list[str]	List all available tables
get_schema	SchemaInfo | str	Full database structure overview
describe_table	TableInfo | str	Detailed table columns, types, constraints
explain_query	str	Query execution plan without running it
query	QueryResult	Execute SQL with timeout and row limits

Configuration

The SQLDatabaseDeps class controls the agent's database access:

Parameter	Type	Default	Description
database	SQLDatabaseProtocol	Required	Backend instance (SQLite or PostgreSQL)
read_only	bool	True	Block destructive queries (INSERT, UPDATE, DELETE, ...)
max_rows	int	100	Maximum rows returned per query
query_timeout	float	30.0	Query timeout in seconds

Security

Built-in protection against accidental or malicious data modifications:

• Read-only mode — blocks 15 dangerous SQL keywords (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, ...)
• Multi-statement prevention — rejects queries with multiple statements
• Comment-aware parsing — detects dangerous keywords even behind -- and /* */ comments
• CTE handling — validates Common Table Expressions for write operations
• Query timeouts — prevents runaway queries with asyncio.wait_for()
• Row limits — caps result sets to prevent memory exhaustion

Examples

Runnable examples are in the examples/ directory:

• SQLite: examples/sql/sqlite
• PostgreSQL: examples/sql/postgresql

make run-example-sqlite
make run-example-postgres

Documentation

Full documentation: vstorm-co.github.io/database-pydantic-ai

Related Projects

Package	Description
Pydantic Deep Agents	Full agent framework (planning, filesystem, subagents, skills)
pydantic-ai-backend	File storage & sandbox backends
pydantic-ai-todo	Task planning toolset
subagents-pydantic-ai	Multi-agent orchestration
summarization-pydantic-ai	Context management
pydantic-ai	The foundation — agent framework by Pydantic

Contributing

git clone https://github.com/vstorm-co/database-pydantic-ai.git
cd database-pydantic-ai
make install
make test  # 100% coverage required
make all   # format + lint + typecheck + test

See CONTRIBUTING.md for full guidelines.

License

MIT — see LICENSE

_{Built with ❤️ by vstorm-co}