The NOSQL "movement" is, first off, not an outright rejection of traditional relational database management systems (RDBMS) but rather a growing recognition that today’s data environment requires a diverse storage toolset that is "Not Only SQL (NOSQL)". Relational and NOSQL data storage solutions should be viewed as complements, with each approach better suited toward different types of applications and services.

The main driver of NOSQL has been the proliferation of applications and services that must store and serve terabytes or petabytes of data, often while striving to guarantee "always-on" availability and low latencies for end users. Organizations in many market sectors are grappling with the advent of Big Data, including but not limited to:

Organizations in these and other data-intensive environments have been challenged to build data storage systems of unprecedented scale. Many such organizations have found their needs ill-met by traditional data storage approaches that center around relational database management systems and specialized high-end hardware. In particular:

Wanting Big Data capacity without crippling cost and complexity, some innovative organizations have sought a better way to scale. At the same time, with an ever-expanding array of data usage scenarios, it’s become apparent that not all scenarios require the complex querying and management functionality associated with an RDBMS. For some applications and services, SQL-structuring and strict ACID properties are overkill. Worse, in some environments they’re expensive overkill that can potentially hamstring service offerings in highly competitive markets that demand flexibility and responsiveness.

In short, recent years have seen a proliferation of services that require more data, with less structure.

Not surprisingly, some of the leading web enterprises have been at the forefront of the NOSQL movement. In particular, Google with its BigTable paper in 2006 and Amazon with its Dynamopaper in 2007 had a profound effect on the NOSQL market. A number of NOSQL solutions have drawn inspiration from either BigTable or Dynamo or both, and in the past couple years several solutions have been released into the open source community.

While NOSQL data storage solutions vary in their particulars, they have these basic traits in common:

For much more on the history, merits, and design issues associated with NOSQL storage solutions, consult with your favorite search engine.

Hibari was developed internally by Cloudian, Inc. (formerly Gemini Mobile Technologies), a leading producer of mass-scale messaging and transaction systems for Tier 1 mobile operators in Asia, Europe, and the Americas. Cloudian had need for a data store that was efficient, fast, flexible, and scalable, as well as robust enough to withstand the rigors of deployment in Tier 1 telecom production environments. Dissatisfied with the then-available options, Cloudian in 2005 began work on what

came to be Hibari (the name is Japanese for skylark; the kanji characters stand for "cloud bird"). With the system having in recent years matured and been proven in production, Cloudian released Hibari to the open source community in July 2010 under the Apache 2.0 license. Cloudian regards the open source community as the best venue in which Hibari can continue to perfect and grow.

This section describes some of the distinctive features that make Hibari a very attractive option for businesses and developers seeking a modern Big Data storage system:

Easy, Affordable Scalability

Hibari provides Big Data scalability while minimizing the cost and operational complexity of cluster growth:

• Hibari scales horizontally by the addition of more chains, deployed on more physical nodes. The total storage and processing capacity of a Hibari cluster increases linearly as machines are added to the cluster.
• The system rebalances data storage distribution automatically as chains are added to (or removed from) the cluster, with no downtime. You can grow (or shrink) your Hibari storage cluster with no service interruption.
• Hibari runs on commodity PCs. Further, the system easily accommodates heterogeneous hardware resources. Bricks within the storage cluster can have different RAM and disk sizes, and different CPU speeds. You can tune Hibari’s consistent hash function to optimize your cluster’s utilization of mixed hardware. Each chain can be assigned a weighting factor that will increase or decrease that chain’s portion of the overall key space, relative to other chains.

In addition to supporting mixed hardware, Erlang-based Hibari can run on most any OS. With its easy adaptability to disparate hardware and operating systems, you can scale Hibari incrementally, with whatever resources you have available. It’s not necessary to buy all your resources at once, or all of the same kind.

The outer limits of Hibari’s horizontal scalability have not been definitely determined, but 200 to 250 nodes is a practical boundary due to the limitations of Erlang’s built-in network distribution implementation. Also, while Hibari chains could theoretically be stretched across multiple data centers to provide geographic redundancy, to date only single data center deployments have been tested and used in production.

