Skip to content

Latest commit

 

History

History
114 lines (71 loc) · 5.02 KB

UPGRADING.md

File metadata and controls

114 lines (71 loc) · 5.02 KB
Raw

Upgrade Guide

This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the changelog.

6.0.0

Legacy range options have been removed (Level/community#86). If you previously did:

db.createReadStream({ start: 'a', end: 'z' })

An error would now be thrown and you must instead do:

db.createReadStream({ gte: 'a', lte: 'z' })

The same applies to db.iterator(), db.createKeyStream() and db.createValueStream().

This release also drops support of legacy runtime environments (Level/community#98):

  • Node.js 6 and 8
  • Internet Explorer 11
  • Safari 9-11
  • Stock Android browser (AOSP).

Some private properties have been replaced with Symbols (1f9d550). Lastly, in browsers, process.nextTick() has been replaced with queue-microtask, except in streams.

5.0.0

Fixes iterating buffer keys that contain bytes 196-255 (#88)

Previously (in any version) keys containing bytes 196-255 were wrongly excluded by the range logic of subleveldown. The fix is not breaking for most folks.

It's breaking if you:

  • Use the default separator and prefixes that contain " (byte 34)
  • Use a custom separator that doesn't sort 2 positions before characters used in your prefixes. For example with separator / (byte 47) prefixes must use characters greater than 0 (byte 48).

In either case, an error will be thrown from the constructor.

Parent database must support deferredOpen (#89)

By parent we mean:

var parent = require('level')('db')
var sublevel = require('subleveldown')(parent, 'a')

By deferredOpen we mean that the db opens itself and defers operations until it's open. Currently that's only supported by levelup (and levelup factories like level). Previously, subleveldown would also accept abstract-leveldown db's that were not wrapped in levelup.

Better isolation

Opening and closing a sublevel no longer opens or closes the parent db. The sublevel does wait for the parent to open (which in the case of levelup already happens automatically) but never initiates a state change on the parent.

If one closes the parent but not the sublevel, subsequent operations on the sublevel (like get and put) will yield an error, to prevent segmentation faults from underlying stores.

Drops support of old modules

Rejects new sublevels on a closing or closed database

db.close(function (err) {
  subdb(db, 'example').on('error', function (err) {
    throw err // Error: Parent database is not open
  })
})
subdb(db, 'example').on('error', function (err) {
  throw err // Error: Parent database is not open
})

db.close(function () {})

4.0.0

Upgraded to abstract-leveldown@6, encoding-down@6 and levelup@4. We recommend to pair subleveldown@4 with level >= 5 or when using a custom store, one that is based on abstract-leveldown >= 6. For details please see:

A quick summary: range options are now serialized the same as keys, db.iterator({ gt: undefined }) is not the same as db.iterator({}), nullish values are now rejected and streams are backed by readable-stream@3.

3.0.0

Dropped support for node 4.

The following methods were removed due to upgrading to abstract-leveldown@^5.0.0:

  • SubDown#approximateSize
  • SubDown#getProperty

If your code relies on these methods they only make sense if the underlying store is something that supports them, e.g. leveldown or rocksdb. If this is true you should invoke these methods on the underlying store instead.

The following methods were removed for two reasons; a) they should not be instance methods and b) they are related to leveldown specifics rather than abstract-leveldown:

  • SubDown#destroy
  • SubDown#repair

The following method was removed due to upgrading to levelup@^3.0.1:

  • SubDown#setDb

Related to internals and should not affect you.