rocksdb-ruby 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e63a830799d975bd61b019413c022b2dd2c2b996
-  data.tar.gz: 4629fb74bd9ff28fdcc4654656410b729033d3e0
+  metadata.gz: ff03f629257fdb8ac8848e41458d5d1eb585f815
+  data.tar.gz: acec6cb4441abdd687337be38eec30be8c74fb49
 SHA512:
-  metadata.gz: 8cd31b6afd9fc8c84638b1e37325a753e1f2a4bde49e48697f993bcf65b71c6c480b89fde2ee303a3ec1ec9b52339081508809aef6be0a31ede97cf8747191da
-  data.tar.gz: 4dec517e5bcc0d8c6b82c1c5a02c43643a9e0bd8e4fa1174d62730ed6c91e950e395957249e6adeb0b4bdb451faffe300b997c8ffe70a6b99c6f5c2337918cbc
+  metadata.gz: 7688c4b6bcbe355a87e23a4a28923ac9d6fac529330be380b3c7fbebec5b9b6517ae311bc52e7cc6dc85eb2f6954c5014e1c530b8e11b1729ea12561c1751a2a
+  data.tar.gz: fc91395d2ddee8543e1dcd438658ab147c21f9414855ece7649ef12ad87dc552cc5f2d46f3ef25653e701bdf420636712da4efb1131ce8b9ddc97e57d4f9a0c3

data/.gitignore

@@ -15,3 +15,7 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+ext/**/*.o
+ext/**/Makefile
+ext/**/*.log
+ext/**/*.bundle

data/.travis.yml

@@ -1,22 +1,60 @@
 language: ruby
+script: bundle exec rake spec
+
 rvm:
-  - 2.4.0
-script: bundle exec rake spec || ( cat ext/rocksdb/mkmf.log && /bin/false )
+  - 2.4
+  - 2.5
+  - 2.6
+
+os:
+  - linux
+  - osx
+
+# We can use this matrix to pick supported versions
+# https://repology.org/project/rocksdb/versions
+jobs:
+  include:
+    - os: linux
+      env: ROCKSDB_VERSION=6.3.6
+    - os: linux
+      env: ROCKSDB_VERSION=5.17.2
+    - os: linux
+      env: ROCKSDB_VERSION=4.5.1
+    - os: osx
+      env: ROCKSDB_VERSION=5.18.3 ROCKSDB_VERSION_COMMIT=d38e4b445ea1525fba69b1d7b88dc63e9faaa21b
+    - os: osx
+      env: ROCKSDB_VERSION=6.1.2 ROCKSDB_VERSION_COMMIT=6e35266c1f6b7bab9ed4371e5cf9f1cfca0566b7
+
+cache:
+  ccache: true
+  bundler: true
+  directories:
+    - /home/travis/.ccache
+
+addons:
+  apt:
+    sources:
+      - sourceline: 'ppa:ubuntu-toolchain-r/test'
+    packages:
+      - gdb
+      - gcc-8
+      - g++-8
+      - libbz2-dev
+      - zlib1g-dev
+      - libgflags-dev
+      - libsnappy-dev
+
+before_script:
+  # enable core dumps
+  - ulimit -c unlimited -S
 
 before_install:
-  - sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
-  - sudo apt-get update -qq
-  - sudo apt-get install gcc-6 g++-6 libsnappy-dev zlib1g-dev libbz2-dev -qq
-  - export CXX="g++-6" CC="gcc-6"
-  - sudo ln -s /usr/bin/gcc-6 /usr/local/bin/gcc
-  - sudo ln -s /usr/bin/g++-6 /usr/local/bin/g++
   - gem install bundler
 
 install:
-  - git clone https://github.com/facebook/rocksdb.git /tmp/rocksdb
-  - pushd /tmp/rocksdb
-  - make clean
-  - make shared_lib
-  - popd
-  - export ROCKSDB_RUBY_BUILD_PARAMS="--with-rocksdb-dir=/tmp/rocksdb --with-rocksdb-lib=/tmp/rocksdb"
-  - bundle install
+  - export ROCKSDB_FOLDER=/tmp/rocksdb/
+  - export ROCKSDB_RUBY_BUILD_PARAMS="--with-rocksdb-dir=$ROCKSDB_FOLDER --with-rocksdb-lib=$ROCKSDB_FOLDER"
+  - ./.travis/install.sh
+
+after_failure:
+ - ./.travis/after_failure.sh