For further information on resizing a Hibari cluster, see Dynamic Cluster Reconfiguration in the Hibari System Administrator’s Guide.

Simple But Powerful Client API

As a key-value store, Hibari’s core data model and client API model are simple by design: blob-based key-value pairs can be inserted, retrieved, and deleted from lexicographically sorted tables. While Hibari thus provides the flexibility and scalability associated with key-value stores, the system also provides distinctive features that enhance the power of client applications and developers:

• Clients can optionally assign per-object expiration times.
• Clients can optionally assign per-object custom flags. This flexible, custom meta-data can be updated with or without updating the associated value blob, and can be retrieved with or without the value blob.
• Objects are automatically timestamped each time they are updated. This timestamping mechanism facilitates "test-and-set" type operations: clients can specify that a requested operation be performed only if the target key’s timestamp matches the client’s expectations.
• Within key-prefix range limits (specifically, within individual chains but not across chains), Hibari’s client API supports atomic transactions. This support for "micro-transactions" sets Hibari apart from other open source KVDBs and can greatly simplify the creation of robust client applications.

Hibari supports multiple client API implementations including:

• Native Erlang
• Universal Binary Format (UBF)
• Thrift
• Amazon S3
• JSON-RPC

You can develop Hibari client applications in a variety of languages including Java, C/C++, Python, Ruby, and Erlang.

For further information about Hibari’s client API, see Client API: Native Erlang and the subsequent client API chapters in this guide.

	The Hibari source distribution does not include Amazon S3 and JSON-RPC. They are separate external projects.

Hibari will run on any OS that the Erlang VM supports, which includes most Unix and Unix-like systems, Windows, and Mac OS X. See Implementation and Ports of Erlang from the official Erlang documentation for further information.

For guidance on hardware requirements in a production environment, see Notes on Brick Hardware in the Hibari System Administrator’s Guide.

Hibari’s requirements for third party software depend on whether you’re doing a single-node installation or a multi-node installation.

Hibari is not yet available as a pre-built release. In the meanwhile, you can build Hibari from source. Follow the instructions in Section 9, “Building Hibari from Source”, and then return to this section to continue the set-up process.

When you build Hibari your output is two files that you will later use in the set-up process:

X.Y.Z is the release version, DIST is the release distribution, ARCH is the release architecture, and WORDSIZE is the release wordsize.

A single-node Hibari system will not provide data replication and redundancy in the way that a multi-node Hibari cluster will. However, you may wish to deploy a simple single-node Hibari system for testing and development purposes.

	On your Hibari node, in the system’s /etc/sysctl.conf file, set vm.swappiness=0. Swappiness is not desirable for an Erlang VM.

Before you install Hibari on to the target nodes you must complete these preparation steps:

Setting Up Your User Privileges

The system user ID that you use to perform the installation must be different than the Hibari runtime user. Your installing user account ($USER) must be set up as follows:

• $USER must exist on the installer node and also on the target Hibari nodes.
• $USER on the installer node must have SSH private/public keys, with the SSH agent set up to enable password-less SSH login.
• $USER account must be accessible with password-less SSH login on the target Hibari nodes.
• $USER must have password-less sudo access on the target Hibari nodes.

If your installing user account does not currently have the above privileges, follow these steps:

1. As the root user, add your installing user ($USER) to the installer node. Then on each of the Hibari nodes, add your installing user and grant your user password-less sudo access:

   $ useradd $USER
   $ passwd $USER
   $ visudo
   # append the following line and save it
   $USER  ALL=(ALL)       NOPASSWD: ALL

   	If you get a "sudo: sorry, you must have a tty to run sudo" error while testing sudo, try commenting out following line inside of the /etc/sudoers file:

   $ visudo
   Defaults    requiretty

2. On the installer node, create a new SSH private/public key for your installing user:

   $ ssh-keygen
   # enter your password for the private key
   $ eval `ssh-agent`
   $ ssh-add ~/.ssh/id_rsa
   # re-enter your password for the private key

