Database Abstraction Wrapper for Graph Schemas
DAWGS is a Go library for working with property graphs through a shared database interface. Run graph queries on vanilla PostgreSQL without database plugins, or use Neo4j's native graph engine. DAWGS provides openCypher parsing, a PostgreSQL SQL translator, and Go APIs for graph queries, traversal, and batch updates.
| Backend | Query execution | Requirements |
|---|---|---|
| PostgreSQL | Translates supported openCypher queries to SQL. | PostgreSQL 16 or newer; 18 recommended. No graph extension required. |
| Neo4j | Executes Cypher through the native driver. | Neo4j using the Go v5 driver. |
Cypher support varies by backend. See syntax support and query compatibility for supported forms and limitations.
Install from your Go project:
go get github.com/specterops/dawgsUse the Go toolchain specified in go.mod. The driver packages are
drivers/pg and drivers/neo4j.
See the PostgreSQL driver guide for pool setup and runtime configuration.
PostgreSQL callers can set dawgs.Config.TraversalStateLimit and TraversalByteLimit
to override traversal admission budgets for their database operations. Zero inherits
the PostgreSQL session setting; see traversal limits
for units, defaults, and examples.
PostgreSQL automatically uses budgeted compact discovery for qualified directed
allShortestPaths queries with property or ID endpoint predicates. Open ranges
need no user-supplied hop limit. Direct endpoint-ID inequalities in the same
MATCH ... WHERE can exclude self-pairs while retaining compact search.
Normal Cypher reads and eligible
FetchAllShortestPaths builder calls establish their search snapshot automatically;
see compact all-shortest search
for supported shapes and transaction behavior.
To build and run unit tests from a checkout:
make build
make testFormatting, vet, and explicit test/coverage package selections exclude the generated
cypher/parser directory. Tests disable implicit vet; run make lint for authored-code vet checks.
Integration tests use a disposable PostgreSQL or Neo4j database selected by
CONNECTION_STRING. See testing for setup and commands.
The reachability cache publishes complete intermediates,
bounds repeated expansion after memo eviction, and releases settled in-flight result references.
The multi-relationship expansion regression checks
compare bounded traversals with exhaustive fixed patterns on both backends,
including path multiplicity, mutation state, fan-out timings, and PostgreSQL plans.
PostgreSQL fan-out fixtures refresh planner statistics before preparing their queries.
The path materialization experiment
checks complete path values and measures batching, wide properties, memory,
and time to first row, including LIMIT 1.
Measured findings and implementation follow-ups are recorded in the
path materialization study.
- PostgreSQL driver: connections, caches, schema upgrades, and storage.
- Query semantics: backend behavior and compatibility.
- Import and export: dump, load, scrub, and archive graphs.
- Development: formatting, tests, and contributor workflows.
- Benchmarking: performance captures and traversal qualification.
- All documentation: library utilities, architecture, and detailed references.
