{"id":48896025,"url":"https://github.com/vstorm-co/database-pydantic-ai","last_synced_at":"2026-04-16T11:04:54.188Z","repository":{"id":333871093,"uuid":"1138624286","full_name":"vstorm-co/database-pydantic-ai","owner":"vstorm-co","description":"Database toolset for PydanticAI — schema exploration, SQL queries, and data analysis with read-only mode, query validation, and row limits.","archived":false,"fork":false,"pushed_at":"2026-02-07T01:06:41.000Z","size":1473,"stargazers_count":13,"open_issues_count":3,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-14T14:13:21.451Z","etag":null,"topics":["ai","ai-agents","anthropic","clawdbot","databases","gemini","llm","openai","postgresql","pydantic","pydantic-ai","python","sql","sqlite3"],"latest_commit_sha":null,"homepage":"https://vstorm-co.github.io/database-pydantic-ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vstorm-co.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T23:01:01.000Z","updated_at":"2026-03-25T01:38:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vstorm-co/database-pydantic-ai","commit_stats":null,"previous_names":["vstorm-co/sql-toolset-pydantic-ai","vstorm-co/database-pydantic-ai"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vstorm-co/database-pydantic-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fdatabase-pydantic-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fdatabase-pydantic-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fdatabase-pydantic-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fdatabase-pydantic-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vstorm-co","download_url":"https://codeload.github.com/vstorm-co/database-pydantic-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fdatabase-pydantic-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31882902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T09:23:21.276Z","status":"ssl_error","status_checked_at":"2026-04-16T09:23:15.028Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","anthropic","clawdbot","databases","gemini","llm","openai","postgresql","pydantic","pydantic-ai","python","sql","sqlite3"],"created_at":"2026-04-16T11:04:49.741Z","updated_at":"2026-04-16T11:04:54.183Z","avatar_url":"https://github.com/vstorm-co.png","language":"Python","readme":"\u003ch1 align=\"center\"\u003eDatabase Toolset for Pydantic AI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eEmpower AI Agents with SQL Database Capabilities\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/database-pydantic-ai/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/database-pydantic-ai.svg\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/vstorm-co/database-pydantic-ai/actions/workflows/ci.yaml\"\u003e\u003cimg src=\"https://github.com/vstorm-co/database-pydantic-ai/actions/workflows/ci.yaml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/vstorm-co/database-pydantic-ai?branch=main\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/vstorm-co/database-pydantic-ai/badge.svg?branch=main\" alt=\"Coverage Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pydantic/pydantic-ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic\u0026logoColor=white\" alt=\"Pydantic AI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eMulti-Backend\u003c/b\u003e — SQLite \u0026amp; PostgreSQL\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003eSecurity-First\u003c/b\u003e — read-only mode \u0026amp; query validation\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003eResource Control\u003c/b\u003e — timeouts \u0026amp; row limits\n\u003c/p\u003e\n\n---\n\n**Database Toolset** provides everything your [Pydantic AI](https://ai.pydantic.dev/) agent needs to explore schemas, query data, and understand database structures — with built-in security and performance controls.\n\n\u003e **Full framework?** Check out [Pydantic Deep Agents](https://github.com/vstorm-co/pydantic-deepagents) — complete agent framework with planning, filesystem, subagents, and skills.\n\n## Use Cases\n\n| What You Want to Build | How This Toolset Helps |\n|------------------------|------------------------|\n| **Data Analysis Agent** | Query databases, explore schemas, sample data |\n| **Business Intelligence Bot** | Read-only access to production databases |\n| **Database Documentation** | Auto-discover schemas, tables, relationships |\n| **SQL Assistant** | Explain query plans, validate queries |\n| **Multi-DB Agent** | Unified interface across SQLite \u0026 PostgreSQL |\n\n## Installation\n\n```bash\npip install database-pydantic-ai\n```\n\nOr with uv:\n\n```bash\nuv add database-pydantic-ai\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom pydantic_ai import Agent\nfrom database_pydantic_ai import (\n    SQLiteDatabase,\n    SQLDatabaseDeps,\n    SQLITE_SYSTEM_PROMPT,\n    create_database_toolset,\n)\n\nasync def main():\n    async with SQLiteDatabase(\"data.db\") as db:\n        deps = SQLDatabaseDeps(database=db, read_only=True)\n        toolset = create_database_toolset()\n\n        agent = Agent(\n            \"openai:gpt-4o\",\n            deps_type=SQLDatabaseDeps,\n            toolsets=[toolset],\n            system_prompt=SQLITE_SYSTEM_PROMPT,\n        )\n\n        result = await agent.run(\n            \"What are the top 5 most expensive products?\",\n            deps=deps,\n        )\n        print(result.output)\n\nasyncio.run(main())\n```\n\n**That's it.** Your agent can now:\n\n- List all tables in the database (`list_tables`)\n- Get full schema overview (`get_schema`)\n- Describe table structures and relationships (`describe_table`)\n- Analyze query execution plans (`explain_query`)\n- Execute SQL queries with safety controls (`query`)\n\n## Available Backends\n\n| Backend | Driver | Use Case |\n|---------|--------|----------|\n| `SQLiteDatabase` | `aiosqlite` | Local files, prototyping, lightweight apps |\n| `PostgreSQLDatabase` | `asyncpg` | Production databases, connection pooling |\n\n### SQLite\n\n```python\nfrom database_pydantic_ai import SQLiteDatabase\n\nasync with SQLiteDatabase(\"data.db\", read_only=True) as db:\n    # Zero configuration, file-based\n    tables = await db.get_tables()\n```\n\n### PostgreSQL\n\n```python\nfrom database_pydantic_ai import PostgreSQLDatabase\n\nasync with PostgreSQLDatabase(\n    user=\"postgres\",\n    password=\"secret\",\n    db=\"mydb\",\n    host=\"localhost:5432\",\n    read_only=True,\n) as db:\n    # Connection pooling with asyncpg\n    schema = await db.get_schema()\n```\n\n## Available Tools\n\nThe `create_database_toolset()` provides 5 tools to the agent:\n\n| Tool | Returns | Description |\n|------|---------|-------------|\n| `list_tables` | `list[str]` | List all available tables |\n| `get_schema` | `SchemaInfo \\| str` | Full database structure overview |\n| `describe_table` | `TableInfo \\| str` | Detailed table columns, types, constraints |\n| `explain_query` | `str` | Query execution plan without running it |\n| `query` | `QueryResult` | Execute SQL with timeout and row limits |\n\n## Configuration\n\nThe `SQLDatabaseDeps` class controls the agent's database access:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `database` | `SQLDatabaseProtocol` | **Required** | Backend instance (SQLite or PostgreSQL) |\n| `read_only` | `bool` | `True` | Block destructive queries (INSERT, UPDATE, DELETE, ...) |\n| `max_rows` | `int` | `100` | Maximum rows returned per query |\n| `query_timeout` | `float` | `30.0` | Query timeout in seconds |\n\n## Security\n\nBuilt-in protection against accidental or malicious data modifications:\n\n- **Read-only mode** — blocks 15 dangerous SQL keywords (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, ...)\n- **Multi-statement prevention** — rejects queries with multiple statements\n- **Comment-aware parsing** — detects dangerous keywords even behind `--` and `/* */` comments\n- **CTE handling** — validates Common Table Expressions for write operations\n- **Query timeouts** — prevents runaway queries with `asyncio.wait_for()`\n- **Row limits** — caps result sets to prevent memory exhaustion\n\n## Examples\n\nRunnable examples are in the `examples/` directory:\n\n- **SQLite**: [examples/sql/sqlite](examples/sql/sqlite/README.md)\n- **PostgreSQL**: [examples/sql/postgresql](examples/sql/postgresql/README.md)\n\n```bash\nmake run-example-sqlite\nmake run-example-postgres\n```\n\n## Documentation\n\nFull documentation: [vstorm-co.github.io/database-pydantic-ai](https://vstorm-co.github.io/database-pydantic-ai/)\n\n## Related Projects\n\n| Package | Description |\n|---------|-------------|\n| [Pydantic Deep Agents](https://github.com/vstorm-co/pydantic-deepagents) | Full agent framework (planning, filesystem, subagents, skills) |\n| [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend) | File storage \u0026 sandbox backends |\n| [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo) | Task planning toolset |\n| [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) | Multi-agent orchestration |\n| [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | Context management |\n| [pydantic-ai](https://github.com/pydantic/pydantic-ai) | The foundation — agent framework by Pydantic |\n\n## Contributing\n\n```bash\ngit clone https://github.com/vstorm-co/database-pydantic-ai.git\ncd database-pydantic-ai\nmake install\nmake test  # 100% coverage required\nmake all   # format + lint + typecheck + test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/vstorm-co\"\u003evstorm-co\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fdatabase-pydantic-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvstorm-co%2Fdatabase-pydantic-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fdatabase-pydantic-ai/lists"}