3. On each of the Hibari nodes:

   • Append an entry for the installer node to the \~/.ssh/known_hosts file.

   • Append an entry for your public SSH key to the ~/.ssh/authorized_keys file.

     In the example below, the target Hibari nodes are dev1, dev2, and dev3:

     $ ssh-copy-id -i ~/.ssh/id_rsa.pub $USER@dev1
     $ ssh-copy-id -i ~/.ssh/id_rsa.pub $USER@dev2
     $ ssh-copy-id -i ~/.ssh/id_rsa.pub $USER@dev3

     	If your installer node will be one of the Hibari cluster nodes, make sure that you ssh-copy-id to the installer node also.

4. Confirm that password-less SSH access to the each of the Hibari nodes works as expected.

   $ ssh $USER@dev1
   $ ssh $USER@dev2
   $ ssh $USER@dev3

	If you need more help with SSH set-up, check http://inside.mines.edu/~gmurray/HowTo/sshNotes.html.

Downloading the Cluster Installer Tool

"Cluster" is a simple tool for installing, configuring, and bootstrapping a cluster of Hibari nodes. The tool is not part of the Hibari package itself, but is available from GitHub.

	The Cluster tool should meet the needs of most users. However, this tool’s "target node" recipe is currently Linux-centric (e.g. useradd, userdel, …). Patches and contributions for other OS and platforms are welcome. For non-Linux deployments, the Cluster tool is rather simple so installation can be done manually by following the tool’s recipe.

1. Create a working directory into which you will download the Cluster installer tool:

   $ mkdir working-directory

2. Download the Cluster tool’s Git repository from GitHub:

   $ cd working-directory
   $ git clone git://github.com/hibari/clus.git

   The download creates a sub-directory clus under which the installer tool and various supporting files are stored.

Configuring the Cluster Installer Tool

The Cluster tool requires some basic configuration information that indicates how you want your Hibari cluster to be set up. You will create a simple text file that specifies your desired configuration, and then later use the file as input when you run the Cluster tool.

It’s simplest to create the file in the same working directory in which you downloaded the cluster tool. You can give the file any name that you want; for purposes of these instructions we will use the file name hibari.config.

Below is a sample hibari.config file. The file that you create must include all of these parameters, and the values must be formatted in the same way as in this example (with parentheses and quotation marks as shown). Parameter descriptions follow the example file.

ADMIN_NODES=(dev1 dev2 dev3)
BRICK_NODES=(dev1 dev2 dev3)
BRICKS_PER_CHAIN=2

ALL_NODES=(dev1 dev2 dev3)
ALL_NETA_ADDRS=("10.181.165.230" "10.181.165.231" "10.181.165.232")
ALL_NETB_ADDRS=("10.181.165.230" "10.181.165.231" "10.181.165.232")
ALL_NETA_BCAST="10.181.165.255"
ALL_NETB_BCAST="10.181.165.255"
ALL_NETA_TIEBREAKER="10.181.165.1"

ALL_HEART_UDP_PORT="63099"
ALL_HEART_XMIT_UDP_PORT="63100"

• ADMIN_NODES

  • Host names of the nodes that will be eligible to run the Hibari Admin Server. For complete information on the Admin Server, see The Admin Server Application in the Hibari System Administrator’s Guide.

• BRICK_NODES

  • Host names of the nodes that will serve as Hibari storage bricks. Note that in the sample configuration file above there are three storage brick nodes (dev1, dev2, and dev3), and these three nodes are each eligible to run the Admin Server.

• BRICKS_PER_CHAIN

  • Number of bricks per replication chain. For example, with two bricks per chain there will be two copies of the data stored in the chain (one copy on each brick); with three bricks per chain there will be three copies, and so on. For an overview of chain replication, see Chain Replication for High Availability and Strong Consistency in this document. For chain replication detail, see the Hibari System Administrator’s Guide.

• ALL_NODES

  • This list of all Hibari nodes is the union of ADMIN_NODES and BRICK_NODES.

