Merge pull request #74 from benbjohnson/cli

CLI

5 files changed, 504 insertions, 0 deletions

diff --git a/cmd/bolt/main.go b/cmd/bolt/main.go
new file mode 100644
index 0000000..647c1c2
--- /dev/null
+++ b/cmd/bolt/main.go
@@ -0,0 +1,294 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"os"
+	"strconv"
+
+	"github.com/boltdb/bolt"
+	"github.com/codegangsta/cli"
+)
+
+func main() {
+	log.SetFlags(0)
+	NewApp().Run(os.Args)
+}
+
+// NewApp creates an Application instance.
+func NewApp() *cli.App {
+	app := cli.NewApp()
+	app.Name = "bolt"
+	app.Usage = "BoltDB toolkit"
+	app.Commands = []cli.Command{
+		{
+			Name:   "get",
+			Usage:  "Retrieve a value for given key in a bucket",
+			Action: GetCommand,
+		},
+		{
+			Name:   "set",
+			Usage:  "Sets a value for given key in a bucket",
+			Action: SetCommand,
+		},
+		{
+			Name:   "keys",
+			Usage:  "Retrieve a list of all keys in a bucket",
+			Action: KeysCommand,
+		},
+		{
+			Name:   "buckets",
+			Usage:  "Retrieves a list of all buckets",
+			Action: BucketsCommand,
+		},
+		{
+			Name:   "pages",
+			Usage:  "Dumps page information for a database",
+			Action: PagesCommand,
+		},
+	}
+	return app
+}
+
+// GetCommand retrieves the value for a given bucket/key.
+func GetCommand(c *cli.Context) {
+	path, name, key := c.Args().Get(0), c.Args().Get(1), c.Args().Get(2)
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		fatal(err)
+		return
+	}
+
+	db, err := bolt.Open(path, 0600)
+	if err != nil {
+		fatal(err)
+		return
+	}
+	defer db.Close()
+
+	err = db.With(func(tx *bolt.Tx) error {
+		// Find bucket.
+		b := tx.Bucket(name)
+		if b == nil {
+			fatalf("bucket not found: %s", name)
+			return nil
+		}
+
+		// Find value for a given key.
+		value := b.Get([]byte(key))
+		if value == nil {
+			fatalf("key not found: %s", key)
+			return nil
+		}
+
+		println(string(value))
+		return nil
+	})
+	if err != nil {
+		fatal(err)
+		return
+	}
+}
+
+// SetCommand sets the value for a given key in a bucket.
+func SetCommand(c *cli.Context) {
+	path, name, key, value := c.Args().Get(0), c.Args().Get(1), c.Args().Get(2), c.Args().Get(3)
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		fatal(err)
+		return
+	}
+
+	db, err := bolt.Open(path, 0600)
+	if err != nil {
+		fatal(err)
+		return
+	}
+	defer db.Close()
+
+	err = db.Do(func(tx *bolt.Tx) error {
+		// Find bucket.
+		b := tx.Bucket(name)
+		if b == nil {
+			fatalf("bucket not found: %s", name)
+			return nil
+		}
+
+		// Set value for a given key.
+		return b.Put([]byte(key), []byte(value))
+	})
+	if err != nil {
+		fatal(err)
+		return
+	}
+}
+
+// KeysCommand retrieves a list of keys for a given bucket.
+func KeysCommand(c *cli.Context) {
+	path, name := c.Args().Get(0), c.Args().Get(1)
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		fatal(err)
+		return
+	}
+
+	db, err := bolt.Open(path, 0600)
+	if err != nil {
+		fatal(err)
+		return
+	}
+	defer db.Close()
+
+	err = db.With(func(tx *bolt.Tx) error {
+		// Find bucket.
+		b := tx.Bucket(name)
+		if b == nil {
+			fatalf("bucket not found: %s", name)
+			return nil
+		}
+
+		// Iterate over each key.
+		return b.ForEach(func(key, _ []byte) error {
+			println(string(key))
+			return nil
+		})
+	})
+	if err != nil {
+		fatal(err)
+		return
+	}
+}
+
+// BucketsCommand retrieves a list of all buckets.
+func BucketsCommand(c *cli.Context) {
+	path := c.Args().Get(0)
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		fatal(err)
+		return
+	}
+
+	db, err := bolt.Open(path, 0600)
+	if err != nil {
+		fatal(err)
+		return
+	}
+	defer db.Close()
+
+	err = db.With(func(tx *bolt.Tx) error {
+		for _, b := range tx.Buckets() {
+			println(b.Name())
+		}
+		return nil
+	})
+	if err != nil {
+		fatal(err)
+		return
+	}
+}
+
+// PagesCommand prints a list of all pages in a database.
+func PagesCommand(c *cli.Context) {
+	path := c.Args().Get(0)
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		fatal(err)
+		return
+	}
+
+	db, err := bolt.Open(path, 0600)
+	if err != nil {
+		fatal(err)
+		return
+	}
+	defer db.Close()
+
+	println("ID       TYPE       ITEMS  OVRFLW")
+	println("======== ========== ====== ======")
+
+	db.Do(func(tx *bolt.Tx) error {
+		var id int
+		for {
+			p, err := tx.Page(id)
+			if err != nil {
+				fatalf("page error: %d: %s", id, err)
+			} else if p == nil {
+				break
+			}
+
+			var overflow string
+			if p.OverflowCount > 0 {
+				overflow = strconv.Itoa(p.OverflowCount)
+			}
+			printf("%-8d %-10s %-6d %-6s\n", p.ID, p.Type, p.Count, overflow)
+			id += 1 + p.OverflowCount
+		}
+		return nil
+	})
+}
+
+var logger = log.New(os.Stderr, "", 0)
+var logBuffer *bytes.Buffer
+
+func print(v ...interface{}) {
+	if testMode {
+		logger.Print(v...)
+	} else {
+		fmt.Print(v...)
+	}
+}
+
+func printf(format string, v ...interface{}) {
+	if testMode {
+		logger.Printf(format, v...)
+	} else {
+		fmt.Printf(format, v...)
+	}
+}
+
+func println(v ...interface{}) {
+	if testMode {
+		logger.Println(v...)
+	} else {
+		fmt.Println(v...)
+	}
+}
+
+func fatal(v ...interface{}) {
+	logger.Print(v...)
+	if !testMode {
+		os.Exit(1)
+	}
+}
+
+func fatalf(format string, v ...interface{}) {
+	logger.Printf(format, v...)
+	if !testMode {
+		os.Exit(1)
+	}
+}
+
+func fatalln(v ...interface{}) {
+	logger.Println(v...)
+	if !testMode {
+		os.Exit(1)
+	}
+}
+
+// LogBuffer returns the contents of the log.
+// This only works while the CLI is in test mode.
+func LogBuffer() string {
+	if logBuffer != nil {
+		return logBuffer.String()
+	}
+	return ""
+}
+
+var testMode bool
+
+// SetTestMode sets whether the CLI is running in test mode and resets the logger.
+func SetTestMode(value bool) {
+	testMode = value
+	if testMode {
+		logBuffer = bytes.NewBuffer(nil)
+		logger = log.New(logBuffer, "", 0)
+	} else {
+		logger = log.New(os.Stderr, "", 0)
+	}
+}
diff --git a/cmd/bolt/main_test.go b/cmd/bolt/main_test.go
new file mode 100644
index 0000000..b755ccd
--- /dev/null
+++ b/cmd/bolt/main_test.go
@@ -0,0 +1,158 @@
+package main_test
+
+import (
+	"io/ioutil"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/boltdb/bolt"
+	. "github.com/boltdb/bolt/cmd/bolt"
+	"github.com/stretchr/testify/assert"
+)
+
+// Ensure that a value can be retrieved from the CLI.
+func TestGet(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		db.Do(func(tx *bolt.Tx) error {
+			tx.CreateBucket("widgets")
+			tx.Bucket("widgets").Put([]byte("foo"), []byte("bar"))
+			return nil
+		})
+		output := run("get", db.Path(), "widgets", "foo")
+		assert.Equal(t, "bar", output)
+	})
+}
+
+// Ensure that an error is reported if the database is not found.
+func TestGetDBNotFound(t *testing.T) {
+	SetTestMode(true)
+	output := run("get", "no/such/db", "widgets", "foo")
+	assert.Equal(t, "stat no/such/db: no such file or directory", output)
+}
+
+// Ensure that an error is reported if the bucket is not found.
+func TestGetBucketNotFound(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		output := run("get", db.Path(), "widgets", "foo")
+		assert.Equal(t, "bucket not found: widgets", output)
+	})
+}
+
+// Ensure that an error is reported if the key is not found.
+func TestGetKeyNotFound(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		db.Do(func(tx *bolt.Tx) error {
+			return tx.CreateBucket("widgets")
+		})
+		output := run("get", db.Path(), "widgets", "foo")
+		assert.Equal(t, "key not found: foo", output)
+	})
+}
+
+// Ensure that a value can be set from the CLI.
+func TestSet(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		db.Do(func(tx *bolt.Tx) error {
+			tx.CreateBucket("widgets")
+			return nil
+		})
+		assert.Equal(t, "", run("set", db.Path(), "widgets", "foo", "bar"))
+		assert.Equal(t, "bar", run("get", db.Path(), "widgets", "foo"))
+	})
+}
+
+// Ensure that an error is reported if the database is not found.
+func TestSetDBNotFound(t *testing.T) {
+	SetTestMode(true)
+	output := run("set", "no/such/db", "widgets", "foo", "bar")
+	assert.Equal(t, "stat no/such/db: no such file or directory", output)
+}
+
+// Ensure that an error is reported if the bucket is not found.
+func TestSetBucketNotFound(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		output := run("set", db.Path(), "widgets", "foo", "bar")
+		assert.Equal(t, "bucket not found: widgets", output)
+	})
+}
+
+// Ensure that a list of keys can be retrieved for a given bucket.
+func TestKeys(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		db.Do(func(tx *bolt.Tx) error {
+			tx.CreateBucket("widgets")
+			tx.Bucket("widgets").Put([]byte("0002"), []byte(""))
+			tx.Bucket("widgets").Put([]byte("0001"), []byte(""))
+			tx.Bucket("widgets").Put([]byte("0003"), []byte(""))
+			return nil
+		})
+		output := run("keys", db.Path(), "widgets")
+		assert.Equal(t, "0001\n0002\n0003", output)
+	})
+}
+
+// Ensure that an error is reported if the database is not found.
+func TestKeysDBNotFound(t *testing.T) {
+	SetTestMode(true)
+	output := run("keys", "no/such/db", "widgets")
+	assert.Equal(t, "stat no/such/db: no such file or directory", output)
+}
+
+// Ensure that an error is reported if the bucket is not found.
+func TestKeysBucketNotFound(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		output := run("keys", db.Path(), "widgets")
+		assert.Equal(t, "bucket not found: widgets", output)
+	})
+}
+
+// Ensure that a list of buckets can be retrieved.
+func TestBuckets(t *testing.T) {
+	SetTestMode(true)
+	open(func(db *bolt.DB) {
+		db.Do(func(tx *bolt.Tx) error {
+			tx.CreateBucket("woojits")
+			tx.CreateBucket("widgets")
+			tx.CreateBucket("whatchits")
+			return nil
+		})
+		output := run("buckets", db.Path())
+		assert.Equal(t, "whatchits\nwidgets\nwoojits", output)
+	})
+}
+
+// Ensure that an error is reported if the database is not found.
+func TestBucketsDBNotFound(t *testing.T) {
+	SetTestMode(true)
+	output := run("buckets", "no/such/db")
+	assert.Equal(t, "stat no/such/db: no such file or directory", output)
+}
+
+// open creates and opens a Bolt database in the temp directory.
+func open(fn func(*bolt.DB)) {
+	f, _ := ioutil.TempFile("", "bolt-")
+	f.Close()
+	os.Remove(f.Name())
+	defer os.RemoveAll(f.Name())
+
+	db, err := bolt.Open(f.Name(), 0600)
+	if err != nil {
+		panic("db open error: " + err.Error())
+	}
+	fn(db)
+}
+
+// run executes a command against the CLI and returns the output.
+func run(args ...string) string {
+	args = append([]string{"bolt"}, args...)
+	NewApp().Run(args)
+	return strings.TrimSpace(LogBuffer())
+}
diff --git a/freelist.go b/freelist.go
index 636ed22..d0b1492 100644
--- a/freelist.go
+++ b/freelist.go
@@ -70,6 +70,23 @@ func (f *freelist) release(txid txid) {
 	sort.Sort(reverseSortedPgids(f.ids))
 }
 
