{"id":13831976,"url":"https://github.com/gogitdb/gitdb","last_synced_at":"2026-03-14T04:03:39.832Z","repository":{"id":42561194,"uuid":"261045857","full_name":"gogitdb/gitdb","owner":"gogitdb","description":"Distributed Embeddable Database","archived":false,"fork":false,"pushed_at":"2022-07-22T10:28:05.000Z","size":316,"stargazers_count":255,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-05T10:19:45.067Z","etag":null,"topics":["database","document-database","embedded","git","gitdb","go","golang","library"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gogitdb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-04T00:13:25.000Z","updated_at":"2024-06-08T03:08:16.000Z","dependencies_parsed_at":"2022-09-11T15:10:42.204Z","dependency_job_id":null,"html_url":"https://github.com/gogitdb/gitdb","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogitdb%2Fgitdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogitdb%2Fgitdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogitdb%2Fgitdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogitdb%2Fgitdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gogitdb","download_url":"https://codeload.github.com/gogitdb/gitdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225565961,"owners_count":17489290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","document-database","embedded","git","gitdb","go","golang","library"],"created_at":"2024-08-04T10:01:46.417Z","updated_at":"2025-12-16T02:16:16.452Z","avatar_url":"https://github.com/gogitdb.png","language":"Go","readme":"GitDB\n=====\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/gogitdb/gitdb?style=flat-square)](https://goreportcard.com/report/github.com/gogitdb/gitdb)\n[![Coverage](https://codecov.io/gh/gogitdb/gitdb/branch/develop/graph/badge.svg)](https://codecov.io/gh/gogitdb/gitdb)\n[![Build Status Travis](https://img.shields.io/travis/gogitdb/gitdb.svg?style=flat-square\u0026\u0026branch=master)](https://travis-ci.com/gogitdb/gitdb)\n[![Godoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://godoc.org/github.com/gogitdb/gitdb)\n[![Releases](https://img.shields.io/github/release/gogitdb/gitdb/all.svg?style=flat-square)](https://github.com/gogitdb/gitdb/releases)\n[![LICENSE](https://img.shields.io/github/license/gogitdb/gitdb.svg?style=flat-square)](https://github.com/gogitdb/gitdb/blob/master/LICENSE)\n\n## What is GitDB?\n\n\u003e GitDB is not a binary. It’s a library!\n\nGitDB is a decentralized document database written in Go that uses [Git](https://git-scm.com/) under the hood to provide database-like functionalities via strictly defined interfaces. \n\nGitDB allows developers to create Models of objects in their application which implement a Model Interface that can access it's persistence features. This allows GitDB to work with these objects in database operations. \n\n## Why GitDB - motivation behind project?\n\n- A need for a database that was quick and simple to set up\n- A need for a database that was decentralized and each participating client in a system can store their data independent of other clients.\n\n\n## Features\n\n- Decentralized\n- Document store\n- Embedded into your go application\n- Encryption (encrypt on write, decrypt on read)\n- Record locking.\n- Simple Indexing System\n- Transactions\n- Web UI \n\n\n## Project versioning\n\nGitDB uses [semantic versioning](http://semver.org).\nAPI should not change between patch and minor releases.\nNew minor versions may add additional features to the API.\n\n## Table of Contents\n\n  - [Getting Started](#getting-started)\n    - [Installing](#installing)\n    - [Configuration](#configuration)\n    - [Opening a database](#opening-a-database)\n    - [Inserting/Updating a record](#insertingupdating-a-record)\n    - [Fetching a single record](#fetching-a-single-record)\n    - [Fetching all records in a dataset](#fetching-all-records-in-a-dataset)\n    - [Deleting a record](#deleting-a-record)\n    - [Search for records](#search-for-records)\n    - [Transactions](#transactions)\n    - [Encryption](#encryption)\n  - [Resources](#resources)\n  - [Caveats \u0026 Limitations](#caveats--limitations)\n  - [Reading the Source](#reading-the-source)\n  \u003c!-- - [Other Projects Using GitDB](#other-projects-using-gitdb) --\u003e\n\n## Getting Started\n\n### Installing\n\nTo start using GitDB, install Go and run `go get`:\n\n```sh\n$ go get github.com/gogitdb/gitdb/v2\n```\n\n\n### Configuration\n\nBelow are configuration options provided by GitDB\n\u003ctable\u003e\n  \u003ctr style=\"font-weight:bold;\"\u003e\n    \u003ctd\u003eName\u003c/td\u003e\n    \u003ctd width=\"600\"\u003eDescription\u003c/td\u003e\n    \u003ctd\u003eType\u003c/td\u003e\n    \u003ctd\u003eRequired\u003c/td\u003e\n    \u003ctd\u003eDefault\u003c/td\u003e\n  \u003ctr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eDbPath\u003c/td\u003e\n    \u003ctd\u003ePath on your machine where you want GitDB to create/clone your database\u003c/td\u003e\n    \u003ctd\u003estring\u003c/td\u003e\n    \u003ctd\u003eY\u003c/td\u003e\n    \u003ctd\u003eN/A\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eConnectionName\u003c/td\u003e\n    \u003ctd\u003eUnique name for gitdb connection. Use this when opening multiple GitDB connections\u003c/td\u003e\n    \u003ctd\u003estring\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003e\"default\"\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eOnlineRemote\u003c/td\u003e\n    \u003ctd\u003eURL for remote git server you want GitDB to sync with e.g git@github.com:user/db.git or https://github.com/user/db.git.\n    \u003cp\u003e\u003cstrong\u003eNote: The first time GitDB runs, it will automatically generate ssh keys and will automatically attempt to use this key to sync with the OnlineRemote,\n    therefore ensure that the generated keys are added to this git server. The ssh keys can be found at \u003ci\u003eConfig.DbPath/.gitdb/ssh\u003c/i\u003e\u003c/strong\u003e\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd\u003estring\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003e\"\"\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eSyncInterval\u003c/td\u003e\n    \u003ctd\u003eThis controls how often you want GitDB to sync with the online remote\u003c/td\u003e\n    \u003ctd\u003etime.Duration.\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003e5s\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eEncryptionKey\u003c/td\u003e\n    \u003ctd\u003e16,24 or 32 byte string used to provide AES encryption for Models that implement ShouldEncrypt\u003c/td\u003e\n    \u003ctd\u003estring\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003e\"\"\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eUser\u003c/td\u003e\n    \u003ctd\u003eThis specifies the user connected to the Gitdb and will be used to commit all changes to the database\u003c/td\u003e\n    \u003ctd\u003egitdb.User\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003eghost \u0026#x3C;ghost@gitdb.local\u0026#x3E;\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eEnableUI\u003c/td\u003e\n    \u003ctd\u003eUse this option to enable GitDB web user interface\u003c/td\u003e\n    \u003ctd\u003ebool\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003efalse\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eUIPort\u003c/td\u003e\n    \u003ctd\u003eUse this option to change the default port which GitDB uses to serve it's web user interface\u003c/td\u003e\n    \u003ctd\u003eint\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003e4120\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eFactory\u003c/td\u003e\n    \u003ctd\u003eFor backward compatibity with v1. In v1 GitDB needed a factory method to be able construct concrete Model for certain database operations.\n    This has now been dropped in v2\n    \u003c/td\u003e\n    \u003ctd\u003efunc(dataset string) gitdb.Model\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003enil\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eMock\u003c/td\u003e\n    \u003ctd\u003eFlag used for testing apps. If true, will return a mock GitDB connection\u003c/td\u003e\n    \u003ctd\u003ebool\u003c/td\u003e\n    \u003ctd\u003eN\u003c/td\u003e\n    \u003ctd\u003efalse\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nYou can configure GitDB either using the constructor or constructing it yourself\n\n```go\t\ncfg := gitdb.NewConfig(path)\n//or\ncfg := gitdb.Config{\n  DbPath: path\n}\n```\n\n\n\u003c!-- This will retrieve the library and install the `gitdb` command line utility into\nyour `$GOBIN` path. --\u003e\n\n### Importing GitDB\n\nTo use GitDB as an embedded document store, import as:\n\n```go\nimport \"github.com/gogitdb/gitdb/v2\"\n\ncfg := gitdb.NewConfig(path)\ndb, err := gitdb.Open(cfg)\nif err != nil {\n  log.Fatal(err)\n}\ndefer db.Close()\n```\n\n\n### Opening a database\n```go\npackage main\n\nimport (\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main() {\n  \n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  // Open will create or clone down a git repo \n  // in configured path if it does not exist.\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  ...\n}\n```\n\n### Models\n\nA Model is a struct that represents a record in GitDB. GitDB only works with models that implement the gidb.Model interface\n\ngitdb.TimeStampedModel is a simple struct that allows you to easily add CreatedAt and UpdatedAt to all the Models in your application and will automatically time stamp them before persisting to GitDB. You can write your own base Models to embed common fields across your application Models\n\n```go\ntype BankAccount struct {\n  //TimeStampedModel will add CreatedAt and UpdatedAt fields this Model\n  gitdb.TimeStampedModel \n  AccountType         string\n  AccountNo           string\n  Currency            string\n  Name                string\n}\n\nfunc (b *BankAccount) GetSchema() *gitdb.Schema {\n  //Dataset Name\n  name := \"Accounts\"\n  //Block ID\n  block := b.CreatedAt.Format(\"200601\")\n  //Record ID\n  record := b.AccountNo\n\n  //Indexes speed up searching\n  indexes := make(map[string]interface{})\n  indexes[\"AccountType\"] = b.AccountType\n \n  return gitdb.NewSchema(name, block, record, indexes)\n}\n\nfunc (b *BankAccount) Validate() error            { return nil }\nfunc (b *BankAccount) IsLockable() bool           { return false }\nfunc (b *BankAccount) ShouldEncrypt() bool        { return false }\nfunc (b *BankAccount) GetLockFileNames() []string { return []string{} }\n\n...\n  \n```\n\n### Inserting/Updating a record\n```go\npackage main\n\nimport (\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  //populate model\n  account := \u0026BankAccount{}\n  account.AccountNo = \"0123456789\"\n  account.AccountType = \"Savings\"\n  account.Currency = \"GBP\"\n  account.Name = \"Foo Bar\"\n\n  err = db.Insert(account)\n  if err != nil {\n    log.Println(err)\n  }\n\n  //get account id\n  log.Println(gitdb.Id(account))\n\n  //update account name\n  account.Name = \"Bar Foo\"\n  err = db.Insert(account)\n  if err != nil {\n    log.Println(err)\n  }\n}\n```\n\n### Fetching a single record\n```go\npackage main\nimport (\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  //model to passed to Get to store result \n  var account BankAccount\n  if err := db.Get(\"Accounts/202003/0123456789\", \u0026account); err != nil {\n    log.Println(err)\n  }\n}\n```\n### Fetching all records in a dataset\n```go\npackage main\n\nimport (\n  \"fmt\"\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  records, err := db.Fetch(\"Accounts\")\n  if err != nil {\n    log.Print(err)\n    return\n  }\n\n  accounts := []*BankAccount{}\n  for _, r := range records {\n    b := \u0026BankAccount{}\n    r.Hydrate(b)\n    accounts = append(accounts, b)\n    log.Print(fmt.Sprintf(\"%s-%s\", gitdb.ID(b), b.AccountNo))\n  }\n}\n\n```\n\n### Fetching all records from specific block in a dataset\n```go\npackage main\n\nimport (\n  \"fmt\"\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  records, err := db.Fetch(\"Accounts\", \"b0\", \"b1\")\n  if err != nil {\n    log.Print(err)\n    return\n  }\n\n  var accounts []*BankAccount\n  for _, r := range records {\n    b := \u0026BankAccount{}\n    r.Hydrate(b)\n    accounts = append(accounts, b)\n    log.Print(fmt.Sprintf(\"%s-%s\", gitdb.ID(b), b.AccountNo))\n  }\n}\n\n```\n\n### Deleting a record\n```go\npackage main\n\nimport (\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  if err := db.Delete(\"Accounts/202003/0123456789\"); err != nil {\n    log.Print(err)\n  }\n}\n```\n\n### Search for records\n```go\npackage main\n\nimport (\n  \"fmt\"\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  //Find all records that have savings account type\n  searchParam := \u0026db.SearchParam{Index: \"AccountType\", Value: \"Savings\"}\n  records, err := dbconn.Search(\"Accounts\", []*db.SearchParam{searchParam}, gitdb.SearchEquals)\n  if err != nil {\n    log.Println(err.Error())\n    return\n  } \n\n  accounts := []*BankAccount{}\n  for _, r := range records {\n    b := \u0026BankAccount{}\n    r.Hydrate(b)\n    accounts = append(accounts, b)\n    log.Print(fmt.Sprintf(\"%s-%s\", b.ID, b.CreatedAt))\n  }\n}\n```\n\n### Transactions\n```go\npackage main\n\nimport (\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main() {\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  func accountUpgradeFuncOne() error { println(\"accountUpgradeFuncOne...\"); return nil }\n  func accountUpgradeFuncTwo() error { println(\"accountUpgradeFuncTwo...\"); return errors.New(\"accountUpgradeFuncTwo failed\") }\n  func accountUpgradeFuncThree() error { println(\"accountUpgradeFuncThree\"); return nil }\n\n  tx := db.StartTransaction(\"AccountUpgrade\")\n  tx.AddOperation(accountUpgradeFuncOne)\n  tx.AddOperation(accountUpgradeFuncTwo)\n  tx.AddOperation(accountUpgradeFuncThree)\n  terr := tx.Commit()\n  if terr != nil {\n    log.Print(terr)\n  }\n}\n```\n\n### Encryption\n\nGitDB suppports AES encryption and is done on a Model level, which means you can have a database with different Models where some are encrypted and others are not. To encrypt your data, your Model must implement `ShouldEncrypt()` to return true and you must set `gitdb.Config.EncryptionKey`. For maximum security set this key to a 32 byte string to select AES-256 \n\n```go\npackage main\n\nimport (\n  \"log\"\n  \"github.com/gogitdb/gitdb/v2\"\n)\n\nfunc main(){\n  cfg := gitdb.NewConfig(\"/tmp/data\")\n  cfg.EncryptionKey = \"a_32_bytes_string_for_AES-256\"\n  db, err := gitdb.Open(cfg)\n  if err != nil {\n    log.Fatal(err)\n  }\n  defer db.Close()\n\n  //populate model\n  account := \u0026BankAccount{}\n  account.AccountNo = \"0123456789\"\n  account.AccountType = \"Savings\"\n  account.Currency = \"GBP\"\n  account.Name = \"Foo Bar\"\n\n  //Insert will encrypt the account\n  err = db.Insert(account)\n  if err != nil {\n    log.Println(err)\n  }\n\n  //Get will automatically decrypt account\n  var account BankAccount\n  err = db.Get(\"Accounts/202003/0123456789\", \u0026account)\n  if err != nil {\n    log.Println(err)\n  }\n}\n```\n\n## Resources\n\nFor more information on getting started with Gitdb, check out the following articles:\n* [Gtidb - an embedded distributed document database for Go](https://docs.google.com/document/d/1OPalq-7J_Vo_uks35up_4a_V0BsRrpwL1J4JG6ZFoEs/edit?usp=sharing) by Oke Ugwu\n\n\n## Caveats \u0026 Limitations\n\nIt's important to pick the right tool for the job and GitDB is no exception.\nHere are a few things to note when evaluating and using GitDB:\n\n* GitDB is good for systems where data producers are indpendent. \n* GitDB currently depends on the git binary to work \n\n## Reading the Source\n\nGitDB is a relatively small code base (\u003c5KLOC) for an embedded, distributed,\ndocument database so it can be a good starting point for people\ninterested in how databases work.\n\nThe best places to start are the main entry points into GitDB:\n\n- [`Open()`](https://github.com/gogitdb/gitdb/blob/a8088f138b072edd64021591e34adf878f2d0bd5/init.go#L17) - Initializes the reference to the database. It's responsible for\n  creating the database if it doesn't exist and pulling down existing database\n  if an online remote is specified.\n\nIf you have additional notes that could be helpful for others, please submit\nthem via pull request.\n\n\n\u003c!-- ## Other Projects Using GitDB\n\nBelow is a list of public, open source projects that use GitDB:\n\n* VogueHotel - Uses Gitdb as the default database backend.\n\n\nIf you are using GitDB in a project please send a pull request to add it to the list. --\u003e\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgogitdb%2Fgitdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgogitdb%2Fgitdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgogitdb%2Fgitdb/lists"}