dirsql (Python SDK)
Ephemeral SQL index over a local directory. dirsql watches a filesystem, ingests structured files into an in-memory SQLite database, and exposes a SQL query interface -- the filesystem is always the source of truth.
Also available as dirsql on crates.io and dirsql on npm.
Installation
pip install dirsql
Requires Python >= 3.12. Ships as a native extension (Rust via PyO3); prebuilt binary wheels are provided for common platforms.
Quick start
DirSQL is async by default: the constructor returns immediately, scanning runs in a background thread, and you await db.ready() before querying. Each table is a (ddl, glob, extract) triple: the DDL defines the SQLite schema, the glob selects files (relative to the root), and extract turns a matched file into a list of row dicts. dirsql does not read file contents -- if extract needs the file body it reads path itself; return an empty list to skip a file.
import asyncio
import json
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: [json.loads(open(path, encoding="utf-8").read())],
),
],
)
await db.ready()
posts = await db.query("SELECT * FROM posts WHERE author = 'alice'")
print(posts)
asyncio.run(main())
Multiple tables and joins
db = DirSQL(
"./my-blog",
tables=[
Table(
ddl="CREATE TABLE posts (title TEXT, author_id TEXT)",
glob="posts/*.json",
extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
),
Table(
ddl="CREATE TABLE authors (id TEXT, name TEXT)",
glob="authors/*.json",
extract=lambda path: [json.loads(open(path, encoding="utf-8").read())],
),
],
)
await db.ready()
results = await db.query("""
SELECT posts.title, authors.name
FROM posts JOIN authors ON posts.author_id = authors.id
""")
Ignoring files
Pass ignore patterns to skip files during scanning and watching:
db = DirSQL(
"./my-blog",
ignore=["**/drafts/**", "**/.git/**"],
tables=[...],
)
Path-table scans (SELECT ... FROM './') respect .gitignore files by
default. Pass no_ignore=True to restore the full walk; the built-in
node_modules/.git defaults and any ignore patterns still apply:
db = DirSQL("./my-blog", no_ignore=True)
Loading SQLite extensions
Pass extensions to load SQLite extension shared libraries onto the connection at startup (before any CREATE TABLE). Each entry is a dict with a path and an optional entrypoint init-symbol override:
db = DirSQL(
"./my-blog",
tables=[...],
extensions=[
{"path": "./ext/vec0.dylib", "entrypoint": "sqlite3_vec_init"},
{"path": "./ext/myext.so"}, # entrypoint derived from the filename
],
)
await db.ready()
# The extension's functions are now callable in queries:
rows = await db.query("SELECT vec_version() AS v")
dirsql enables extension loading only while loading the configured libraries, then disables it again, so the SQL load_extension() function is never exposed to your queries. Programmatic entries load first, followed by any [[dirsql.extension]] entries declared in a config file. See the config reference.
Watching for changes
db.watch() returns an async iterator of row-level change events as files change on disk:
async for event in db.watch():
print(f"{event.action} on {event.table}: {event.row}")
if event.action == "error":
print(f" error: {event.error}")
Each event has .action ("insert", "update", "delete", or "error"), .table, .row (the new row, or the deleted row on delete), .old_row (the previous row, on update), .file_path, and .error (on error).
CLI
pip install dirsql also installs a dirsql console script. dirsql "<sql>" (or uvx dirsql "<sql>") runs one query and prints the rows as JSON — the default. dirsql server starts an HTTP server exposing the SDK over HTTP: POST /query for SQL and GET /events for a Server-Sent Events change stream. See the CLI reference.
License
MIT
1 maintainer
Release files for dirsql 0.4.50
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dirsql-0.4.50.tar.gz | 484.5 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| dirsql-0.4.50-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| dirsql-0.4.50-cp310-abi3-manylinux_2_28_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| dirsql-0.4.50-cp310-abi3-manylinux_2_28_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| dirsql-0.4.50-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| dirsql-0.4.50-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 15.9 MB
Release files / dirsql-0.4.50.tar.gz
| Download URL | dirsql-0.4.50.tar.gz |
|---|---|
| Size | 484.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef58c92ccfea5bd7089bb95f8ce06664ec874f1f1fc45a95f3bbec535867f1b3
|
|
BLAKE2b-256 checksum How to use checksums |
2ee445380978b53578360a5f216cd54f158343b774dd98e4c3435cb0ef0b1b6e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / dirsql-0.4.50-cp310-abi3-win_amd64.whl
| Download URL | dirsql-0.4.50-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
035c958895f0c764a47abcf027abb3663500234ed4711e25bfe4f0896315094f
|
|
BLAKE2b-256 checksum How to use checksums |
743aab340c2c464e212c262980c107d276449ce81d61f71ba19b0ad74e6908a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / dirsql-0.4.50-cp310-abi3-manylinux_2_28_x86_64.whl
| Download URL | dirsql-0.4.50-cp310-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 3.2 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
2b1798fb4167a8d98ad155879b6065d9bf51056cfdbc9c65ccb0199429cc4bca
|
|
BLAKE2b-256 checksum How to use checksums |
82a9e1e7c9778bbfe7b319ab77b8a3b912859b0617c8754a860f329c497c38de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / dirsql-0.4.50-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | dirsql-0.4.50-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 3.1 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
1ae9dd4cc0eac44e4cbdf497021bcb4d10d85e1447cf41de09e27e268ba46ff0
|
|
BLAKE2b-256 checksum How to use checksums |
94267bd90a6687c5466deb8e8a987745b083e55085ec60c775e00ccac44e90a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / dirsql-0.4.50-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | dirsql-0.4.50-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
590504ae920b980c8481a08cbbc51d1f0e3c8d9d57d3b0d3843ab8f700cb9894
|
|
BLAKE2b-256 checksum How to use checksums |
f052bf1ad2cd045da8d4c4b4f5d8d5d97bdf3270fefb02396b0c6b48afb370f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / dirsql-0.4.50-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | dirsql-0.4.50-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
305607269dcf23246da5887f471a99417470eb425cd02c462e04420641621355
|
|
BLAKE2b-256 checksum How to use checksums |
43cf13ca970820b1fdf79628c0519920a3fe9df61f78db58696e27410c3844f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
