reldir

A relational database that lives in a folder of JSON files.

reldir governs an ordinary folder – one directory per table, one JSON file per row – as a relational database. The files stay the source of truth: you, your editor, your scripts and git read and write them directly. reldir adds a schema for every table, references between rows, SQL over all of it, changes validated before a byte is written, and a verified history of every state the folder has been in.

$ reldir sql 'SELECT u.name, count(*) AS posts FROM users u JOIN posts p ON p.user_id = u.id GROUP BY u.name ORDER BY u.name'
name  | posts
------+------
Ada   | 1
Grace | 1
(2 rows)
2 row(s)
$ reldir delete users ada
error[FOREIGN_KEY_VIOLATION]: deleting users/ada.json refused: posts/p1.json still references it at /user_id (posts.user_id -> users, onDelete restrict)
  --> posts/p1.json:3:14
[..]

• Adopts a folder as it is, inferring each table’s schema from its files and changing none of them.
• Keeps the folder’s contract: nothing reldir writes leaves the shape the files had, unless you widen it.
• Writes only what changes, down to number spelling and indentation, and many files at once or not at all.
• Answers SQL in SQLite’s dialect, and enforces keys, references, checks and assertions beside every rule of JSON Schema 2020-12.
• Judges outside edits to their file, line and column, and repairs them.
• Keeps history, merges with git, serves AI agents over MCP, and embeds in Rust, Python and Node.js.

Tutorial

Getting started	from an empty folder to a database we query, change, repair and look back through

How-to guides

Install reldir	the command and the Python and Node.js libraries
Put an existing folder under reldir	adopt a folder of JSON without changing a file
Declare a new table	write a table’s schema yourself
Write a value the contract does not admit	widen a table’s contract, deliberately
Change the shape of a table	migrate schemas and rows together
Import and export rows	JSON, JSONL, CSV and Parquet, in bulk
Repair an invalid database	from INVALID back to VALID
Undo a change	find a change and go back before it
Recover	after an interrupted change, or damaged metadata
Retry a change safely	never apply a change twice
Merge and diff with git	row files that merge member by member
Check a database in CI	fail a build on a fault, annotate the pull request
Give an AI agent access	the database over MCP
Keep a large folder fast	up to a million rows

Reference

CLI	every command and flag
SQL	queries, changes, types, scripts, the shell
Schemas	the schema dialect
Validation	check, lint and doctor
Migrations	every migration operation
History and snapshots	revisions, snapshots, gc
Git integration	the merge and diff drivers, the CI action
MCP server	tools, resources and prompts
Machine protocol	the JSON every command speaks
Errors	every code and exit status
Configuration	.db/config
Storage format	what is on disk, byte for byte
Python, Node.js, Rust	the libraries
Stability	what semantic versioning covers

Explanation

Concepts	the folder as the database, the observed contract, identity, history
Transactions	how a change across many files lands whole
Performance	why a command costs what changed, not what exists
Security	what reldir trusts, and why
reldir beside other tools	SQLite, DuckDB, Dolt and flat-file stores

This site is open source. Improve this page.