React to file changes

dirsql watches the directory it indexes, so your tables update as files change — and GET /events pushes every row-level change to you as it happens. No polling, no diffing on your side.

1. Open the stream

With the server running (npx dirsql / uvx dirsql), subscribe from another terminal:

curl -N http://localhost:7117/events

The server immediately confirms the subscription is attached:

event: ready
data: {}

2. Change a file, receive an event

Create a file under the indexed directory:

echo 'second' > inbox/two.txt

The stream delivers the resulting row change:

event: row
data: {"action":"insert","file_path":"inbox/two.txt","old_row":null,"row":{"basename":"two.txt","ctime":1783170226,"dir":"inbox","ext":"txt","mtime":1783170226,"path":"inbox/two.txt","size":7},"table":"files"}

Edits arrive as update events carrying both the old and new row; deletions as delete. The full payload schema — including error events — is in event payloads.

Consuming it

Anything that speaks Server-Sent Events works — EventSource in a browser, an SSE client library, or plain curl -N in a shell pipeline. Two semantics worth designing around (stream semantics):

• Errors don't end the stream. A malformed file produces an error event and the stream continues — handle the event, don't reconnect.
• Slow consumers skip. A subscriber that falls behind misses the overflowed events rather than stalling the server. If you must not miss anything, re-query after catching up.

Notes

• Events reflect row changes, not raw filesystem events: a file edit that leaves a table's rows identical emits nothing, and one file change can emit several events. The diffing model is part of how dirsql thinks.
• Ignored files (Skip files you don't want indexed) never generate events.
• Embedding dirsql in a program? The SDK's watch() yields the same events in-process — see the SDK reference and Embed dirsql in your application.