data/.travis/after_failure.sh

@@ -0,0 +1,16 @@
+echo "---- mmkf.log ----"
+cat ext/rocksdb/mkmf.log
+echo "---- makefile ----"
+cat ext/rocksdb/Makefile
+
+if [ $TRAVIS_OS_NAME = 'linux' ]; then
+  # Show core dump contents and build configuration if any
+ COREFILE=$(find . -maxdepth 1 -name "core*" | head -n 1)
+ CORE_PROG=$(which ruby)
+ echo "---- gdb $CORE_PROG -c "$COREFILE" ----"
+ if [[ -f "$COREFILE" ]]; then
+   gdb $CORE_PROG -c "$COREFILE" -ex "thread apply all bt full" -ex "set pagination 0" -batch
+fi
+else
+  echo "Can't inspect coredump on ${TRAVIS_OS_NAME}"
+fi

data/.travis/install.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Fail if anything fails
+set -e
+
+if [[ $TRAVIS_OS_NAME == 'osx' ]]; then
+  # BUG: https://discourse.brew.sh/t/octave-require-relative-problem/6043
+  # BUG: https://travis-ci.community/t/homebrew-syntax-error/5623
+  export HOMEBREW_NO_AUTO_UPDATE=1
+
+  if [[ -z "${ROCKSDB_VERSION}" ]]; then
+    echo "Brewing latest available version"
+    brew install "rocksdb"
+  else
+    BREW_CORE_URI="https://raw.githubusercontent.com/Homebrew/homebrew-core"
+    FORMULA_URI="${BREW_CORE_URI}/${ROCKSDB_VERSION_COMMIT}/Formula/rocksdb.rb"
+    echo "Installing ${ROCKSDB_VERSION} from ${ROCKSDB_VERSION_COMMIT}"
+    brew install "${FORMULA_URI}"
+    brew switch rocksdb "${ROCKSDB_VERSION}"
+  fi
+
+  echo "Building bundle"
+  bundle install
+elif [[ $TRAVIS_OS_NAME == 'linux' ]]; then
+  export PATH="/usr/lib/ccache/:$PATH"
+
+  if [[ -z "${ROCKSDB_VERSION}" ]]; then
+    echo "Building from rocksdb master in ${ROCKSDB_FOLDER}"
+    git clone -b "master" --single-branch --depth 1 https://github.com/facebook/rocksdb.git $ROCKSDB_FOLDER
+  else
+    echo "Building ${ROCKSDB_VERSION} in ${ROCKSDB_FOLDER}"
+    git clone -b "v$ROCKSDB_VERSION" --single-branch --depth 1 https://github.com/facebook/rocksdb.git $ROCKSDB_FOLDER
+  fi
+
+  pushd $ROCKSDB_FOLDER
+  ccache -s
+
+  if [[ $DEBUG_LEVEL == '1' ]]; then
+    echo "Building with DEBUG_LEVEL=1"
+    # TODO: I think it's better to try to satisfy all the rocksdb checks
+    make -j4 shared_lib DEBUG_LEVEL=1
+  else
+    make -j4 shared_lib
+  fi
+
+  ccache -s
+  popd
+
+  echo "Building bundle with params:"
+  echo "${ROCKSDB_RUBY_BUILD_PARAMS}"
+  bundle install
+else
+  echo "Unsupported OS ${TRAVIS_OS_NAME}"
+  exit 1
+fi

data/README.md

@@ -11,7 +11,7 @@ This gem contains Ruby bindings so that you can use it from your Ruby process.
 
 ## Installation
 
-First install rocksdb.
+First, install rocksdb: https://github.com/facebook/rocksdb/blob/master/INSTALL.md
 
 Add this line to your application's Gemfile:
 