+// isFree returns whether a given page is in the free list.
+func (f *freelist) isFree(pgid pgid) bool {
+	for _, id := range f.ids {
+		if id == pgid {
+			return true
+		}
+	}
+	for _, m := range f.pending {
+		for _, id := range m {
+			if id == pgid {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 // read initializes the freelist from a freelist page.
 func (f *freelist) read(p *page) {
 	ids := ((*[maxAllocSize]pgid)(unsafe.Pointer(&p.ptr)))[0:p.count]
diff --git a/page.go b/page.go
index 5b60c4d..0d46f09 100644
--- a/page.go
+++ b/page.go
@@ -119,3 +119,11 @@ func (n *leafPageElement) value() []byte {
 	buf := (*[maxAllocSize]byte)(unsafe.Pointer(n))
 	return buf[n.pos+n.ksize : n.pos+n.ksize+n.vsize]
 }
+
+// PageInfo represents human readable information about a page.
+type PageInfo struct {
+	ID            int
+	Type          string
+	Count         int
+	OverflowCount int
+}
diff --git a/tx.go b/tx.go
index ae6d103..5b2b14d 100644
--- a/tx.go
+++ b/tx.go
@@ -420,3 +420,30 @@ func (t *Tx) forEachPage(pgid pgid, depth int, fn func(*page, int)) {
 		}
 	}
 }
+
+// Page returns page information for a given page number.
+// This is only available from writable transactions.
+func (t *Tx) Page(id int) (*PageInfo, error) {
+	if !t.writable {
+		return nil, ErrTxNotWritable
+	} else if pgid(id) >= t.meta.pgid {
+		return nil, nil
+	}
+
+	// Build the page info.
+	p := t.page(pgid(id))
+	info := &PageInfo{
+		ID:            id,
+		Count:         int(p.count),
+		OverflowCount: int(p.overflow),
+	}
+
+	// Determine the type (or if it's free).
+	if t.db.freelist.isFree(pgid(id)) {
+		info.Type = "free"
+	} else {
+		info.Type = p.typ()
+	}
+
+	return info, nil
+}