graphsql

README

graph-sql

graph-sql is an SQL storage implementation for graph data structures created with graph.

Usage

0. Get your database up and running

If you don't have a database running, you may spin up a MariaDB container with a graph database to get started quickly.

docker run -e MARIADB_DATABASE=graph -e MARIADB_ROOT_PASSWORD=root -p 3306:3306 mariadb

1. Connect to your database

The first step is to establish a connection to your database server, more specifically to the actual database schema.

For instance, a connection to the MariaDB container from the example above can be established as follows:

package main

import (
	"database/sql"

	_ "github.com/go-sql-driver/mysql"
)

func main() {
	db, err := sql.Open("mysql", "root:root@tcp(localhost:3306)/graph")
	if err != nil {
		panic(err)
	}
}

2. Create a new store

Use the retrieved sql.DB instance to create a new store.

store := graphsql.New[int, int](db, graphsql.DefaultConfig)

The New function has two type parameters. These are the types of the vertex hashes and vertex values, and they have to be the same as for the graph itself. If you're not familiar with graph's hashing system, check out the concept of hashes.

This example uses a sane default configuration provided by this library, but you can configure it to your needs (see Configuration).

3. Set up the table schema

Create all required tables by calling SetupTables. This should only happen once.

if err := store.SetupTables(); err != nil {
	log.Fatal(err)
}

4. Create a graph backed by the store

Finally, the store instance can be passed to graph.NewWithStore, which will create a graph backed by this store.

g := graph.NewWithStore(graph.IntHash, store)

5. Full example

A complete program that utilizes a MariaDB database to store a graph of integers may look like as follows:

package main

import (
	"database/sql"
	"log"

	"github.com/dominikbraun/graph"
	graphsql "github.com/dominikbraun/graph-sql"
	_ "github.com/go-sql-driver/mysql"
)

func main() {
	db, err := sql.Open("mysql", "root:root@tcp(localhost:3306)/graph")
	if err != nil {
		panic(err)
	}

	store := graphsql.New[int, int](db, graphsql.DefaultConfig)

	if err = store.SetupTables(); err != nil {
		log.Fatal(err)
	}

	g := graph.NewWithStore(graph.IntHash, store)

	// This will persist two vertices and an edge in the database.
	_ = g.AddVertex(1)
	_ = g.AddVertex(2)
	_ = g.AddEdge(1, 2)
}

Configuration

The table schema created by graph-sql can be configured using a Config passed to New. You can either use the provided DefaultConfig or create your own one.

Field	Description	Default
VerticesTable	The name of the vertices table.	vertices
EdgesTable	The name of the edges table.	edges
VertexHashType	The database type of the vertex hashes.	TEXT
VertexValueType	The database type of the vertex values.*	JSON

*Vertex values are stored as JSON by this library.

Table schema

vertices

Column	Type	NULL	Key	Extra
id	BIGINT	No	Primary	AUTO_INCREMENT
hash	TEXT	Yes
value	JSON	Yes
weight	INT	Yes
attributes	JSON	Yes

edges

Column	Type	NULL	Key	Extra
id	BIGINT	No	Primary	AUTO_INCREMENT
source_hash	TEXT	Yes
target_hash	TEXT	Yes
weight	INT	Yes
attributes	JSON	Yes
data	BLOB	Yes

Graph operations

Check out the graph repository for an overview of built-in graph algorithms and operations.

Documentation

Index

• Variables
• type Config
• type Store
  • func New[K comparable, T any](db *sql.DB, config Config) *Store[K, T]
  • func (s *Store[K, T]) AddEdge(sourceHash, targetHash K, edge graph.Edge[K]) error
  • func (s *Store[K, T]) AddVertex(hash K, value T, properties graph.VertexProperties) error
  • func (s *Store[K, T]) DestroyTables() error
  • func (s *Store[K, T]) Edge(sourceHash, targetHash K) (graph.Edge[K], error)
  • func (s *Store[K, T]) EdgeCount() (int, error)
  • func (s *Store[K, T]) ListEdges() ([]graph.Edge[K], error)
  • func (s *Store[K, T]) ListVertices() ([]K, error)
  • func (s *Store[K, T]) RemoveEdge(sourceHash, targetHash K) error
  • func (s *Store[K, T]) RemoveVertex(hash K) error
  • func (s *Store[K, T]) SetupTables() error
  • func (s *Store[K, T]) UpdateEdge(sourceHash, targetHash K, edge graph.Edge[K]) error
  • func (s *Store[K, T]) Vertex(hash K) (T, graph.VertexProperties, error)
  • func (s *Store[K, T]) VertexCount() (int, error)

