README
¶
DAWGS
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.
Supported backends
| 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.
Get started
Install from your Go project:
go get github.com/specterops/dawgs
Use 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.
To build and run unit tests from a checkout:
make build
make test
Formatting, 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.
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.
Guides
- 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.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrDriverMissing indicates that Open has no constructor registered for the requested driver. ErrDriverMissing = errors.New("driver missing") )
Functions ¶
func Open ¶
Open invokes the registered driver constructor and returns ErrDriverMissing for an unknown name.
func Register ¶
func Register(driverName string, constructor DriverConstructor)
Register installs a constructor under driverName, replacing any previous registration. Call it during initialization before concurrent database opens.
Types ¶
type Config ¶
type Config struct {
// GraphQueryMemoryLimit bounds in-memory query results for drivers that enforce it.
GraphQueryMemoryLimit size.Size
// ConnectionString supplies the backend URI when the driver creates its connection pool.
ConnectionString string
// Pool supplies an existing PostgreSQL pool when supported by the selected driver.
Pool *pgxpool.Pool
}
Config supplies connection and memory settings to the selected driver constructor.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
benchmark
command
|
|
|
export
command
|
|
|
graphbench
command
|
|
|
plancorpus
command
|
|
|
retriever
command
|
|
|
cypher
|
|
|
internal
|
|
|
jsonutil
Package jsonutil provides shared JSON numeric conversions.
|
Package jsonutil provides shared JSON numeric conversions. |
|
v2
Package v2 contains the experimental fluent Cypher query builder.
|
Package v2 contains the experimental fluent Cypher query builder. |
|
Package retriever exports and imports Dawgs graph databases using the manifest-based retriever collection format.
|
Package retriever exports and imports Dawgs graph databases using the manifest-based retriever collection format. |
|
Package testutil provides reusable corpus, fixture, and baseline helpers for DAWGS tests and diagnostic commands.
|
Package testutil provides reusable corpus, fixture, and baseline helpers for DAWGS tests and diagnostic commands. |
|
tools
|
|
|
dawgrun/cmd/dawgrun
command
|
|
|
dawgrun/pkg/commands
Package commands holds all of the repl commands along with infrastructure types and helpers
|
Package commands holds all of the repl commands along with infrastructure types and helpers |
|
dawgrun/pkg/stubs
Package stubs has various bits and bobs to stub out internal behaviors
|
Package stubs has various bits and bobs to stub out internal behaviors |
|
metrics/cmd/dawgs-metrics
command
|
|