dirsql
Ephemeral SQL index over a local directory
Decision gist · record as of 2026-08-14
Yes, if you need to query structured files in a directory with SQL and want real-time change tracking. The native extension adds medium install friction but provides prebuilt wheels for common platforms. MIT license and active maintenance are favorable. No known vulnerabilities. Suitable for development, data analysis, and small-to-medium workloads.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python >= 3.10.
- Ships as native Rust extension; prebuilt wheels provided for macOS (x86_64, arm64), Linux (x86_64, aarch64), and Windows (x64).
- Medium install friction due to native Rust extension; prebuilt wheels cover common platforms (macOS x86_64/arm64, Linux x86_64/aarch64, Windows x64).
License · maintenance · safety
MIT (permissive) — MIT license permits commercial and private use with minimal restrictions; suitable for most projects.
last release 2026-08-12 (2 days)
0 known vulnerabilities (OSV.dev, 2026-08-14) · 176,965 downloads/mo, #10,228 on PyPI
Alternatives
Verify before relying
pip install dirsql
import asyncio
from dirsql import DirSQL, Table
async def main():
db = DirSQL("./my-blog", tables=[Table(ddl="CREATE TABLE posts (title TEXT, author TEXT)", glob="posts/*.json", extract=lambda path: [__import__('json').loads(open(path).read())])])
await db.ready()
posts = await db.query("SELECT * FROM posts WHERE author = 'alice'")
print(posts)
asyncio.run(main())- Performance characteristics for large directories or complex joins not specified
- Memory overhead for in-memory SQLite index relative to directory size not quantified
- Behavior when files are deleted or moved during active queries not documented
What it is and what it does
dirsql is a Python SDK that creates an ephemeral SQL interface over a filesystem directory. It watches for file changes, ingests structured files (JSON, etc.) into an in-memory SQLite database according to user-defined schemas and glob patterns, and exposes standard SQL queries. The filesystem remains the source of truth; the database is rebuilt from files on startup and kept in sync via background file watching.
You define tables by specifying DDL, a glob pattern to select files, and an extraction function that converts matched files into row dicts. dirsql handles the scanning and indexing asynchronously; you await db.ready() before querying. It supports multiple tables, joins, SQLite extensions, and an async iterator for row-level change events (insert, update, delete). A CLI tool is also included for one-off queries and an HTTP server mode.
Use it for
- Query a blog directory (posts and authors as JSON files) with SQL joins across tables
- Monitor a config directory for changes and react to inserts/updates/deletes via async events
- Index structured logs or data files and run ad-hoc SQL analysis without a separate database
- Load SQLite extensions and use them in queries over filesystem data
- Expose filesystem data over HTTP via the built-in server for remote SQL access
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you need to query structured files in a directory with SQL and want real-time change tracking.
The native extension adds medium install friction but provides prebuilt wheels for common platforms. MIT license and active maintenance are favorable. No known vulnerabilities. Suitable for development, data analysis, and small-to-medium workloads.
Install
dirsql on PyPI
Before you install
Medium install friction due to native Rust extension; prebuilt wheels cover common platforms (macOS x86_64/arm64, Linux x86_64/aarch64, Windows x64). Requires Python >= 3.10. Active maintenance with recent releases.
Requires Python >= 3.10. Ships as native Rust extension; prebuilt wheels provided for macOS (x86_64, arm64), Linux (x86_64, aarch64), and Windows (x64).
License in practice
MIT license permits commercial and private use with minimal restrictions; suitable for most projects.
Quickstart
pip install dirsql
import asyncio
from dirsql import DirSQL, Table
async def main():
db = DirSQL("./my-blog", tables=[Table(ddl="CREATE TABLE posts (title TEXT, author TEXT)", glob="posts/*.json", extract=lambda path: [__import__('json').loads(open(path).read())])])
await db.ready()
posts = await db.query("SELECT * FROM posts WHERE author = 'alice'")
print(posts)
asyncio.run(main())Verify before relying
- Performance characteristics for large directories or complex joins not specified
- Memory overhead for in-memory SQLite index relative to directory size not quantified
- Behavior when files are deleted or moved during active queries not documented
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Medium. Platform-specific wheel |
| Runtime dependencies | 2 packagestomlibin-shim |
| Maintenance | Actively maintained 2 days since the last release |
| First released | |
| Downloads | 176,965 / month, #10,228 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
Evidence: dirsql-0.4.20-cp310-abi3-macosx_10_12_x86_64.whl; dirsql-0.4.20-cp310-abi3-macosx_11_0_arm64.whl; dirsql-0.4.20-cp310-abi3-manylinux_2_39_aarch64.whl; dirsql-0.4.20-cp310-abi3-manylinux_2_39_x86_64.whl; dirsql-0.4.20-cp310-abi3-win_amd64.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “sql query filesystem directory”
- dirsqlWatches a local directory, indexes structured files into an in-memory…
- scandirProvides faster directory iteration and os.walk() replacement by…
- rospkgProvides Python access to ROS package metadata and filesystem…
Give your agent the search over MCP, or paste the wish link into any chat.
More Database packages
psycopg2-binary is a PostgreSQL database adapter for Python that implements the DB API 2.0 specification, enabling Python applications to connect to and query PostgreSQL databases with thread-safe concurrent operations.
Python client library for connecting to and executing commands against Redis key-value stores, supporting both synchronous and asynchronous operations.
Install it if your application needs to interact with Redis; the only prerequisite is a running Redis server instance.
YDB Python SDK is the official client library for connecting to and querying YDB databases from Python applications.
Install it if you need to connect Python applications to YDB databases.
Connects Python applications to Snowflake data warehouses using the DB API 2.0 specification, enabling SQL queries, data transfers, and warehouse operations.
sqlparse tokenizes SQL text into a tree of statements, clauses, and expressions, and provides functions to split scripts, format queries, and inspect parsed tokens without validating dialect or syntax.
Install it if you need to manipulate, format, or analyze SQL text programmatically.
Provides base adapter protocols and shared functionality that database adapters use to integrate with dbt-core, handling connections, dialect translation, relation caching, and core interface management.
See also libsql-client · osquery · aiosqlite · sqlite-utils · aiosql · qpd · dirsync · sqlitedict · apswutils · fastlite