@@ -31,49 +31,410 @@ Or install it yourself as:
 $ gem install rocksdb-ruby
 ```
 
+`rocksdb-ruby` is tested against Ruby 2.4, 2.5 and 2.6 on Linux and macOS platforms. However, it might work on other platforms.
+
+`rocksdb-ruby` supports rocksb 4.5.1 and later. It is tested against master branch with all supported ruby version. It is also tested against few specific version, available in popular distributions. Check `.travis.yml` for details.
+
+JRuby, TruffleRuby and Rubinius are not supported at the moment.
+
 ## Usage
 
+
+### Open database
+
+First, you need to open database. Use `open` method and pass path to database
+root as first argument. By default, it will create path if missing.
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file1"
+```
+
+You can pass RocksDB options as second argument:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file2", compression: "kNoCompression"
+```
+
+Or you can pass raw Option String:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file2", "compression=kNoCompression"
+```
+
+Read more about Option Sting: https://github.com/facebook/rocksdb/wiki/Option-String-and-Option-Map#option-string
+
+### Basic reads and writes
+
+You can read and write keys using `put` and `get` methods:
+
 ```ruby
-require "rocksdb"
 
-# Reads And Writes
-key = "test"
-value = "1"
-rocksdb = RocksDB::DB.new "/tmp/file"
-rocksdb.put(key, value)
-new_value = rocksdb.get(key)
-rocksdb.delete(key)
+    require "rocksdb"
 
-# Atomic Updates
-batch = RocksDB::Batch.new
-batch.delete("test:batch1")
-batch.put("test:batch2", "b")
-rocksdb.write(batch)
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file3"
 
-# Iteration
-iterator = rocksdb.new_iterator
+    # Store string `World` under key `Hello`
+    rocksdb.put "Hello", "World"
 
-iterator.seek_to_first
-while(iterator.valid)
-  iterator.value
-  iterator.key
-  iterator.next
-end
-iterator.close
+    # Read a value stored under key `Hello`
+    puts rocksdb.get "Hello"
+    # => World
+```
 
-# Block
-rocksdb.each do |data|
-  puts data
-end
+You can also use Hash-like methods `[]` and `[]=`
 
-# Hash access
-rocksdb['key'] = data
-puts rocksdb['key']
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file4"
 
+    # Store string `World` under key `Hello`
+    rocksdb["Hello"] = "World"
 
