commitdb

package module
v2.13.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

CommitDB

Go Reference Go Report Card

A Git-backed SQL database engine. Every transaction is a Git commit.

📚 Full Documentation

⚠️ Experimental Project - This is a hobby project and should not be used in any production environment.

Why CommitDB?

Traditional databases lose history. Once you UPDATE or DELETE, the old data is gone. CommitDB stores every change as a Git commit, giving you:

  • Complete audit trail - Know exactly who changed what and when
  • Instant rollback - Made a mistake? Restore any table to any point in time
  • Safe experimentation - Create a branch, try risky changes, merge if it works
  • Built-in backup - Push your entire database to GitHub/GitLab as a remote
  • No migration headaches - Branch your schema, test changes, merge when ready

Features

  • 🔄 Version history - Every change tracked, nothing lost
  • 🌿 Git branching - Experiment in branches, merge when ready
  • ⏪ Time travel - Restore any table to any previous state
  • 🔗 Remote sync - Push/pull to GitHub, GitLab, or any Git remote
  • 📡 Shared databases - Query and JOIN across external repositories

Quick Start

Go Library
import (
    commitdb "github.com/nickyhof/CommitDB/v2"
    "github.com/nickyhof/CommitDB/v2/core"
    "github.com/nickyhof/CommitDB/v2/persistence"
)

// In-memory
p, _ := persistence.NewMemoryPersistence()
instance := commitdb.Open(&p)

// Or file-backed (a real Git repo)
p, _ := persistence.NewFilePersistence("./mydata", nil)
instance := commitdb.Open(&p)

e := instance.Engine(core.Identity{Name: "Alice", Email: "[email protected]"})

e.Execute("CREATE DATABASE myapp")
e.Execute("CREATE TABLE myapp.users (id INT, name STRING)")
e.Execute("INSERT INTO myapp.users VALUES (1, 'Alice')")
result, _ := e.Execute("SELECT * FROM myapp.users")
result.Display()
CLI
# Install
go install github.com/nickyhof/CommitDB/v2/cmd/commitdb@latest

# In-memory mode
commitdb

# File-backed mode (creates a Git repo)
commitdb -dir ./mydata

# Execute SQL directly
commitdb -e "CREATE DATABASE myapp"

# Execute a SQL file
commitdb -dir ./mydata -f setup.sql

# Pipe SQL via stdin
echo "SHOW DATABASES;" | commitdb -dir ./mydata

Documentation

Performance

CommitDB vs DuckDB (1,000 rows, Apple M1 Pro):

Operation CommitDB DuckDB Ratio
INSERT 2.66 ms 0.19 ms 14x
SELECT * 1.39 ms 0.61 ms 2.3x
WHERE 1.42 ms 0.43 ms 3.3x
ORDER BY 2.07 ms 0.74 ms 2.8x
COUNT(*) 1.32 ms 0.11 ms 11.6x
SUM 1.36 ms 0.13 ms 10.3x
AVG 1.35 ms 0.13 ms 10.5x
GROUP BY 1.37 ms 0.43 ms 3.2x
LIMIT 1.32 ms 0.13 ms 10.5x
Complex 1.44 ms 0.53 ms 2.7x

Why is DuckDB faster? DuckDB is an OLAP-optimized columnar database built for analytics. CommitDB uses a row-based Git object model that trades raw query speed for:

  • Git-native storage - Every row is a Git blob, enabling branching, merging, and time travel
  • Full audit trail - Query any table at any point in history
  • Standard Git tooling - Push/pull to GitHub, diff changes, bisect bugs

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache 2.0

Documentation

Overview

Package commitdb provides a Git-backed SQL database engine.

CommitDB stores data using Git as the underlying storage mechanism, making every transaction a Git commit. This provides built-in version control, history tracking, and the ability to restore to any point in time.

Quick Start

Create an in-memory database: 

p, _ := persistence.NewMemoryPersistence()
db := commitdb.Open(&p)
e := db.Engine(core.Identity{Name: "App", Email: "[email protected]"})

e.Execute("CREATE DATABASE mydb")
e.Execute("CREATE TABLE mydb.users (id INT PRIMARY KEY, name STRING)")
e.Execute("INSERT INTO mydb.users (id, name) VALUES (1, 'Alice')")

