boltup

README

boltup

Boltup is a simple one way migration tool for boltdb inspired by the simplicity of https://github.com/BurntSushi/migration. It performs a series on migrations on a bolt database as one transaction. If a migration fails, the transaction is rolled back and nothing is changed. Once a migration has been applied, it is perminant and should never be modified. Internally, boltup creates a migrations bucket with a version field to keep track of the amount of migrations applied.

Usage

A migration updates the database by one version. As all migrations are ran in one transaction, a migration shouldn't be able to commit any changes early. Therefore a LimitedTx is used which wraps the regular bolt transaction but does not allow commit or rollback functionality.

type Migration func(tx *LimitedTx) error

Up takes in a bolt db instance and runs all of the supplied migrations in order. If any migration fails an error is returned and everything is rolled back.

func Up(db *bolt.DB, migrations ...Migration) error

Example

Adding a new field with a default value

package main

import (
    "encoding/json"
    "log"

    "github.com/GeorgeNewby/boltup"
    "github.com/boltdb/bolt"
)

type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Group string `json:"group"` // new field
}

func main() {
    db, err := bolt.Open("users.db", 0600, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    err = boltup.Up(db, createUserBucket, addGroupField)
    if err != nil {
        log.Fatal(err)
    }
}

func createUserBucket(tx *boltup.LimitedTx) error {
    _, err := tx.CreateBucket([]byte("users"))
    return err
}

func addGroupField(tx *boltup.LimitedTx) error {
    b := tx.Bucket([]byte("users"))

    b.ForEach(func(k, v []byte) error {
        var user User
        if err := json.Unmarshal(v, &user); err != nil {
            return err
        }

        user.Group = "A"

        data, err := json.Marshal(user)
        if err != nil {
            return err
        }

        if err := b.Put(k, data); err != nil {
            return err
        }
        return nil
    })
    return nil
}

Documentation

Index

• func Up(db *bolt.DB, migrations ...Migration) error
• type LimitedTx
  • func (l *LimitedTx) Bucket(name []byte) *bolt.Bucket
  • func (l *LimitedTx) CreateBucket(name []byte) (*bolt.Bucket, error)
  • func (l *LimitedTx) CreateBucketIfNotExists(name []byte) (*bolt.Bucket, error)
  • func (l *LimitedTx) Cursor() *bolt.Cursor
  • func (l *LimitedTx) DeleteBucket(name []byte) error
  • func (l *LimitedTx) ForEach(fn func(name []byte, b *bolt.Bucket) error) error
• type Migration

Functions

func Up

func Up(db *bolt.DB, migrations ...Migration) error

Up excutes all the migrations as one transaction, if a migration fails the transaction is rolled back

Types

type LimitedTx

type LimitedTx struct {
	// contains filtered or unexported fields
}

LimitedTx wraps the standard bolt tx but does not allow commit or rollback behavior

func (*LimitedTx) Bucket

func (l *LimitedTx) Bucket(name []byte) *bolt.Bucket

Bucket retrieves a bucket by name

func (*LimitedTx) CreateBucket

func (l *LimitedTx) CreateBucket(name []byte) (*bolt.Bucket, error)

CreateBucket creates a new bucket

func (*LimitedTx) CreateBucketIfNotExists

func (l *LimitedTx) CreateBucketIfNotExists(name []byte) (*bolt.Bucket, error)

CreateBucketIfNotExists creates a new bucket if it doesn't already exist

func (*LimitedTx) Cursor

func (l *LimitedTx) Cursor() *bolt.Cursor

Cursor creates a cursor associated with the root bucket

func (*LimitedTx) DeleteBucket

func (l *LimitedTx) DeleteBucket(name []byte) error

DeleteBucket deletes a bucket

func (*LimitedTx) ForEach

func (l *LimitedTx) ForEach(fn func(name []byte, b *bolt.Bucket) error) error

ForEach executes a function for each bucket in the root

type Migration

type Migration func(tx *LimitedTx) error

Migration represents a single bolt migration to updates the db by one version