-rocksdb.close
+    # Read a value stored under key `Hello`
+    puts rocksdb["Hello"]
+    # => World
 ```
 
+If key does not exists, RocksDB will return nil:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file5"
+
+    # Try to read a key, that does not exists
+    result = rocksdb.get "Missing Key"
+
+    if !result
+      puts "Key not found!"
+    end
+
+    # => Key not found
+```
+
+If you want to get multiple keys at the same time, you can use `get` with multiple arguments:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file6"
+
+    rocksdb.put "First Key", "First Value"
+    rocksdb.put "Second Key", "Second Value"
+    rocksdb.put "Third Key", "Third Value"
+
+    # If key does not exists, you'll get nil
+    values = rocksdb.get "Second Key", "Imaginary Key", "Third Key"
+
+    puts values
+    # => ["Second Value", nil, "Third Value"]
+```
+
+You can check, if key exists:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file7"
+
+    rocksdb.put "Real Key", "Real Value"
+
+    rocksdb.exists? "Real Key"
+    # => true
+
+    rocksdb.exists? "Imaginary Key"
+    # => false
+```
+
+And you can delete keys, when not needed:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file8"
+
+    rocksdb.put "Delete Me", "Memory"
+    rocksdb.exists? "Delete Me"
+    # => true
+    rocksdb.delete "Delete Me"
+    rocksdb.exists? "Delete Me"
+    # => false
+
+    rocksdb.get "Delete Me"
+    # => nil
+```
+
+You can open RocksDB only for reading:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open only for reading
+    rocksdb = RocksDB.open_readonly "/tmp/file9"
+
+    puts rocksdb.writable?
+    # => false
+
+    rocksdb.put "First Key", "First Value"
+
+    # => RocksDB::ReadOnly (database is read-only)
+```
+
+
+### Enumerable
+
+You can enumerate over all values using `each` method. Note how values are sorted lexicographically by their keys:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file10"
+
+    rocksdb.put "One", "1"
+    rocksdb.put "Two", "2"
+    rocksdb.put "Three", "3"
+
+    rocksdb.each do |value|
+      puts value
+    end
+
+    # => 1
+    # => 3
+    # => 2
+```
+
+Additionally, you can enumerate in reverse order with `reverse_each`:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file11"
+
+    rocksdb.put "One", "1"
+    rocksdb.put "Two", "2"
+    rocksdb.put "Three", "3"
+
+    rocksdb.reverse_each do |value|
+      puts value
+    end
+
+    # => 2
+    # => 3
+    # => 1
+```
+
+You can enumerate over keys with `each_key` or in reverse order with `reverse_each_key`:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file12"
+
+    rocksdb.put "One", "1"
+    rocksdb.put "Two", "2"
+    rocksdb.put "Three", "3"
+
+    rocksdb.each_key do |key|
+      puts key
+    end
+
+    # => One
+    # => Three
+    # => Two
+
+    rocksdb.reverse_each_key do |key|
+      puts key
+    end
+
+    # => Two
+    # => Three
+    # => One
+```
+
+You can enumerate over both keys and values with `each_pair` and in reverse order with `reverse_each_pair`:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file13"
+
+    rocksdb.put "One", "1"
+    rocksdb.put "Two", "2"
+    rocksdb.put "Three", "3"
+
+    rocksdb.each_pair do |key, value|
+      puts "#{key} = #{value}"
+    end
+
+    # => One = 1
+    # => Three = 3
+    # => Two = 2
+```
+
+Additionally, you can enumerate over keys that start with a specific prefix with `each_prefix`:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file14"
+
+    rocksdb.put "my:1", "1"
+    rocksdb.put "my:2", "2"
+    rocksdb.put "your:3", "3"
+
+    rocksdb.each_prefix("my") do |key, value|
+      puts "#{key} = #{value}"
+    end
+
+    # => my:1 = 1
+    # => my:2 = 2
+```
+
+Or you can scan over the ranges of keys with `each_range`. Note, range is `[start, limit]`:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file15"
+
+    10.times do |count|
+      rocksdb.put "key:#{count}", "#{count}"
+    end
+
+    rocksdb.each_range("key:5", "key:7") do |key, value|
+      puts "#{key} = #{value}"
+    end
+
+    # => key:5 = 5
+    # => key:6 = 6
+    # => key:7 = 7
+```
+
+### Atomic Batches
+
+You can use `RocksDB::Batch` to atomically insert big chunks of data.
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file16"
+
+    batch = RocksDB::Batch.new
+
+    batch.delete("test:batch1")
+    batch.put("test:batch2", "b")
+
+    rocksdb.write(batch)
+
+    rocksdb.each_pair do |key, value|
+      puts "#{key} = #{value}"
+    end
+
+    # => test:batch2 = b
+```
+
+Read more about RocksDB batches: https://github.com/facebook/rocksdb/wiki/Basic-Operations#atomic-updates
+
+# Iterator
+
+You can get RocksDB Iterator with `to_iterator` method to iterate over your data:
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file16"
+
+    10.times do |count|
+      rocksdb.put "key:#{count}", "#{count}"
+    end
+
+    # Get Iterator
+    iterator = rocksdb.to_iterator
+    # Seek to some position. You can also use seek("key") to
+    iterator.seek_to_first
+
+    while iterator.valid?
+      puts "#{iterator.value} = #{iterator.key}"
+      iterator.next
+    end
+
+    iterator.close
+```
+
+Supported methods:
+
+* `seek(key)` seeks to closest key to given prefix at beginning
+* `seek_to_first` seeks to the first key
+* `seek_to_last` seeks to the last key
+* `next` seeks to the next key
+* `previous` seeks to the previous key
+* `valid?` returns true if iterator can be iterated
+* `close` closes iterator
+* `key` returns current key
+* `value` returns current value
+
+Methods supported by rocksdb 4.11 and later:
+
+* `seek_for_previous(key)`seeks to closest key to given prefix at end
+
+## Upgrade
+
+When upgrading from `0.2` version, please note the following breaking changes:
+
+* `multi_get` will return `nil` instead of empty string
+* `RocksDB::DB.get_instance` is removed. Implement your own DB instance cache if needed
+* `each_` methods now returns `Enumerator` instead of `RocksDB::Iterator`
+
+Also, there some things that are now deprecated and will be removed in future versions:
+
+* `RocksDB::DBError` was deprecated and replaced with `RocksDB::Error`. Specific errors now have their own exception class: `ReadOnly`, `DatabaseClosed`, `IteratorClosed`, `StatusError`
+* `is_open?` was replaced with `open?`
+* `is_readonly?` was replaced with `writable?`
+* `multi_get` was replaced with `get_many`
+* `new_iterator` was replaced with `to_iterator`
+* `Iterator#valid` was replaced with `Iterator#valid?`
+
 ## Contributing
 
 1. Fork it