result, _ := e.Execute("SELECT * FROM mydb.users")
result.Display()

Supported SQL

CommitDB supports a subset of SQL including:

  • CREATE/DROP DATABASE
  • CREATE/DROP TABLE
  • CREATE/DROP INDEX
  • INSERT, SELECT, UPDATE, DELETE
  • WHERE with comparison operators
  • ORDER BY, LIMIT, OFFSET
  • Aggregate functions: SUM, AVG, MIN, MAX, COUNT
  • GROUP BY, HAVING
  • JOINs: INNER, LEFT, RIGHT
  • DISTINCT
  • Transactions: BEGIN, COMMIT, ROLLBACK
Example 
package main

import (
	"fmt"

	commitdb "github.com/nickyhof/CommitDB/v2"
	"github.com/nickyhof/CommitDB/v2/core"
	"github.com/nickyhof/CommitDB/v2/engine"
	"github.com/nickyhof/CommitDB/v2/persistence"
)

func main() {
	// Create an in-memory database
	p, _ := persistence.NewMemoryPersistence()
	instance := commitdb.Open(&p)

	// Create an engine with identity (used for Git commit author)
	e := instance.Engine(core.Identity{
		Name:  "Example",
		Email: "[email protected]",
	})

	// Create a database and table
	e.Execute("CREATE DATABASE myapp")
	e.Execute("CREATE TABLE myapp.users (id INT PRIMARY KEY, name STRING)")

	// Insert data
	e.Execute("INSERT INTO myapp.users (id, name) VALUES (1, 'Alice')")
	e.Execute("INSERT INTO myapp.users (id, name) VALUES (2, 'Bob')")

	// Query data
	result, _ := e.Execute("SELECT name FROM myapp.users ORDER BY id")

	// Access result data
	qr := result.(engine.QueryResult)
	for _, row := range qr.Data {
		fmt.Println(row[0])
	}
}

Output:

Alice
Bob

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Instance 

type Instance struct {
	Persistence *persistence.Persistence
}

func Open 

func Open(p *persistence.Persistence) *Instance

func (*Instance) Engine 

func (instance *Instance) Engine(identity core.Identity) *engine.Engine
Example 
package main

import (
	"fmt"

	commitdb "github.com/nickyhof/CommitDB/v2"
	"github.com/nickyhof/CommitDB/v2/core"
	"github.com/nickyhof/CommitDB/v2/engine"
	"github.com/nickyhof/CommitDB/v2/persistence"
)

func main() {
	p, _ := persistence.NewMemoryPersistence()
	instance := commitdb.Open(&p)

	// Each engine has its own identity for Git commits
	alice := instance.Engine(core.Identity{Name: "Alice", Email: "[email protected]"})
	bob := instance.Engine(core.Identity{Name: "Bob", Email: "[email protected]"})

	alice.Execute("CREATE DATABASE demo")
	alice.Execute("CREATE TABLE demo.messages (id INT PRIMARY KEY, text STRING)")
	alice.Execute("INSERT INTO demo.messages (id, text) VALUES (1, 'Hello from Alice')")
	bob.Execute("INSERT INTO demo.messages (id, text) VALUES (2, 'Hello from Bob')")

	result, _ := alice.Execute("SELECT text FROM demo.messages ORDER BY id")
	qr := result.(engine.QueryResult)
	for _, row := range qr.Data {
		fmt.Println(row[0])
	}
}

Output:

Hello from Alice
Hello from Bob

Source Files

View all Source files

Directories

Path Synopsis
cmd
commitdb command
Package core provides core types used throughout CommitDB.
 Package core provides core types used throughout CommitDB.
Package engine provides the SQL execution engine for CommitDB.
 Package engine provides the SQL execution engine for CommitDB.
internal
compare
Package compare provides shared value comparison utilities for query evaluation and indexing.
 Package compare provides shared value comparison utilities for query evaluation and indexing.
ops
Package ops provides high-level operations for working with CommitDB databases and tables.
 Package ops provides high-level operations for working with CommitDB databases and tables.
sql
Package sql provides SQL lexing and parsing for CommitDB.
 Package sql provides SQL lexing and parsing for CommitDB.
Package persistence provides the persistence layer for CommitDB.
 Package persistence provides the persistence layer for CommitDB.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.