go-puppetdb

PuppetDB query language (PQL) in pure Go — parser, in-memory evaluator and /pdb/query/v4 client.

pure Go · zero cgo PQL lexer / parser / AST AST-query JSON in-memory evaluator HTTP client HTTP server + ingestion embedded storage subqueries group by / aggregates 100% coverage 6 arches + wasm
Documentation GitHub
Documentation (MkDocs Material + mike) License: BSD-3-Clause Go 1.26.4+ Coverage 100%

go-puppetdb is a pragmatic, pure-Go (CGO_ENABLED=0) toolkit for PuppetDB. It provides a PQL lexer, parser and typed AST; a compiler to PuppetDB's canonical AST-query JSON wire form (and ParseAST, the inverse); an in-memory evaluator — with group by and count/avg/sum/min/max aggregation — so PQL is useful and fully testable without a server; an HTTP client for a real PuppetDB /pdb/query/v4 endpoint behind an injectable http.RoundTripper seam; command ingestion for the current wire formats (replace facts v5, replace catalog v9, store report v8); a pure-Go embedded storage backend (a JSON file, no external database); and an HTTP server exposing /pdb/query/v4 and /pdb/cmd/v1 on top of it. Entities (nodes, resources, facts, inventory, catalogs, reports, …), comparison / regexp / boolean operators, in subqueries, null tests, projection and order / limit / offset are all supported. Standard library only, 100% coverage, six arches and WebAssembly.

PQL front-end ready

Lexer, parser and typed AST for the PuppetDB entities (nodes, resources, facts, inventory, catalogs, reports, events, edges, fact_contents), comparison / regexp / boolean operators, in membership, null tests, projection and order / limit / offset.

AST-query compiler ready

Compile PQL to PuppetDB’s canonical ["from", entity, ["and", …]] JSON wire form via MarshalAST, the shape the HTTP API accepts directly.

In-memory evaluator ready

NewStore with recursive subquery evaluation, group by + count/avg/sum/min/max aggregation, ~> array matching, ordering, paging and projection, so a PQL query runs against an in-memory dataset — no server required, fully testable.

HTTP client ready

NewClient POSTs PQL or a compiled AST to a live /pdb/query/v4, with token auth, behind an injectable http.RoundTripper seam.

HTTP server, ingestion & storage ready

NewServer serves /pdb/query/v4 (PQL + AST) and ingests commands at /pdb/cmd/v1 — replace facts (v5), replace catalog (v9), store report (v8) — backed by a pure-Go embedded store (Open / Save / Snapshot / Load), a JSON file with no external database.

The PuppetDB engine of the go-puppetdb org: a PQL front-end, an AST-query compiler, an in-memory evaluator, an HTTP client, command ingestion, embedded storage and a PuppetDB-compatible HTTP server, all in dependency-free pure Go. Part of the pure-Go Puppet stack alongside go-facter, go-hiera, go-pcore and go-puppet.