rocksdb-ruby 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 02a4d4a14d208c82b4350ad74137d5dc61787981
-  data.tar.gz: 11cb366cd0278dc76275ff163f450e8e18564a6d
+SHA256:
+  metadata.gz: 3a31d0881ac039ce8fc05c6aa47b34984fef049367e797027dc4de381b618bcc
+  data.tar.gz: 713b878614320830014a92f0390ddf42f6a40803cb746f9d8b56bed32a14bdea
 SHA512:
-  metadata.gz: 67921bce1b5f49bee1861089067ee59a9380913356e20455b8135dfe498c2799c5c9b88802221709aa09522442504c1a4e2c2a13d25e806af18c98184f552a0c
-  data.tar.gz: 0cdcbd2d5aa177d1c85db02ac03fe2f83562a9510357228ee36ce699fe527d1e6e4243aaa5d311a09b63c3775bcab19e6c71094c4cd1aacbfe5a36fca70c0ffc
+  metadata.gz: 3acd74eef6bfa29bb6c972225ec8d5cfa4ab9617e3cf0663c152e0c4b472bbb70bee993cd19b65ec058568857df5d39538d3799996293d6b6055c8a63e9ffd0d
+  data.tar.gz: d9ca30a13ae84da30d347951e4951eb98896e38eb61211ed93cf733fd5f301d7500ad4c2167207085a636a4251561fa972e88174549d545e7210315a9f7dc1f1

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,62 @@
 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
+  - 2.7
+  - 3.0
+
+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,61 +11,429 @@ 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:
 
-    gem 'rocksdb-ruby'
+```ruby
+gem 'rocksdb-ruby'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install rocksdb-ruby
+```sh
+$ 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"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file3"
+
+    # Store string `World` under key `Hello`
+    rocksdb.put "Hello", "World"
+
+    # Read a value stored under key `Hello`
+    puts rocksdb.get "Hello"
+    # => World
+```
+
+You can also use Hash-like methods `[]` and `[]=`
+
+```ruby
+
+    require "rocksdb"
+
+    # Open for reads and writes
+    rocksdb = RocksDB.open "/tmp/file4"
+
+    # Store string `World` under key `Hello`
+    rocksdb["Hello"] = "World"
+
+    # 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"
 
-    # 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)
+    # 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"
 
-    #Atomic Updates
     batch = RocksDB::Batch.new
+
     batch.delete("test:batch1")
     batch.put("test:batch2", "b")
+
     rocksdb.write(batch)
 
-    #Iteration
-    iterator = rocksdb.new_iterator
+    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)
-      iterator.value
-      iterator.key
+
+    while iterator.valid?
+      puts "#{iterator.value} = #{iterator.key}"
       iterator.next
     end
+
     iterator.close
+```
 
-    #Block
-    rocksdb.each do |data|
-      puts data
-    end
+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:
 
-    #Hash access
-    rocksdb['key'] = data
-    puts rocksdb['key']
+* `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`
 
-    
-    rocksdb.close
+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