• ALL_NETA_ADDRS

  • As described in The Partition Detector Application in the Hibari System Administrator’s guide, the nodes in a multi-node Hibari cluster should be connected by two networks, Network A and Network B, in order to detect and manage network partitions. The ALL_NETA_ADDRS parameter specifies the IP addresses of each Hibari node within Network A, which is the network through which data replication and other Erlang communications will take place. The list of the IP addresses should correspond in order to host names you listed in the ALL_NODES setting.

• ALL_NETB_ADDRS

  • IP addresses of each Hibari node within Network B. Network B is used only for heartbeat broadcasts that help to detect network partitions. The list of the IP addresses should correspond in order to host names you listed in the ALL_NODES setting.

• ALL_NETA_BCAST

  • IP broadcast address for Network A.

• ALL_NETB_BCAST

  • IP broadcast address for Network B.

• ALL_NETA_TIEBREAKER

  • Within Network A, the IP address for the network monitoring application to use as a "tiebreaker" in the event of a partition. If the network monitoring application on a Hibari node determines that Network A is partitioned and Network B is not partitioned, then if the Network A tiebreaker IP address responds to a ping, then the local node is on the "correct" side of the partition. Ideally the tiebreaker should be the address of the Layer 2 switch or Layer 3 router that all Erlang network distribution communications flow through.

• ALL_HEART_UDP_PORT

  • UDP port for heartbeat listener.

• ALL_HEART_XMIT_UDP_PORT

  • UDP port for heartbeat transmitter.

