repodb

README

RepoDB

RepoDB is a simple file based database of git repositories. Metadata for files and repositories are provided as flat json files within.

This module is used to facilitate a local file storage database with "automatic" version control support. The design focused on low-traffic applications with increased file auditing and retention. Performance may suffer for high traffic applications, although that has not been investigated.

Installation

go get github.com/readpe/repodb

Usage Example

See example_test.go for full example.

General steps:

1. Create file record type(s) satisfying Record interface
2. Create Database using NewDB
3. Create Repository using CreateRepo
4. Write/Read/Delete files in Repository

License

Distributed under the MIT license. For more information, as well as third party licenses and notices, see LICENSE.

Acknowledgements

• go-git
• golang-scribble

Documentation

Overview

Example

package main

import (
	"bytes"
	"fmt"
	"io/ioutil"
	"log"
	"os"
	"strings"
	"time"

	"github.com/readpe/repodb"
)

// FileRecord is a simple file record, satisfying the Record interface
type FileRecord struct {
	Name        string    `json:"name"`
	SoftDeleted bool      `json:"softdeleted"`
	CreateOn    time.Time `json:"created_on"`
	UpdatedOn   time.Time `json:"updated_on"`
	DeletedOn   time.Time `json:"deleted_on"`
	body        string    // unexported so as not to add body to meta-data in addition to file
}

// FileName returns the file name for the record. Satisfies Record interface
func (fr *FileRecord) FileName() string {
	return fr.Name
}

// Folder returns the folder name for the record within the repository. Satisfies Record interface
func (fr *FileRecord) Folder() string {
	return "files"
}

func main() {
	// temp directory used for example
	dir, err := ioutil.TempDir(os.TempDir(), "repodb")
	if err != nil {
		log.Fatal(err)
	}

	// create database and repository
	db := repodb.NewDB(dir)

	// setup Repo details for CreateRepo
	repo := &repodb.Repo{
		Name:        "HelloRepo",
		DB:          db,
		Description: "A hello world repository.",
		Protected:   false,
		SoftDeleted: false,
		CreatedOn:   time.Now(),
		UpdatedOn:   time.Now(),
	}

	// create repository: adds a directory does git init, and writes meta-data for repo
	err = db.CreateRepo(repo)
	if err != nil {
		log.Fatal(err)
	}

	// creating example record
	fr := &FileRecord{
		Name:        "HelloWorld.txt",
		SoftDeleted: false,
		CreateOn:    time.Now(),
		UpdatedOn:   time.Now(),
		body:        "This is the body of the text file, an io.Reader could be used instead.",
	}

	// re-open repository for each write/read
	repo, err = db.OpenRepo("HelloRepo")
	if err != nil {
		log.Fatal(err)
	}

	// writes file to repository and commits all changes
	repo.WriteFile(fr, strings.NewReader(fr.body), repodb.CommitOptions{
		Msg: fmt.Sprintf("added file %s to %s", fr.FileName(), repo.Dir()),
	})
	repo.WriteMeta(fr, repodb.CommitOptions{
		Msg: fmt.Sprintf("added meta-data for file %s to %s", fr.FileName(), repo.Dir()),
	})

	// Read File
	buf := bytes.NewBufferString("")
	_, err = repo.ReadFile(fr, buf)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(buf)
}

Output:
This is the body of the text file, an io.Reader could be used instead.

Index

• Variables
• type CommitOptions
• type Record
• type Repo
  • func (repo *Repo) CommitAll(opts CommitOptions) error
  • func (repo *Repo) Dir() string
  • func (repo *Repo) FileExists(rec Record) bool
  • func (repo *Repo) FileName() string
  • func (repo *Repo) Folder() string
  • func (repo *Repo) LoadMeta(rec Record) error
  • func (repo *Repo) Protect() error
  • func (repo *Repo) ReadFile(rec Record, w io.Writer) (written int64, err error)
  • func (repo *Repo) RemoveFile(rec Record, opts CommitOptions) error
  • func (repo *Repo) RemoveMeta(rec Record, opts CommitOptions) error
  • func (repo *Repo) WriteFile(rec Record, r io.Reader, opts CommitOptions) error
  • func (repo *Repo) WriteMeta(rec Record, opts CommitOptions) error
