Holocron

A declarative schema & query compiler — one YAML file as the single source of truth for your SQL schema and a type-checked query catalog.

What is this?

Holocron is a compiler whose target language is SQL. You write one declarative YAML file that defines both:

1. your database schema (tables, views, indexes), and
2. a semantic rulebook — which columns are filterable/searchable/sortable, what the aggregates and entities are, who owns a row, which view is the default list.

From that single file it produces the physical schema and an in-memory catalog. Any query — written in RSQL (compact, URL-friendly) or YAML (full specs) — is type-checked against the catalog before it runs: unknown field, not-filterable, wrong-operator-for-type are caught at build time, with no database connection needed, because the YAML is the schema.

Why

ORMs are code-first and language-bound, and migration tools know nothing about how the app is allowed to use the data. Holocron's novel piece is the bridge: one declarative source that is simultaneously the physical schema and the application's query/authz/read contract, consumable from any language.

The guarantee: any query that compiles is well-formed against the declared schema — every field exists, is allowed, and is used with a valid operator for its type — and produces runnable SQL.

Status

🚧 Active development. The compiler pipeline parses, builds a catalog, resolves views, type-checks queries, and emits PostgreSQL DDL end-to-end — with rich, rustc-style diagnostics that underline the exact YAML token at fault. The LSP server gives live in-editor squiggles. Still in flight: error-collection (currently bail-on-first), DML emit, and the RSQL parser. Full roadmap in holocron-seed/DESIGN.md.

Install

cargo install holocron         # the CLI compiler
cargo install holocron-lsp     # the LSP server (separate crate)

The LSP server lives in its own repo (holocron-lang/holocron-lsp) so the CLI install stays slim — no tokio/tower-lsp deps for users who only need YAML → SQL.

Or download pre-built archives for macOS / Linux / Windows from the latest GitHub Release (holocron-lsp ships from its own releases).

To use the compiler as a Rust library:

cargo add holocron

Usage

Schema files conventionally use the .holocron.yaml extension — the editor LSP picks that up automatically. See samples/ for a dozen-plus working examples plus error samples demonstrating every diagnostic.

holocron samples/blog.holocron.yaml     # YAML → PostgreSQL DDL on stdout
cat schema.holocron.yaml | holocron     # or pipe from stdin
holocron --help

Editor integration

holocron-lsp speaks standard LSP. Open a .holocron.yaml file in your editor and unknown columns, duplicate aliases, type mismatches, etc. underline in real time with the same diagnostics you'd see at the CLI.

Zed (project .zed/settings.json)

{
  "lsp": {
    "holocron": {
      "binary": {
        "path": "/path/to/holocron-lsp",
        "arguments": []
      }
    }
  },
  "languages": {
    "YAML": { "language_servers": ["holocron"] }
  }
}

Make sure the project is trusted in Zed; otherwise project-level settings (including this one) are ignored.

JetBrains (RustRover, IntelliJ, …) via LSP4IJ

1. Install the LSP4IJ plugin from the Marketplace.
2. Settings → Languages & Frameworks → Language Servers → + (New Language Server).
3. Command: the path to holocron-lsp.
4. Mappings tab → File name patterns: *.holocron.yaml.
5. Language Id: leave empty.

Other editors

holocron-lsp is a stdio LSP server. Any LSP client works — point it at the binary and associate *.holocron.yaml.

Development

This project uses Conventional Commits. Releases are fully automated: merging to main bumps the version, updates the changelog, tags, publishes to crates.io, and creates a GitHub Release with binary archives for every supported platform.

cargo build      # build
cargo test       # run tests
cargo doc --open # build & view the docs

pre-commit hooks mirror CI (formatting, clippy, tests, commit linting):

pre-commit install --install-hooks --hook-type commit-msg

License

Licensed under the Mozilla Public License 2.0.