Adding ssdb addon to application will provide you with access to SSDBHub - highly available ssdb cluster, configured and ready for use. The cluster can be accessed directly with SSDB or Redis client.

SSDBHub supports users libraries in many languages. including Java, Python, Node.js, Ruby, PHP, and Go.

Provisioning the add-on

ssdb plugin can be attached to a Heroku application via the CLI:

$ heroku addons:create ssdb
-----> Adding ssdb to sharp-mountain-4005... done, v18 (free)

Once ssdb is added to your app, the following variables will be added to environment configuration:

SSDB_HOST
SSDB_PORT
SSDB_URL
SSDB_PASSWORD

These should be used to access the newly provisioned SSDB instance. Configuration variables can be confirmed using the heroku config:get command.

$ heroku config:get SSDB_HOST
172.217.18.14

$ heroku config:get SSDB_PORT
32612

$ heroku config:get SSDB_URL
http://172.217.18.14:32612

$ heroku config:get SSDB_PASSWORD
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoZWxsbyI6InRlc3QifQ..

After installing ssdb the application should be configured to fully integrate with the add-on. Please note that SSDB_URL is only the combination of SSDB_HOST and SSDB_PORT. Some clients will require both of them separate, others will use full url as a connection string.

Local setup

Environment setup

After provisioning the add-on it's necessary to locally replicate the config vars so your development environment operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app's Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app's config vars, type heroku config. Use the following command for each value you want to add to your .env file.

$ heroku config:get SSDB_HOST -s  >> .env
$ heroku config:get SSDB_PORT -s  >> .env
$ heroku config:get SSDB_PASSWORD -s  >> .env
$ heroku config:get SSDB_URL -s >> .env

For more information, see Heroku Local article.

Using SSDB with Different Languages

As already mentioned above SSDB has many client libraries in different programming languages. Below are couple of examples on how you can apply them.

Using with Java

Available clients

Package	Author	Repository	Description
official ★	ideawu	Repository	This is the official client
ssdb4j	nutzam	Repository	Yet another SSDB client for Java
another ssdb4j	jbakwd	Repository
hydrogen-ssdb	yiding-he	Repository	Supports client-side load-balance

The following example uses official Java client, which needs to be imported within the application.

import com.udpwork.ssdb.*;

Then the client library should be created using environment variables, which were discussed previously.

String host = System.getenv("SSDB_HOST");
String port = System.getenv("SSDB_PORT");
SSDB ssdb = new SSDB(host, Integer.parseInt(port));

String pass = System.getenv("SSDB_PASSWORD");
Response resp = ssdb.request("auth", pass);
if(!resp.ok()){
	resp.exception();
}

Now when client is authenticated it's ready to be used

ssdb.set("mykey", "myvalue");
byte[] val = ssdb.get("myvalue");

Using with Python

Available clients

Package	Author	Repository	Description
built-in ★	ideawu	Repository	This is the official client
pyssdb	ifduyue	Repository	A SSDB Client Library for Python
ssdb-py	wrongwaycn	Repository	SSDB Python Client like Redis-Py
ssdb.py	hit9	Repository	SSDB Python Client Library by hit9

For this example the ssdb-py client is use. Before using the package it should be installed as follows:

$ pip install ssdb

Application needs to import the library

import ssdb

When it's done, the client should be created using environment variables.

import os

host = os.env["SSDB_HOST"]
port = os.env["SSDB_PORT"]
ssdb = ssdb.SSDB(host, port)

pass = os.env["SSDB_PASSWORD"];
resp = ssdb.execute_command("auth", pass);
if resp[0] != "ok":
    raise Exception("Invalid Password")

Now when client is authenticated it's ready to be used

ssdb.set("mykey", "myvalue");
res = ssdb.get("mykey");

Using with Node

Available clients

Package	Author	Repository	Description
official ★	ideawu	Repository	This is the official client
node-ssdb by @hit9	hit9	Repository	node-ssdb by @hit9

For this example the node-ssdb library is use. Before using the package it should be installed

$ npm install ssdb

Application will need to import the library

