boltdb/bolt — pull request #74 by benbjohnson (2014-03-22 05:17:07+00:00)
Title: CLI

## Overview

This pull request adds a `bolt` command line utility:

```
NAME:
bolt - BoltDB toolkit

USAGE:
bolt [global options] command [command options] [arguments...]

VERSION:
0.0.0

COMMANDS:
get	Retrieve a value for given key in a bucket
set	Sets a value for given key in a bucket
keys	Retrieve a list of all keys in a bucket
buckets	Retrieves a list of all buckets
pages	Dumps page information for a database
help, h	Shows a list of commands or help for one command

GLOBAL OPTIONS:
--version, -v	print the version
--help, -h	show help
```

## Install

To install the CLI:

```
$ go get github.com/boltdb/bolt/...
```

## Usage

Set some values on keys in the `widgets` bucket:

```
$ bolt set ~/mydb widgets foo bar
$ bolt set ~/mydb widgets bat baz
$ bolt set ~/mydb widgets abc 123
```

Read back the `foo` key from the `widgets` bucket:

```
$ bolt get ~/mydb widgets foo
bar
```

Retrieve a list of all keys on the `widgets` bucket:

```
$ bolt keys ~/mydb widgets
abc
bat
foo
```

Retrieve a list of all buckets in the database.

```
$ bolt buckets ~/mydb
widgets
```

Dump a listing of all pages in the database along with their type and the number of elements they have in them. It also shows the number of overflow pages being used, if any.

```
$ bolt pages ~/mydb
ID TYPE ITEMS OVRFLW
======== ========== ====== ======
0 meta 0
1 meta 0
2 freelist 0
3 buckets 0
4 leaf 0
...
```

## Caveats

This initial CLI is pretty barebones. It's mainly to help me debug without opening up a hex editor.

Warning: Bolt databases are not safe to share across multiple processes! You're probably ok to use it to get values or list keys. For read-only operations the worst case scenario is that your CLI process crashes. Don't use it to set values. You'll probably corrupt your database. If you need to edit your database (for some reason), shut down your process, make changes, and restart your process. Or run a `DB.Copy()` and make changes on the copy.