Datamog

An educational Datalog you can run in your terminal, your browser, or your notebook.

Playground · Language spec · Walkthrough · Development

Datamog is a small Datalog dialect built for learning how Datalog works. You write Horn-clause rules over relations, and Datamog runs them on the backend of your choice (three SQL databases or two pure-TypeScript in-memory evaluators), all honouring the same language semantics. On top of the classic core (recursion, stratified negation, aggregates) it adds first-class support for JSON, algebraic data types, and a module system, and it ships with a browser playground, a VS Code extension, a REPL, and a Jupyter magic.

It is a teaching tool, not a production database. If you want to understand recursion, stratified negation, seminaive evaluation, or how Datalog compiles to SQL, and to learn it by reading, running, and stepping through code, this is for you.

Example

# ancestor.dl: who descends from whom
input predicate parent(name: string, child: string).

ancestor(X, Y) :- parent(X, Y).                  # base case
ancestor(X, Y) :- parent(X, Z), ancestor(Z, Y).  # recursive case

?- ancestor("alice", X).

bun run datamog ancestor.dl   # parent data loads from ./parent.csv by convention

Try it in the browser, no install needed

Highlights

• Five backends, one language. The same program runs on Postgres, SQLite, or sql.js through a SQL translator, or on the pure-TypeScript native / seminaive evaluators with no SQL at all, which is handy for tracing the semantics step by step. See the language spec.
• Nested data, first-class. A value type is the union of every JSON shape (null, primitives, arrays, objects) with subscript, slice, iteration, and structural equality that agree byte-for-byte across every backend. See Working with values.
• Algebraic data types via proof terms. Name a rule p(...) :: Ctor and the predicate becomes an ADT whose derivations are its values: enums, pairs, Peano naturals, lists, parse trees. See Proof terms.
• A module system. A file is a function from its input predicates to its outputs; bind an input with := to a data file or to an instance of another module. See Modules.
• Optional, checked types. Column types are inferred; annotate a column or a rule head when you want a contract, and inference checks it.
• Diagnostics that explain. Safety, arity, stratification, and finiteness checks report the offending source span, and the playground visualises a rejected negation or finiteness cycle.

Getting started

Datamog is a Bun/TypeScript project. You need Bun 1.3 or newer.

bun install                          # install workspace dependencies
bun run datamog                      # start the interactive REPL
bun run datamog path/to/program.dl   # run a program (in-memory SQLite by default)

Choose a backend, or preview the generated SQL without running it:

bun run datamog --backend native program.dl    # in-memory evaluator, easy to trace
bun run datamog --backend sqljs  program.dl     # SQLite compiled to WebAssembly
bun run datamog --dry-run        program.dl     # print the generated SQL, don't execute
DATABASE_URL=postgres://localhost/mydb bun run datamog --backend postgres program.dl

The CLI loads each input predicate p from a like-named data file next to the program (p.csv, p.jsonl, p.json, p.mmd), or from a file/URL/Google Sheet/GitHub path you pass explicitly. The CLI README covers data loading, output formats, and every flag.

Over 40 runnable programs live in packages/cli/examples/, covering transitive closure, stratified negation, aggregates, puzzles, JSON handling, proof-term ADTs, and Boolean-circuit solvers:

bun run datamog packages/cli/examples/family/family.dl

Playground

The playground is a zero-install, fully client-side IDE: write a program, attach CSV/JSONL data, and run the whole pipeline (parse, analyze, translate, execute) in your browser. SQL runs on sql.js (SQLite compiled to WASM); the native / seminaive evaluators run directly in JavaScript. It offers live diagnostics, jump-to-definition, a dependency-graph view, and a step-through trace of the in-memory evaluators. It is redeployed on every push to main.

bun run playground:dev     # run it locally

Packages

Datamog is a Bun-workspace monorepo. The pieces, from foundation to frontend:

Package	Description
datamog-parser	Langium grammar, generated parser, and AST types
datamog-core	Analyzer (safety, dependency graph, recursion), type inference
datamog-engine	SQL translator, executor, and the Backend / loader interfaces
datamog-backend-postgres	Postgres backend (via Bun.sql)
datamog-backend-sqlite	SQLite backend (via bun:sqlite, in-memory by default)
datamog-backend-sqljs	sql.js backend (SQLite compiled to WASM)
datamog-backend-native	In-memory naive evaluator (no SQL)
datamog-backend-seminaive	In-memory seminaive evaluator (no SQL)
datamog-csv	CSV loader
datamog-jsonl	JSONL loader
datamog-json	Whole-file JSON loader (single-row tables)
datamog-gsheet	Google Sheets loader
datamog-mermaid	Mermaid graph/flowchart loader
datamog-repl	Incremental REPL session engine
datamog-cli	Command-line interface
datamog-playground	Browser playground (Preact + sql.js, no server)
datamog-vscode	VS Code extension (highlighting + diagnostics)

A sibling Python package, datamog-magic, provides a %%datamog IPython/Jupyter cell magic that drives the CLI.

Documentation

• Language specification: the full reference for syntax, semantics, the type system, and SQL translation.
• Language walkthrough: the feature-by-feature tutorial (chapters 00-16 plus appendices), with runnable code and exercises.
• Case studies: a puzzle-driven companion that builds end-to-end solutions to bigger problems.
• Comparison with other Datalog systems: how Datamog relates to Soufflé, CodeQL, Datomic, DES, Flix, and others.
• Jupyter notebook tutorial: runnable %%datamog cells with pandas DataFrame binding.
• Embed tutorials: Markdown whose code blocks render as live, editable mini-playgrounds.
• FLOLAC 2026 course slides: Introduction to Logic Programming with Datalog.

Development

See DEVELOPMENT.md for the full guide. The essentials, run from the repository root:

bun test             # run all tests
bun run typecheck    # tsc -b across the workspace
bun run check        # lint and format check (biome); check:fix to auto-fix
bun run e2e          # Playwright e2e suite for the playground

License

MIT © 2026 Max Schaefer.

Trademarks

The Datamog mascot is original art, a play on the Mercedes-Benz Unimog; "Mercedes-Benz" and "Unimog" are trademarks of Mercedes-Benz Group AG. The Part 1 course material uses Pokémon as a running example; "Pokémon" and Pokémon names, types, moves, and abilities are trademarks of Nintendo, Creatures Inc., and GAME FREAK inc. All such marks are used only nominatively, for educational illustration; this project is not affiliated with or endorsed by their owners.