GoGraph

The Minimalist Embedded Graph Database in Pure Go

简体中文 | English

---

📖 Project Overview

GoGraph is a lightweight, zero-dependency, embedded graph database written entirely in Go. Think of it as "SQLite for Graph Databases".

It allows Go developers to execute Cypher queries (the standard graph query language) and manage local graph data—nodes, relationships, and properties—without the overhead of external heavy database services like Neo4j.

⚡ Quick Start

1. Install CLI (Recommended)

The fastest way to explore GoGraph is via the CLI.

macOS / Linux (Homebrew):

brew tap dotnetage/gograph
brew install gograph

Linux

# Linux x86_64
curl -L https://github.com/DotNetAge/gograph/releases/download/v0.2.2/gograph-v0.2.2-linux-amd64.tar.gz -o gograph.tar.gz
tar -xzf gograph.tar.gz
sudo cp gograph-v0.2.2-linux-amd64/gograph /usr/local/bin/

# Test
gograph --version

Run TUI (Interactive Shell):

# Simply run without arguments to open default.db in interactive mode
gograph

2. Use as a Go Library

Add GoGraph to your project:

go get github.com/DotNetAge/gograph

Basic Example:

package main

import (
	"context"
	"fmt"
	"github.com/DotNetAge/gograph/pkg/api"
)

func main() {
	db, _ := api.Open("default.db")
	defer db.Close()

	ctx := context.Background()
	db.Exec(ctx, "CREATE (a:User {name: 'Alice'})-[:KNOWS]->(b:User {name: 'Bob'})")
	
	rows, _ := db.Query(ctx, "MATCH (u:User) RETURN u.name")
	defer rows.Close()
	
	for rows.Next() {
		var name string
		rows.Scan(&name)
		fmt.Println("User:", name)
	}
}

📝 CRUD Examples

Create

gograph exec "CREATE (a:User {name: 'Alice', age: 30})"
gograph exec "CREATE (a:User {name: 'Bob'})-[:KNOWS {since: 2020}]->(b:User {name: 'Charlie'})"

Read

gograph query "MATCH (u:User) RETURN u.name, u.age"
gograph query "MATCH (a:User)-[r:KNOWS]->(b:User) RETURN a.name, b.name, r.since"

Update

gograph exec "MATCH (u:User {name: 'Alice'}) SET u.age = 31"
gograph exec "MATCH (u:User {name: 'Bob'}) SET u:Admin"

Delete

gograph exec "MATCH (u:User {name: 'Alice'}) DELETE u"
gograph exec "MATCH (u:User) WHERE u.name = 'Bob' DETACH DELETE u"
gograph exec "MATCH ()-[r:KNOWS]->() WHERE r.since < 2020 DELETE r"

✨ Key Features

• 🚀 Pure Go: No CGO, seamless cross-platform support.
• 📦 Embedded: Zero-config, single-directory storage (Pebble DB).
• 🔍 Cypher Support: Native MATCH, CREATE, SET, DELETE.
• 🛡️ ACID: MVCC, thread-safety, and WAL recovery.
• 🛠️ TUI Included: Interactive shell with auto-completion and ASCII tables.

💻 CLI Usage

The gograph binary provides a powerful TUI and command-line utilities.

Command	Description
gograph	Launch Interactive TUI (default to default.db)
gograph query <cypher>	Run a read-only query
gograph exec <cypher>	Run a data modification command

Example:

gograph query "MATCH (n) RETURN n"

---

🧩 System Compatibility

• OS: macOS, Linux, Windows.
• Arch: amd64, arm64.

📚 Documentation

Check out the full Documentation or the Docs Folder.