Variables

var DefaultConfig = Config{
	VerticesTable:   "vertices",
	EdgesTable:      "edges",
	VertexHashType:  "TEXT",
	VertexValueType: "JSON",
	Safe:            false,
	Unique:          false,
}

DefaultConfig is a sane default configuration of the table schema. Using DefaultConfig when creating a store using New makes sense for most users.

var SafeConfig = Config{
	VerticesTable:   "vertices",
	EdgesTable:      "edges",
	VertexHashType:  "TEXT",
	VertexValueType: "JSON",
	Safe:            true,
	Unique:          true,
}

Types

type Config

type Config struct {
	VerticesTable   string
	EdgesTable      string
	VertexHashType  string
	VertexValueType string
	Safe            bool
	Unique          bool
}

Config configures the table schema, i.e. the table names and some data types of its columns.

type Store

type Store[K comparable, T any] struct {
	// contains filtered or unexported fields
}

Store is a graph.Store implementation that uses an SQL database to store and retrieve graphs.

func New

func New[K comparable, T any](db *sql.DB, config Config) *Store[K, T]

New creates a new SQL store that can be passed to graph.NewWithStore. It expects a database connection directly to the actual database schema in the form of a sql.DB instance.

func (*Store[K, T]) AddEdge

func (s *Store[K, T]) AddEdge(sourceHash, targetHash K, edge graph.Edge[K]) error

AddEdge implements graph.Store.AddEdge.

func (*Store[K, T]) AddVertex

func (s *Store[K, T]) AddVertex(hash K, value T, properties graph.VertexProperties) error

AddVertex implements graph.Store.AddVertex.

func (*Store[K, T]) DestroyTables

func (s *Store[K, T]) DestroyTables() error

DestroyTables drops all tables and thus removes all data from the database.

func (*Store[K, T]) Edge

func (s *Store[K, T]) Edge(sourceHash, targetHash K) (graph.Edge[K], error)

Edge implements graph.Store.Edge.

func (*Store[K, T]) EdgeCount

func (s *Store[K, T]) EdgeCount() (int, error)

EdgeCount implements graph.Store.EdgeCount.

func (*Store[K, T]) ListEdges

func (s *Store[K, T]) ListEdges() ([]graph.Edge[K], error)

ListEdges implements graph.Store.ListEdges.

func (*Store[K, T]) ListVertices

func (s *Store[K, T]) ListVertices() ([]K, error)

ListVertices implements graph.Store.ListVertices.

func (*Store[K, T]) RemoveEdge

func (s *Store[K, T]) RemoveEdge(sourceHash, targetHash K) error

RemoveEdge implements graph.Store.RemoveEdge.

func (*Store[K, T]) RemoveVertex

func (s *Store[K, T]) RemoveVertex(hash K) error

RemoveVertex implements graph.Store.RemoveVertex. from https://github.com/dominikbraun/graph-sql/pull/3/files

func (*Store[K, T]) SetupTables

func (s *Store[K, T]) SetupTables() error

SetupTables creates all required tables inside the configured database. The schema is documented in this library's README file.

func (*Store[K, T]) UpdateEdge

func (s *Store[K, T]) UpdateEdge(sourceHash, targetHash K, edge graph.Edge[K]) error

func (*Store[K, T]) Vertex

func (s *Store[K, T]) Vertex(hash K) (T, graph.VertexProperties, error)

Vertex implements graph.Store.Vertex.

func (*Store[K, T]) VertexCount

func (s *Store[K, T]) VertexCount() (int, error)

VertexCount implements graph.Store.VertexCount.