2019-03-09 12:41:59 +00:00
# bitcask
[](https://cloud.drone.io/prologic/bitcask)
[](https://codecov.io/gh/prologic/bitcask)
[](https://goreportcard.com/report/prologic/bitcask)
2019-09-03 22:20:44 +00:00
[](https://codebeat.co/projects/github-com-prologic-bitcask-master)
2019-03-09 12:41:59 +00:00
[](https://godoc.org/github.com/prologic/bitcask)
2019-04-23 20:44:21 +00:00
[](https://github.com/prologic/bitcask)
2019-08-30 03:28:17 +00:00
[](https://sourcegraph.com/github.com/prologic/bitcask?badge)
2019-04-23 20:44:21 +00:00
2019-08-03 09:47:23 +00:00
A high performance Key/Value store written in [Go ](https://golang.org ) with a predictable read/write performance and high throughput. Uses a [Bitcask ](https://en.wikipedia.org/wiki/Bitcask ) on-disk layout (LSM+WAL) similar to [Riak ](https://riak.com/ )
2019-03-09 12:41:59 +00:00
2019-03-29 12:21:39 +00:00
For a more feature-complete Redis-compatible server, distributed key/value store have a look at [Bitraft ](https://github.com/prologic/bitraft ) which uses this library as its backend. Use [Bitcask ](https://github.com/prologic/bitcask ) as a starting point or if you want to embed in your application, use [Bitraft ](https://github.com/prologic/bitraft ) if you need a complete server/client solution with high availability with a Redis-compatible API.
2019-03-09 12:41:59 +00:00
## Features
2019-03-20 22:36:17 +00:00
* Embeddable (`import "github.com/prologic/bitcask"`)
* Builtin CLI (`bitcask`)
* Builtin Redis-compatible server (`bitcaskd`)
2019-03-13 10:27:27 +00:00
* Predictable read/write performance
2019-08-01 03:48:36 +00:00
* Low latency
2019-04-23 20:44:21 +00:00
* High throughput (See: [Performance ](README.md#Performance ) )
2019-03-09 12:41:59 +00:00
2019-04-01 07:27:56 +00:00
## Development
2019-08-03 09:49:15 +00:00
```#!sh
2019-04-01 07:27:56 +00:00
$ git clone https://github.com/prologic/bitcask.git
$ make
```
2019-03-09 12:41:59 +00:00
## Install
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-09 12:41:59 +00:00
$ go get github.com/prologic/bitcask
```
## Usage (library)
Install the package into your project:
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-09 12:41:59 +00:00
$ go get github.com/prologic/bitcask
```
```#!go
package main
2019-03-20 22:36:17 +00:00
import "github.com/prologic/bitcask"
2019-03-09 12:41:59 +00:00
func main() {
db, _ := bitcask.Open("/tmp/db")
2019-03-20 22:36:17 +00:00
defer db.Close()
2019-06-03 10:48:30 +00:00
db.Put("Hello", []byte("World"))
2019-06-11 21:29:11 +00:00
val, _ := db.Get("Hello")
2019-03-09 12:41:59 +00:00
}
```
See the [godoc ](https://godoc.org/github.com/prologic/bitcask ) for further
documentation and other examples.
## Usage (tool)
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-09 12:41:59 +00:00
$ bitcask -p /tmp/db set Hello World
$ bitcask -p /tmp/db get Hello
World
```
2019-03-13 11:40:43 +00:00
## Usage (server)
There is also a builtin very simple Redis-compatible server called `bitcaskd` :
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-13 11:40:43 +00:00
$ ./bitcaskd ./tmp
INFO[0000] starting bitcaskd v0.0.7@146f777 bind=":6379" path=./tmp
```
Example session:
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-13 11:40:43 +00:00
$ telnet localhost 6379
Trying ::1...
Connected to localhost.
Escape character is '^]'.
SET foo bar
+OK
GET foo
$3
bar
DEL foo
:1
GET foo
$-1
PING
+PONG
QUIT
+OK
Connection closed by foreign host.
```
2019-03-30 10:25:23 +00:00
## Docker
You can also use the [Bitcask Docker Image ](https://cloud.docker.com/u/prologic/repository/docker/prologic/bitcask ):
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-30 10:25:23 +00:00
$ docker pull prologic/bitcask
$ docker run -d -p 6379:6379 prologic/bitcask
```
2019-03-09 12:41:59 +00:00
## Performance
Benchmarks run on a 11" Macbook with a 1.4Ghz Intel Core i7:
2019-08-03 09:49:15 +00:00
```#!sh
2019-03-09 12:41:59 +00:00
$ make bench
...
2019-08-05 22:15:03 +00:00
goos: darwin
goarch: amd64
pkg: github.com/prologic/bitcask
BenchmarkGet/128B-4 300000 3913 ns/op 32.71 MB/s 387 B/op 4 allocs/op
BenchmarkGet/128BWithPool-4 300000 4143 ns/op 30.89 MB/s 227 B/op 3 allocs/op
BenchmarkGet/256B-4 300000 3919 ns/op 65.31 MB/s 643 B/op 4 allocs/op
BenchmarkGet/256BWithPool-4 300000 4270 ns/op 59.95 MB/s 355 B/op 3 allocs/op
BenchmarkGet/512B-4 300000 4248 ns/op 120.52 MB/s 1187 B/op 4 allocs/op
BenchmarkGet/512BWithPool-4 300000 4676 ns/op 109.48 MB/s 611 B/op 3 allocs/op
BenchmarkGet/1K-4 200000 5248 ns/op 195.10 MB/s 2275 B/op 4 allocs/op
BenchmarkGet/1KWithPool-4 200000 5270 ns/op 194.28 MB/s 1123 B/op 3 allocs/op
BenchmarkGet/2K-4 200000 6229 ns/op 328.74 MB/s 4451 B/op 4 allocs/op
BenchmarkGet/2KWithPool-4 200000 6282 ns/op 325.99 MB/s 2147 B/op 3 allocs/op
BenchmarkGet/4K-4 200000 9027 ns/op 453.74 MB/s 9059 B/op 4 allocs/op
BenchmarkGet/4KWithPool-4 200000 8906 ns/op 459.87 MB/s 4195 B/op 3 allocs/op
BenchmarkGet/8K-4 100000 12024 ns/op 681.28 MB/s 17763 B/op 4 allocs/op
BenchmarkGet/8KWithPool-4 200000 11103 ns/op 737.79 MB/s 8291 B/op 3 allocs/op
BenchmarkGet/16K-4 100000 16844 ns/op 972.65 MB/s 34915 B/op 4 allocs/op
BenchmarkGet/16KWithPool-4 100000 14575 ns/op 1124.10 MB/s 16483 B/op 3 allocs/op
BenchmarkGet/32K-4 50000 27770 ns/op 1179.97 MB/s 73827 B/op 4 allocs/op
BenchmarkGet/32KWithPool-4 100000 24495 ns/op 1337.74 MB/s 32867 B/op 3 allocs/op
BenchmarkPut/128B-4 100000 17492 ns/op 7.32 MB/s 441 B/op 6 allocs/op
BenchmarkPut/256B-4 100000 17234 ns/op 14.85 MB/s 571 B/op 6 allocs/op
BenchmarkPut/512B-4 100000 22837 ns/op 22.42 MB/s 861 B/op 6 allocs/op
BenchmarkPut/1K-4 50000 30333 ns/op 33.76 MB/s 1443 B/op 6 allocs/op
BenchmarkPut/2K-4 30000 45304 ns/op 45.21 MB/s 2606 B/op 6 allocs/op
BenchmarkPut/4K-4 20000 83953 ns/op 48.79 MB/s 5187 B/op 6 allocs/op
BenchmarkPut/8K-4 10000 142142 ns/op 57.63 MB/s 9845 B/op 6 allocs/op
BenchmarkPut/16K-4 5000 206722 ns/op 79.26 MB/s 18884 B/op 6 allocs/op
BenchmarkPut/32K-4 5000 361108 ns/op 90.74 MB/s 41582 B/op 7 allocs/op
BenchmarkScan-4 1000000 1679 ns/op 408 B/op 16 allocs/op
PASS
2019-03-09 12:41:59 +00:00
```
2019-03-14 08:17:20 +00:00
For 128B values:
2019-08-05 22:15:03 +00:00
* ~200,000 reads/sec
* ~50,000 writes/sec
2019-03-14 08:17:20 +00:00
2019-08-05 22:15:03 +00:00
The full benchmark above shows linear performance as you increase key/value sizes. Memory pooling starts to become advantageous for larger values.
2019-03-09 12:41:59 +00:00
2019-08-25 22:45:15 +00:00
## Stargazers over time
2019-08-29 22:05:08 +00:00
[](https://starcharts.herokuapp.com/prologic/bitcask)
2019-08-25 22:45:15 +00:00
## Support
Support the ongoing development of Bitcask!
**Sponser**
- Become a [Sponser ](https://www.patreon.com/prologic )
2019-08-07 03:24:38 +00:00
## Contributors
2019-09-02 00:22:08 +00:00
Thank you to all those that have contributed to this project, battle-tested it, used it in their own projects or products, fixed bugs, improved performance and even fix tiny typos in documentation! Thank you and keep contributing!
2019-08-07 03:24:38 +00:00
You can find an [AUTHORS ](/AUTHORS ) file where we keep a list of contributors to the project. If you contriibute a PR please consider adding your name there. There is also Github's own [Contributors ](https://github.com/prologic/bitcask/graphs/contributors ) statistics.
2019-03-09 12:41:59 +00:00
## License
2019-08-07 03:24:38 +00:00
bitcask is licensed under the term of the [MIT License ](https://github.com/prologic/bitcask/blob/master/LICENSE )