• type RepoDB
  • func NewDB(dir string) *RepoDB
  • func (db *RepoDB) CreateRepo(repo *Repo) error
  • func (db *RepoDB) ListRepos() []*Repo
  • func (db *RepoDB) OpenRepo(name string) (*Repo, error)
  • func (db *RepoDB) RemoveRepo(dir string) error

Examples

• Package

Variables

var (
	MetaDir             = "meta-data"
	DBRepoName          = "db-repo" // the database repo name
	DBRepoCommitOptions = CommitOptions{
		Msg: DBRepoName,
		Opts: git.CommitOptions{
			Author:    &object.Signature{Name: "repodb", Email: ""},
			Committer: &object.Signature{Name: "repodb", Email: ""},
		},
	}
)

package variables

var (
	ErrRepoAlreadyExists = errors.New("repo already exists")
	ErrRepoNotExists     = errors.New("repo does not exist")
)

errors

Types

type CommitOptions

type CommitOptions struct {
	Msg  string
	Opts git.CommitOptions
}

CommitOptions is a wrapper struct arount git.CommitOptions with the addition of the message

type Record

type Record interface {
	FileName() string
	Folder() string
}

Record is a RepoDB record interface.

type Repo

type Repo struct {
	sync.RWMutex
	Name        string
	DB          *RepoDB `json:"-"`
	Description string
	Protected   bool
	SoftDeleted bool
	CreatedOn   time.Time
	UpdatedOn   time.Time
	DeletedOn   time.Time
}

Repo is a git repository as a subdirectory under the RepoDB

func (*Repo) CommitAll

func (repo *Repo) CommitAll(opts CommitOptions) error

CommitAll does a git add . && git commit -m "msg"

func (*Repo) Dir

func (repo *Repo) Dir() string

Dir is the full directory for the Repo under the DB

func (*Repo) FileExists

func (repo *Repo) FileExists(rec Record) bool

FileExists checks if file exists

func (*Repo) FileName

func (repo *Repo) FileName() string

FileName returns the repo , which is its dir implements Record interface

func (*Repo) Folder

func (repo *Repo) Folder() string

Folder is the record folder, final path component under the Repo. Implements Record interface

func (*Repo) LoadMeta

func (repo *Repo) LoadMeta(rec Record) error

LoadMeta data for record to Record concrete type

func (*Repo) Protect

func (repo *Repo) Protect() error

Protect the repo from deletion

func (*Repo) ReadFile

func (repo *Repo) ReadFile(rec Record, w io.Writer) (written int64, err error)

ReadFile will read the file to the provided io.Writer

func (*Repo) RemoveFile

func (repo *Repo) RemoveFile(rec Record, opts CommitOptions) error

RemoveFile removes the record. If there is an error it will be of type *os.PathError. This function will not remove the coresponding meta-data file, use in conjunction with RemoveMeta.

func (*Repo) RemoveMeta

func (repo *Repo) RemoveMeta(rec Record, opts CommitOptions) error

RemoveMeta removes the records meta-data file. If there is an error it will be of type *os.PathError. This function will not remove the referenced record file, use in conjunction with RemoveFIle.

func (*Repo) WriteFile

func (repo *Repo) WriteFile(rec Record, r io.Reader, opts CommitOptions) error

WriteFile will create and write the record to file. If the directory does not exist, it will be created.

func (*Repo) WriteMeta

func (repo *Repo) WriteMeta(rec Record, opts CommitOptions) error

WriteMeta data for record to json file db.

type RepoDB

type RepoDB struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

RepoDB is a file based database of git repositories.

func NewDB

func NewDB(dir string) *RepoDB

NewDB returns a new RepoDB in the named directory

func (*RepoDB) CreateRepo

func (db *RepoDB) CreateRepo(repo *Repo) error

CreateRepo will create a git repository as a subdirectory dir in the RepoDB. Will return ErrRepoAlreadyExists if it already exists

func (*RepoDB) ListRepos

func (db *RepoDB) ListRepos() []*Repo

ListRepos returns a list of repositories in the database

func (*RepoDB) OpenRepo

func (db *RepoDB) OpenRepo(name string) (*Repo, error)

OpenRepo will open the git repository at the specified directory Will return ErrRepoNotExists if no valid repository is found

func (*RepoDB) RemoveRepo

func (db *RepoDB) RemoveRepo(dir string) error

RemoveRepo will remove the current database and all files/sub-directories. Use with caution.