For more detail on network monitoring configuration settings, see the partition-detector’s OTP application source file (https://github.com/hibari/partition-detector/raw/master/src/partition_detector.app.src).

	In a production setting, Network A and Network B should be physically different networks and network interfaces. However, for testing and development purposes the same physical network can be used for Network A and Network B (as in the sample configuration file above).

As final configuration steps, on each Hibari node:

• Make sure that the /etc/hosts file has entries for all Hibari nodes in the cluster. For example:

  10.181.165.230  dev1.your-domain.com    dev1
  10.181.165.231  dev2.your-domain.com    dev2
  10.181.165.232  dev3.your-domain.com    dev3

• In the system’s /etc/sysctl.conf file, set vm.swappiness=0. Swappiness is not desirable for an Erlang VM.

You can use the Cluster installer tool to start and stop your multi-node Hibari cluster, working from the same node from which you managed the installation process. Note that in each of the Hibari commands in this section you’ll be referencing the name of the Cluster tool configuration file that you created during the installation procedure.

$ cd working-directory
$ ./clus/priv/clus-hibari.sh -f stop hibari hibari.config
ok
ok
ok
hibari@dev1
hibari@dev2
hibari@dev3

The simplest way to create a new table is via the Admin Server’s GUI. Open http://localhost:23080/ and click the "Add a table" link. In addition to the GUI, the hibari-admin tool can also be used to create a new table. See the hibari-admin tool for usage details.

	For information about creating tables using the administrative API, see the Hibari System Administrator’s Guide.

When adding a table through the GUI, you have these table configuration options:

As a key-value database, Hibari provides a simple client API with primitive operations for inserting, retrieving, and deleting data. Within certain restrictions, the API also supports compound operations that optionally can be executed as atomic transactions.

More specifically, Hibari’s client API supports the operations listed below. For details on the native Erlang API for each operation, follow the links.

Data Insertion

Data Retrieval

Data Deletion

Compound Operations

Fold Operations

If desired, clients can apply a "test 'n set" logic to data insertion, retrieval, and deletion operations so that the operation will be executed only if the target key has the exact timestamp specified in the request.

Erlang Basic Data Types

The following provides a high level introduction to Erlang basic data types that are referenced in this chapter. This material is excerpted with minor modifications from the official Erlang documentation on data types. For further information, see the official Erlang documentation.

	All Erlang commands must conclude with a period (.).

Term

A piece of data of any data type is called a term.

Number

There are two types of numeric literals, integers and floats.

Atom

An atom is a literal, a constant with name. An atom should be enclosed in single quotes (') if it does not begin with a lower-case letter or if it contains other characters than alphanumeric characters, underscore (_), or @. Optionally, any atom can be enclosed in single quotes. For example:

hello
phone_number
'Monday'
'phone number'
'hello'
'phone_number'

Bit String and Binary

A bit string is used to store an area of untyped memory. Bit strings are expressed using Erlang bit syntax. A bit string that consists of a number of bits that is evenly divisible by eight is called a binary. For example:

<<10,20>>
<<"ABC">>

Tuple

A tuple is a compound data type with a fixed number of terms, enclosed by braces:

{Term1,...,TermN}

List

A list is a compound data type with a variable number of terms, enclosed by square brackets:

[Term1,...,TermN]

String

Strings are enclosed in double quotes ("), but are not a true data type in Erlang. Instead a string "hello" is shorthand for the list [$h,$e,$l,$l,$o], that is [104,101,108,108,111].

Boolean

There is no Boolean data type in Erlang. Instead the atoms true and false are used to denote Boolean values.

CREATE TABLE foo (
    BLOB key;
    BLOB value;
    INTEGER timestamp;                  -- Monotonically increasing
    INTEGER expiration_time;            -- Usually zero
    LIST OF ATOMS_AND_TWO_TUPLES flags; -- Metadata stored in RAM for speed
) PRIMARY KEY key;

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURNS

ALIASES

EXAMPLES

SYNOPSIS

DESCRIPTION

	Do not execute this operation while a data migration is being performed.

PARAMETERS

RETURNS

ALIASES

EXAMPLES

to be added

SYNOPSIS

DESCRIPTION

	Do not execute this operation while a data migration is being performed.

PARAMETERS

RETURNS

ALIASES

EXAMPLES

to be added

The Erlang language does not have a data type specifically for strings. Instead, strings are typically represented as lists of integers (ASCII byte values) and/or binaries.

A UBF contract makes a distinction between a string, list, and binary. In the case of a string, UBF(A) encodes a string using the notation {'#S', "Hello, world!"} to represent the string "Hello, world!".

This string encoding is cumbersome to use for developers; in Erlang, the ubf.hrl header file includes a macro ?S("Hello, world!") as a slightly less ugly shortcut. When using other languages, the 2-tuple and the atom '#S' would be created as any other 2-tuple and atom.

Fortunately, there is only one case where the string type is necessary: using the startSession metaprotocol command to start using the Hibari data server contract. An example will be shown below.

The steps to use a UBF-based protocol are the same in any language.

The Hibari UBF Protocol contract can be found in the file ubf_gdss_plugin.con.

	See the Hibari source code for the most up-to-date version of this file. This documentation has a copy of ubf_gdss_plugin.con, though it may be slightly out-of-date.

The names of the UBF types specified in the contract may differ slightly from the names of the types used in this document’s Section 5, “Client API: Native Erlang”. For example, the UBF contract calls the key expiration time time exp_time(), while the type system in this document calls it expiry(). However, in all cases of slightly different names, the fundamental data type that both names use is the same: e.g. integer() for expiration time.

For each command, the UBF contract uses the following naming conventions:

The general form of a UBF RPC call is a tuple. The first element in the tuple is the name of the command, and the following elements are arguments for that command. The response can be any Erlang term, but the Hibari contract will only return the atom or tuple types.

The following is a mapping of UBF client request type to its Erlang API function, in alphabetical order.:

When using the Erlang shell for experimentation & prototyping, that shell must have the path to the Erlang UBF client library in its search path. The easiest way to do this is to use the arguments -pz /path/to/ubf/library/ebin to your Erlang shell’s erl command. When writing code, the statement -include("ubf.hrl"). at the top of your source module to gain access to the ?S() macro. Due to limitations in the Erlang shell, macros cannot be used in the shell.

As outlined in Section 6.3, “Steps for Using a UBF-based Protocol in Any Language”, the first step is to create a connection to a Hibari server. If the Hibari cluster has multiple nodes, then it doesn’t matter which one that you connect to: all nodes can handle any UBF request and will route the query to the proper brick.

Create a connection to the UBF server (on "localhost" TCP port 7581). 

(asdf@bb3)54> {ok, P1, _} = ubf_client:connect("localhost", 7581, [{proto, ubf}], 5000).
{ok,<0.139.0>,{'#S', "gdss_meta_server"}}

The second step is to use the UBF metaprotocol to select the Hibari server, contract, called "gdss", for all further commands for this connection.

	The Hibari server contract is "stateless". All replies terms from the ubf_client:rpc/2 function use the form {reply,ServerReply,UBF_StateName}. Because the Hibari server contract is stateless, the UBF_StateName will always be the atom none.

Use the UBF metaprotocol to request the "gdss" contract. 

(asdf@bb3)55> ubf_client:rpc(P1, {startSession, {'#S', "gdss"}, []}).
{reply,{ok,ok},none}

Now that the UBF connection is set up, we can use it to set a key "foo".

Set the key "foo" in table tab1 with the value "foo val", no. 

expiration time, no flags, and a timeout of 5 seconds

(asdf@bb3)59> ubf_client:rpc(P1, {set, tab1, <<"foo">>, <<"foo val">>, 0, [], 5000}).
{reply,ok,none}

	Note that the return value of both the set_req() (in the example above) and get_req() (in the example below) return the same types described in the Section 5.4, “brick_simple:set/6” and Section 5.6, “brick_simple:get/4”, respectively. The only difference is that the ubf_client:rpc/2 function wraps the server’s reply in a 3-tuple: {reply,ServerReply,none}.

Get the key "foo" in table tab1, timeout in 5 seconds. 

(asdf@bb3)66> ubf_client:rpc(P1, {get, tab1, <<"foo">>, [], 5000}).
{reply,{ok,1273009092549799,<<"foo val">>},none}

If the client sends a request that violates the contract, the server will tell you, as in this example:

Send a contract-violating request. 

(asdf@bb3)89> ubf_client:rpc(P1, {bbb, 3000}).
{reply,{clientBrokeContract,{bbb,3000},[]},none}

When you are done with the connection, it is polite to close the connection explicitly. The server will quietly clean up its side of the connection if the client forgets to call or cannot call stop/1.

Close the UBF connection. 

(asdf@bb3)92> ubf_client:stop(P1).
ok

The source code for the UBF client library for Java is included in the UBF source repository at http://github.com/ubf/ubf, in the priv/java subdirectory.

public class HibariTest
{
    public static void main(String[] args)
        throws Exception
    {
        Socket sock = null;
        UBFClient ubf = null;

        try {
            sock = new Socket(args[0], 7581);
            ubf = UBFClient.new_via_sock(new UBFString("gdss"), new UBFList(),
                    new FooHandler(), sock);
        }
        catch (Exception e) {
            System.out.println(e);
            System.exit(1);
        }

        test_hibari_basics(ubf);

        ubf.stopSession();
        System.out.println("Success, it works");
        System.exit(0);
    }
/* ... */
}

The UBF event handler interface

Each UBFClient instance uses a separate thread to read data from the server and do any of the following:

1. Signal to the other thread that a synchronous RPC response was received from the server.
2. Run a callback function when an event_out asynchronous event is received from the server.
3. The socket was closed unexpectedly.

In cases #2 and #3, a class that implements the UBFEventHandler interface is used to define the action to be taken in those cases.

The HibariTest.java contains a sample implementation of callback functions for asynchronous events. A real application would probably want to do something much more helpful than this example does.

    public static class FooHandler implements UBFEventHandler {
        public FooHandler() {
        }
        public void handleEvent(UBFClient client, UBFObject event) {
            System.out.println("Hey, got an event: " + event.toString());
        }
        public void connectionClosed(UBFClient client) {
            System.out.println("Hey, connection closed, ignoring it\n");
        }
    }

	See The ubf.HibariTest.main() method for an example that uses this FooHandler class.

The source code for the EBF client library for Python is included in the UBF source repository at http://github.com/ubf/ubf, in the priv/python subdirectory.

	Recall that the EBF protocol is very closely related to UBF. The only significant difference is the "layer 5" session protocol layer: instead of using the UBF(A) protocol, the EBF (Erlang Binary Format) protocol is used instead. See Section 6.1, “The Hibari Server’s Implementation of the UBF Protocol Stack” for more details.

In addition, you will need the "py_interface" package, developed by Tomas Abrahamsson and others. "py-interface" is distributed under the GNU Library General Public License. A git repository is hosted at repo.or.cz. To clone it and build it, use:

git clone git://repo.or.cz/py_interface.git
cd py_interface
autoconf
./configure
make
pwd

Use the output of the last command, pwd, to remember the full directory path to the "py-interface" library. The example below assumes that path is /tmp/py-interface.

The pyebf.py file contains a small unit test that makes several calls to the Hibari UBF contract’s do_req() command. The results of (almost) every command are verified using the assert function.

env PYTHONPATH=/path/to/py_interface python pyebf.py

The Hibari Thrift API is defined as Hibari Service in hibari.thrift. At the time this API was developed, only Thrift 0.4.0 is available to us. This version is our first attempt to adopt Thrift. Some of the functions and options are not yet supported.

	The Hibari Thrift API only supports Thrift 0.4.0 or above.

service Hibari {

  /**
   * Check connection availability / keepalive
   */
  oneway void keepalive()

  /**
   * Hibari Server Info
   */
  string info()

  /**
   * Hibari Description
   */
  string description()

  /**
   * Hibari Contract
   */
  string contract()

  /**
   * Add
   */
  HibariResponse Add(1: Add request)
      throws (1:HibariException ouch)

  /**
   * Replace
   */
  HibariResponse Replace(1: Replace request)
      throws (1:HibariException ouch)

  /**
   * Set
   */
  HibariResponse Set(1: Set request)
      throws (1:HibariException ouch)

  /**
   * Rename
   */
  HibariResponse Rename(1: Rename request)
      throws (1:HibariException ouch)

  /**
   * Delete
   */
  HibariResponse Delete(1: Delete request)
      throws (1:HibariException ouch)

  /**
   * Get
   */
  HibariResponse Get(1: Get request)
      throws (1:HibariException ouch)
}

For each primitive utility function, it has exactly one input parameter. The parameter is an object that has a name matching its function. The object carries all mandatory and optional parameters to Hibari. This object could also be used to implement micro-transactions in the future.

You can find more details of the UBF / Thrift type conversion in (UBF-Thrift).

Mapping UBF types to thrift primitives is different from mapping UBF contracts to service. Thrift mainly uses 2 different types to compose a request (struct and field).

If you are using Thrift to generate client code, you probably don’t need to worry about how the request being constructed. Visit Thrift Wiki for the instruction to install Thrift and to generate client code. You will also need hibari.thrift to get started.

If you are interested in the UBF contract, the Hibari NTBF contract can be found in the file of ntbf_gdss_plugin.con.

Once you get the generated code, connecting to Hibari is easy. For example, adding the key 'fookey' to table tab1 with a value of 'Hello, world!' in the following 3 languages.

In Erlang:

  -include("hibari_thrift.hrl").

  % init
  {ok, Client} = thrift_client:start_link("127.0.0.1", 7600, hibari_thrift),

  % create the input parameter object
  Request = #add{table=<<"tab1">>, key=<<"fookey">>, value=<<"Hello, world!">},

  % send request
  try
    HibariResponse = thrift_client:call(Client, 'Add', [Request]),
  catch
    HibariException ->
      HibariException
  end,

  ok = thrift_client:close(Client).

In Java:

  import com.hibari.rpc.*;

  // init
  TTransport transport = new TSocket("127.0.0.1", 7600);
  TProtocol proto = new TBinaryProtocol(transport);
  Hibari.Client client = new Hibari.Client(proto);
  transport.open();

  // create the input parameter object
  Add request = new Add("tab1", ByteBuffer.wrap("fookey".getBytes()),
    ByteBuffer.wrap("Hello, world!".getBytes())))

  // send request
  try {
    HibariResponse response = client.Add(request);
  } catch (HibariException e) {
    // ...
  }

  transport.close();

In python:

  from hibari import Hibari

  # init
  transport = TSocket.TSocket('localhost', 7600)
  transport.setTimeout(None)
  transport = TTransport.TBufferedTransport(transport)
  protocol = TBinaryProtocol.TBinaryProtocol(transport)
  client = Hibari.Client(protocol)
  transport.open()

  # create the input parameter object
  request = Add()
  request.table = "tab1"
  request.key = b"fookey"
  request.value = b"Hello, world!"

  # send request
  response = client.Add(request)

  transport.close()

TBF only responses one of two generic types to all functions in Hibari Thrift API, HibariResponse or HibariException. One could expect a HibariResponse in an any successful cases. Otherwise a HibariException should be thrown.

to be added

to be added

Before getting started, review this checklist of tools and software. Please install and set up as needed.

Follow these steps to download the Hibari repositories from GitHub.

<working-directory>
  |- hibari/
    |- .git/
    |- .gitignore
    |- Makefile
    |- dialyze-ignore-warnings.txt
    |- dialyze-nospec-ignore-warnings.txt
    |- lib/                             
      |- <application_name>/
        |- .git/
        |- .gitignore
        |- ebin/
        |- include/
          |- *.hrl
        |- priv/
        |- rebar.config
        |- src/
          |- <application_name>.app.src
          |- *.erl
        |- test/
          |- eunit/
            |- *.erl
          |- eqc/
            |- *.erl
      :
    |- rebar
    |- rebar.config
    |- rel/                             
      |- files/
        |- app.config
        |- erl
        |- hibari
        |- hibari-admin
        |- nodetool
        |- nodetool-admin
        |- vm.args
      |- hibari/
        :
        |- releases/
          |- <release_vsn>/
            :
          :
        :
      |- reltool.config
  |- hibari-doc/                        
    :
  |- manifests/                         
    :
  |- patches/                           
    :
  |- rebar/                             
    :
  |- .repo/
    :

Follow these steps to build a Hibari release package.

Follow these steps to build Hibari’s documentation.

Hibari’s documentation is authored using AsciiDoc and a few auxillary tools:

Hibari’s documentation is generated with AsciiDoc and a manually modified version of the a2x tool. A fake lang-ja.conf file can be easily created by making a symlink to the lang-en.conf file.

diff -r -u 8.6.4-orig/bin/a2x.py 8.6.4/bin/a2x.py
--- 8.6.4-orig/bin/a2x.py       2011-04-24 00:50:26.000000000 +0900
+++ 8.6.4/bin/a2x.py    2011-04-24 00:35:55.000000000 +0900
@@ -156,7 +156,10 @@
 def shell_copy(src, dst):
     verbose('copying "%s" to "%s"' % (src,dst))
     if not OPTIONS.dry_run:
-        shutil.copy(src, dst)
+        try:
+            shutil.copy(src, dst)
+        except shutil.Error:
+            return

 def shell_rm(path):
     if not os.path.exists(path):
Only in 8.6.4/etc/asciidoc: lang-ja.conf

Follow these steps to download and build Erlang/OTP from source, and to install the system. These steps provide a basic recipe; not all options are addressed.

	Please make sure to have the openssl-devel package installed on your system before configuring and building Erlang/OTP.

	Please make sure "otp-installing-directory-name/bin" is added to your $PATH environment.

to be added

List the working directories for all of Hibari’s "projects":

$ repo forall -c "pwd"

	Each project has a corresponding Git repository and (default) revision. Check the "manifests/hibari-default.xml" file for details.

Start a new topic (e.g. new-topic-name) branch:

$ repo start new-topic-name `repo forall -c "pwd" | xargs echo`

Abandon an existing topic (e.g. topic-name) branch:

$ repo abandon topic-name `repo forall -c "pwd" | xargs echo`

Track and checkout the master branch:

$ repo forall -c "git branch --track master github/master"
$ repo forall -c "git checkout master"

Track and checkout the dev (i.e. Development) branch:

$ repo forall -c "git branch --track dev github/dev"
$ repo forall -c "git checkout dev"

to be added

to be added

to be added