var ssdb = require('ssdb');

Then the connection pool should be created using environment variables.

var host = process.env.SSDB_HOST
var port = process.env.SSDB_PORT
var pass = process.env.SSDB_PASSWORD

var pool = ssdb.createPool({
  host: host,
  port: port,
  auth: pass
  });

Now when connection pool is created it's ready to be used.

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

Using with Go

Available clients

Package	Author	Repository	Description
official ★	ideawu	Repository	This is the official client
hissdb	Eryx	Repository	hissdb in lessos/lessgo, supports connection pool.
gossdb	seefan	Repository	From the official client derived from the client, supports the connection pool and set, get, habits and most client consistent.

For this example the hissdb library is use. Application will need to import the library

package main

import (
    "fmt"
    "github.com/lessos/lessgo/data/hissdb"
)

Then the connection should be created using environment variables.

import os
import strconv

func main() {
    host := os.Getenv("SSDB_HOST")
    port := os.Getenv("SSDB_PORT")
    auth := os.Getenv("SSDB_PASSWORD")
    conn, err := hissdb.NewConnector(hissdb.Config{
        Host:    host,
        Port:    strconv.ParseInt(port),
        Auth:    auth,
        Timeout: 3,  // timeout in second, default to 10
        MaxConn: 10, // max connection number, default to 1
    })
    if err != nil {
        fmt.Println("Connect Error:", err)
        return
    }
    defer conn.Close()

Now when connection is created it's ready to be used.

    conn.Cmd("set", "mykey", "myvalue")
    if rs := conn.Cmd("get", "mykey"); rs.State == "ok" {
        fmt.Println("get OK\n\t", rs.String())
    }
 }

Using with Ruby

Available clients

Package	Author	Repository	Description
ssdb-rb	bsm	Repository	Ruby client library for SSDB

Application will need to import the library

gem install ssdb

Then create the connection using environment variables.

require "ssdb"
ssdb = SSDB.new url: ENV['SSDB_URL']

ssdb.perform("auth", ENV['SSDB_PASSWORD'])

Now when connection is created it's ready to be used.

ssdb.set("mykey", "myvalue")
# => true

ssdb.get("mykey")
# => "myvalue"

Using with PHP

Available clients

Package	Author	Repository	Description
built-in ★	ideawu	Repository	This is the official client

Application will need to import the library

include(dirname(__FILE__) . '/SSDB.php');

Then create the connection using environment variables

$host = getenv('SSDB_HOST');
$port = getenv('SSDB_PORT');

try{
	$ssdb = new SimpleSSDB($host, $port);
}catch(Exception $e){
	die(__LINE__ . ' ' . $e->getMessage());
}

ssdb.perform("auth", ENV['SSDB_PASSWORD'])

Now when connection is created it's ready to be used.

$ssdb->set("mykey", "myvalue")
# => true

echo $ssdb->get("mykey")
# => "myvalue"

Using with Redis Clients

Even though SSDB has its own original client libraries for different programming languages, it also supports Redis protocol, which makes possible to communicate with SSDB database using Redis clients.

Below is the list of supported Redis commands and how they map to SSDB.

Key-Value

Redis	SSDB
get	get
set	set
setex	setx(for kv type only)
del	del
incr/incrBy	incr
decr/decrBy	decr
mget/getMultiple	multi_get
setMultiple	multi_set
del(multiple)	multi_del
keys	keys(for kv type only)
getset	getset
setnx	setnx
exists	exists
ttl	ttl
expire	expire
getbit	getbit
setbit	setbit
bitcount	redis_bitcount, countbit
strlen	strlen
getrange	getrange

Key-(Key-Value)

Redis	SSDB
del(not supported)	hclear
hget	hget
hset	hset
hdel, hmdel	hdel, multi_hdel
hIncrBy	hincr
hDecrBy	hdecr
hKeys	hkeys
hVals	hscan
hMGet	multi_hget
hMSet	multi_hset
hLen	hsize
hExists	hexists
keys	hlist(for hash type only)

Key - (Sorted List)

