gograph

README

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 install dotnetage/tap/gograph

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)
	}
}

✨ 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.