|
| 1 | +# level-party |
| 2 | + |
| 3 | +Open a leveldb handle multiple times, transparently upgrading to use |
| 4 | +[`multileveldown`](https://npmjs.org/package/multileveldown) when more than 1 process try to use the same leveldb data directory at once and re-electing a new master when the primary unix socket goes down. |
| 5 | + |
| 6 | +[![level badge][level-badge]](https://github.com/Level/awesome) |
| 7 | +[](https://www.npmjs.com/package/level-party) |
| 8 | +[](https://www.npmjs.com/package/level-party) |
| 9 | +[](https://travis-ci.com/Level/party) |
| 10 | +[](https://coveralls.io/github/Level/party) |
| 11 | +[](https://standardjs.com) |
| 12 | +[](https://www.npmjs.com/package/level-party) |
| 13 | +[](#backers) |
| 14 | +[](#sponsors) |
| 15 | + |
| 16 | +## Example |
| 17 | + |
| 18 | +Normally with [`level`](https://npmjs.org/package/level), when you try to open |
| 19 | +a database handle from more than one process you will get a locking error: |
| 20 | + |
| 21 | +``` |
| 22 | +events.js:72 |
| 23 | + throw er; // Unhandled 'error' event |
| 24 | + ^ |
| 25 | +OpenError: IO error: lock /home/substack/projects/level-party/example/data/LOCK: Resource temporarily unavailable |
| 26 | + at /home/substack/projects/level-party/node_modules/level/node_modules/level-packager/node_modules/levelup/lib/levelup.js:114:34 |
| 27 | +``` |
| 28 | + |
| 29 | +With `level-party`, the database open will automatically drop down to using |
| 30 | +multilevel over a unix socket using metadata placed into the level data |
| 31 | +directory transparently. |
| 32 | + |
| 33 | +This means that if you have 2 programs, 1 that gets: |
| 34 | + |
| 35 | +```js |
| 36 | +var level = require('level-party'); |
| 37 | +var db = level(__dirname + '/data', { valueEncoding: 'json' }); |
| 38 | + |
| 39 | +setInterval(function () { |
| 40 | + db.get('a', function (err, value) { |
| 41 | + console.log('a=', value); |
| 42 | + }); |
| 43 | +}, 250); |
| 44 | +``` |
| 45 | + |
| 46 | +And 1 that puts: |
| 47 | + |
| 48 | +```js |
| 49 | +var level = require('level-party'); |
| 50 | +var db = level(__dirname + '/data', { valueEncoding: 'json' }); |
| 51 | + |
| 52 | +var n = Math.floor(Math.random() * 100000); |
| 53 | + |
| 54 | +setInterval(function () { |
| 55 | + db.put('a', n + 1); |
| 56 | +}, 1000); |
| 57 | +``` |
| 58 | + |
| 59 | +and you start them up in any order, everything will just work! No more |
| 60 | +`IO error: lock` exceptions. |
| 61 | + |
| 62 | +``` |
| 63 | +$ node put.js & sleep 0.2; node put.js & sleep 0.2; node put.js & sleep 0.2; node put.js & sleep 0.2 |
| 64 | +[1] 3498 |
| 65 | +[2] 3502 |
| 66 | +[3] 3509 |
| 67 | +[4] 3513 |
| 68 | +$ node get.js |
| 69 | +a= 35340 |
| 70 | +a= 31575 |
| 71 | +a= 37639 |
| 72 | +a= 58874 |
| 73 | +a= 35341 |
| 74 | +a= 31576 |
| 75 | +$ node get.js |
| 76 | +a= 35344 |
| 77 | +a= 31579 |
| 78 | +a= 37643 |
| 79 | +a= 58878 |
| 80 | +a= 35345 |
| 81 | +^C |
| 82 | +``` |
| 83 | + |
| 84 | +Hooray! |
| 85 | + |
| 86 | +## Seamless failover |
| 87 | + |
| 88 | +level-party does seamless failover. This means that if you create a read-stream |
| 89 | +and the leader goes down while you are reading that stream level-party will resume your stream on the new leader. |
| 90 | + |
| 91 | +[**This disables leveldb snapshotting**](https://github.com/level/leveldown#snapshots) so if your app relies on this you should disable this by setting `opts.retry = false` |
| 92 | + |
| 93 | +```js |
| 94 | +var db = level('./data', {retry: false}) // will not retry streams / gets / puts if the leader goes down |
| 95 | +``` |
| 96 | + |
| 97 | +## Windows support |
| 98 | + |
| 99 | +`level-party` works on windows as well using named pipes. |
| 100 | + |
| 101 | +## API |
| 102 | + |
| 103 | +### `var db = level(...)` |
| 104 | + |
| 105 | +The arguments are exactly the same as [`level`](https://npmjs.org/package/level). You will sometimes get a real leveldb handle and sometimes get a `multileveldown` handle back in the response. |
| 106 | + |
| 107 | +## Install |
| 108 | + |
| 109 | +With [npm](https://npmjs.org) do: |
| 110 | + |
| 111 | +``` |
| 112 | +npm install level-party |
| 113 | +``` |
| 114 | + |
| 115 | +## Contributing |
| 116 | + |
| 117 | +[`Level/party`](https://github.com/Level/party) is an **OPEN Open Source Project**. This means that: |
| 118 | + |
| 119 | +> Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project. |
| 120 | +
|
| 121 | +See the [Contribution Guide](https://github.com/Level/community/blob/master/CONTRIBUTING.md) for more details. |
| 122 | + |
| 123 | +## Donate |
| 124 | + |
| 125 | +To sustain [`Level`](https://github.com/Level) and its activities, become a backer or sponsor on [Open Collective](https://opencollective.com/level). Your logo or avatar will be displayed on our 28+ [GitHub repositories](https://github.com/Level) and [npm](https://www.npmjs.com/) packages. 💖 |
| 126 | + |
| 127 | +### Backers |
| 128 | + |
| 129 | +[](https://opencollective.com/level) |
| 130 | + |
| 131 | +### Sponsors |
| 132 | + |
| 133 | +[](https://opencollective.com/level) |
| 134 | + |
| 135 | +## License |
| 136 | + |
| 137 | +[MIT](LICENSE.md) © 2014-present James Halliday and [Contributors](CONTRIBUTORS.md). |
| 138 | + |
| 139 | +[level-badge]: https://leveljs.org/img/badge.svg |
0 commit comments