Redis	SSDB
del(not supported)	zclear
zScore	zget
zAdd	zset
zRem	zdel
zRange	zrange
zRevRange	zrrange
zRangeByScore	zscan
zRevRangeByScore	zrscan
zIncrBy	zincr
zDecrBy	zdecr
zCount	zcount
zSum	zsum
zAvg	zavg
zCard	zsize
zRank	zrank
zRemRangeByRank	zremrangebyrank
zRemRangeByScore	zremrangebyscore
keys	zlist(for zset type only)

Key-Queue

Redis	SSDB
del(not supported)	qclear
llen/lsize	qsize
lpush	qpush_front
rpush	qpush_back
lpop	qpop_front
rpop	qpop_back
lrange	qslice
lindex, lget	qget
lset	qset
keys	qlist(for queue/list type only)

Dashboard

The dashboard can be accessed via the CLI:

$ heroku addons:open ssdb
Opening ssdb for sharp-mountain-4005

or by visiting the Heroku Dashboard and selecting the application in question. Select SSDB from the Add-ons menu.

The dashboard contains following components:

Connection Details

The variables you should use in order to connect and authenticate against your SSDB cluster. They shown at the top of the dashboard.

SSDB_HOST
SSDB_PORT
SSDB_URL
SSDB_PASSWORD

Plan Usage

There are a couple of important things to know about the Plan Usage representation:

It indicates how much space on the disk is used by your database.
It's calculated approximately, so you might notice minor variations in it's value.
It represents the size of compressed data. The actual size of data might be by 1.5 - 4 times bigger.

It's important to not exceed the Plan Usage limit, provided by your plan. If this happens, we will send you an email and post the notice at your Dashboard.

Backup Button

Backup Button downloads SSDB dump file to your local computer. Keep in mind that the size of the dump file might be by 1.5-4 times bigger then it's indicated by Plan Usage.

Flush All Button

You can remove all data from the database by clicking "Flush All" button. This will schedule flushdb action to all SSDB nodes in your cluster. It may take awhile to process this action, before the changes will be shown on the dashboard.

Troubleshooting

In case of connection problems, please make sure you are using right connection details.

If you are getting an alert message on the top of the dashboard view, saying that Plan Usage limit is exceeded, you should consider to decrease the amount of data in your database, or update your plan to get a higher limit.

You may see the message, saying that your account has been suspended, which means the Plan Usage limit was extensively outreached and your SSDB nodes were killed by the system. All the data stored on them is lost in such a case.

Given the above, it's a good practice to make regular backups. All our plans provide possibility to download SSDB dump file to your local machine.

Our Premium Plans provides automatic backups, managed by us and available for download for period of one week.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade ssdb:newplan
-----> Upgrading ssdb:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: ssdb:newplan

Removing the add-on

SSDBHub plugin can be removed via the CLI.

$ heroku addons:destroy ssdb
-----> Removing ssdb from sharp-mountain-4005... done, v20 (free)

Support

All SSDBHub support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback are welcome at feedback@ssdbhub.com

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ReadmeHeroku.md

ReadmeHeroku.md

Provisioning the add-on

Local setup

Environment setup

Using SSDB with Different Languages

Using with Java

Using with Python

Using with Node

Using with Go

Using with Ruby

Using with PHP

Using with Redis Clients

Key-Value

Key-(Key-Value)

Key - (Sorted List)

Key-Queue

Dashboard

Connection Details

Plan Usage

Backup Button

Flush All Button

Troubleshooting

Migrating between plans

Removing the add-on

Support

Files

ReadmeHeroku.md

Latest commit

History

ReadmeHeroku.md

File metadata and controls

Provisioning the add-on

Local setup

Environment setup

Using SSDB with Different Languages

Using with Java

Using with Python

Using with Node

Using with Go

Using with Ruby

Using with PHP

Using with Redis Clients

Key-Value

Key-(Key-Value)

Key - (Sorted List)

Key-Queue

Dashboard

Connection Details

Plan Usage

Backup Button

Flush All Button

Troubleshooting

Migrating between plans

Removing the add-on

Support