fileio

Package fileio exposes SQL functions and a virtual table for reading and walking files. It mirrors the SQLite fileio.c misc extension and ncruces/ext/fileio.

• readfile(path) → BLOB: returns the contents of path, or NULL if the file does not exist. Errors on other I/O failures.

• writefile(path, data [, mode]) → INTEGER: writes data to path, returning the number of bytes written. mode is interpreted as a Go io/fs.FileMode integer. Creates intermediate directories as needed.

• lsmode(mode_int) → TEXT: the 10-character ls(1)-style rendering of a io/fs.FileMode integer (e.g. “drwxr-xr-x” for 0o20000000755).

• fsdir(root [, depth]) virtual table: recursively walks root. Columns:

  name TEXT – path relative to root mode INTEGER – io/fs.FileMode bits mtime INTEGER – modification time, Unix nanoseconds data BLOB – file contents for regular files; symlink target for symlinks (os-backed only); NULL otherwise level INTEGER – walk depth (1 for direct children of root) path HIDDEN – initial-root constraint (required) depth HIDDEN – optional max depth constraint

Two registration modes:

• Register — os-backed. readfile, writefile, lsmode, and fsdir all touch the local filesystem. Suitable when SQL is trusted (your own code) but a security boundary when SQL is untrusted (LLM agents, user-supplied queries).

• RegisterFS — sandboxed. Reads go through the supplied io/fs.FS; writefile is omitted entirely. Mirrors ext/lines’ two-mode shape; suitable for embedding read-only assets via embed.FS or for untrusted SQL over a fstest.MapFS.

Ported from ncruces/ext/fileio. Constraint planner support in fsdir is scoped to the root and depth columns; the ncruces “base” path-prefix optimization is deferred.

---

Full API: pkg.go.dev/gosqlite.org/ext/fileio