# ssdb

> ssdb nodejs client library, ssdb is a fast nosql database, an alternative to redis.

Latest version **0.3.8** (published 2015-10-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install ssdb
pnpm add ssdb
yarn add ssdb
bun add ssdb
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.8 |
| Published | 2015-10-26 |
| First published | 2014-08-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.10.30 |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | hit9 |
| Maintainers | hit9, eleme |
| Keywords | ssdb, client |

## Links

- npm: https://www.npmjs.com/package/ssdb
- Repository: https://github.com/eleme/node-ssdb
- Homepage: https://github.com/eleme/node-ssdb#readme
- Issues: https://github.com/eleme/node-ssdb/issues
- npm.io page: https://npm.io/package/ssdb

## Dependencies (2)

- [promisify.js](https://npm.io/package/promisify.js.md) ~0.0.1
- [create-error.js](https://npm.io/package/create-error.js.md) ~0.0.5

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.3.8 (latest) — 2015-10-26
- 0.3.7 — 2015-10-26
- 0.3.6 — 2015-10-16
- 0.3.5 — 2015-09-14
- 0.3.4 — 2015-08-24
- 0.3.3 — 2015-07-16
- 0.3.2 — 2015-05-05
- 0.3.1 — 2015-04-23
- 0.3.0 — 2015-04-21
- 0.2.2 — 2015-04-14
- 0.2.1 — 2015-04-08
- 0.2.0 — 2015-03-16
- 0.1.9 — 2015-03-04
- 0.1.8 — 2015-02-07
- 0.1.7 — 2015-01-01
- … 15 more at https://npm.io/package/ssdb/versions

## README

node-ssdb
=========

![](https://nodei.co/npm/ssdb.png)

[ssdb](https://github.com/ideawu/ssdb) nodejs/iojs client library,
ssdb is a fast nosql database, an alternative to redis.

**v0.3.0 (and higher versions) are not backward-compactiable with old versions(0.2.x)**.

![](https://api.travis-ci.org/eleme/node-ssdb.svg)

Please dont send me emails for any questions about node-ssdb, open an issue on GitHub instead, thanks!

Ports
------

- Python port: https://github.com/hit9/ssdb.py
- Lua ngx client: https://github.com/eleme/lua-resty-ssdb


Supported Engines
-----------------

- node.js >= v0.10.30
- iojs >= 1.0.4

Requirements
-------------

- ssdb 1.6.8.8+

Installation
-------------

```bash
$ npm install ssdb
```

Example
--------

The traditional Node.js way:

```js
var ssdb = require('ssdb');
var pool = ssdb.createPool();
var conn = pool.acquire();

conn.set('key', 'val', function(err, data) {
  if (err) {
    throw err;
  }
  // data => '1'
});
```

Work with [tj/co](https://github.com/tj/co), make it thunkify or promisify:

```js
var co = require('co');

var pool = ssdb.createPool({promisify: true});
var conn = pool.acquire();

co(function *(){
  var key = 'key';
  var a = yield conn.set(key, 'val');
  var b = yield conn.get(key);
  console.log(a, b);  // 1 'val'
}).catch(function(err) {
  console.error(err)
});
```

*node-ssdb uses v8 native Promise to implement `promisify`, which requires nodejs v0.11.13+*

To use [bluebird](https://github.com/petkaantonov/bluebird) as promise implementation (which
is much faster than v8 native promise):

```js
// use bluebird promise
global.Promise = require('bluebird').Promise;
```

Callback Parameters
-------------------

Callback functions have two parameters: `error, data`;

- on `status_ok`:  only `error` is `undefined`;
- on `status_not_found`: `error` and `data` are both `undefined`
- on `status_error`, `status_fail`, `status_client_error`: only `data` is `undefined`.

Error Handling
--------------

```javascript
var ssdb = require('ssdb');
var pool = ssdb.createPool();

pool.acquire().set('key', 'val', function(err, data) {
  if (err && err instanceof ssdb.SSDBError)
    throw err;  // ssdb error
});
```

Poolling Policies
-----------------

There are 2 poolling policies avaliable: 'least_conn' and 'round_robin' (the default), e.g.

```ssdb
var pool = ssdb.createPool({policy: ssdb.Pool.policies.least_conn});
```

API References
--------------

### createPool(options)

To make a ssdb client:

```js
var ssdb = require('ssdb');
var pool = ssdb.createPool();
```

options (with default values):

```js
{
  host: '0.0.0.0',
  port: 8888,
  auth: undefined,  // ssdb server auth password
  authCallback: function(err, data) {if (err) throw err;},  // callback function on auth
  size: 1,  // connection pool size
  timeout: 0,
  promisify: false,  // make api methods promisify.
  thunkify: false,  // make api methods thunkify.
  policy: Pool.policies.round_robin,
}
```

*Note: `auth` requires ssdb v1.7.0.0+*

### pool.acquire()

Acquire a connection from pool.

### pool.destroy()

Close all connections in the pool. (*note that if a connection is closed, it will reconnect to ssdb
server automatically if you reuse this conn to send commands, and the same with pool.*)

### pool.create(options)

Create a new connection and add it to the pool.

### command names

```js
ssdb.commands
```

SSDB API Documentation
----------------------

Detail docs for ssdb interfaces can be found at: https://github.com/hit9/ssdb.api.docs


FAQ
---

1. Pipeline?

   Node-ssdb pipelines automatically because node.js has async IO, this is different with other
   clients in sync IO languages (i.e. Python), node-ssdb always pipelines.

2. Commands & Callbacks ordering ?

   On a single connection, the callbacks are run the same order as the commands are sent, TCP guarantees
   this: the stream will arrive in the same order as it was sent.

3. Connection Pool?

   ssdb is a multiple-threading server, so the connection pool is required. Here are some examples
   to use the connection pool:

   ```js
   // async io and executed in order on the remote end.
   var conn = pool.acquire();
   yield conn.set('key', 'val');
   yield conn.get('key');
   // async io and executed parallely on the remote end.
   yield [
     pool.acquire().set('key1', 'val1');
     pool.acquire().set('key2', 'val2');
   ];
   ```

License
-------

Copyright (c) 2014 Eleme, Inc. detail see [LICENSE-MIT](./LICENSE-MIT)

---
_Source: https://npm.io/package/ssdb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._