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

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

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:

Configuration

The SQLDatabaseDeps class controls the agent's database access:

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

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}