Getting started

HerdDB was created from the get go to be a JVM-Embedded database and from a developer point of view the best way to start playing with it is through a Java application.

For a list of installation mode and recipes please refer to this page.

try (HerdDBEmbeddedDataSource dataSource = new HerdDBEmbeddedDataSource();) {
        try (Connection con = dataSource.getConnection();
                Statement statement = con.createStatement();) {
                statement.execute("CREATE TABLE mytable (key string primary key, name string)");
                    try (PreparedStatement ps = con.prepareStatement("INSERT INTO mytable(key,name) values(?,?)")) {
                            ps.setString(1,"foo");
                            ps.setString(2,"bar");
                        ps.executeUpdate();
                } 
}

Please note that the main API used in production to connect to HerdDB is the JDBC driver and that the "internal" API could change from version to version.

Running a simple standalone HerdDB server

HerdDB could also run in standalone mode with the Server separated from the Client.

You can start by using docker.

Or just download a release, unzip the package and run

bin/service server start
tail -f server.service.log

NOTE: if you need to specify the JAVA_HOME please edit the script under bin/setenv.sh

In order to use the command line interface use

bin/herddb-cli.sh -x jdbc:herddb:server:$(hostname):7000 -q "select * from sysnodes"

or to use the interactive console:

bin/herddb-cli.sh -x jdbc:herddb:server:$(hostname):7000 -sc

or to see an overview using the Web UI open your browser at

http://localhost:9845/ui/#/home?url=jdbc:herddb:server:localhost:7000

remember to check your log file service.server.log

tail -f service.server.log

This way you will connect to HerdDB using the JDBC driver and the JDBC URL: jdbc:herddb:server:myserver.name:7000

try (Connection connection = DriverManager.getConnection("jdbc:herddb:server:localhost:7000?", "myuser", "mypassword");
                    Statement statement = connection.createStatement();
                    ResultSet rs = statement.executeQuery("SELECT * FROM SYSTABLES")) {
                assertTrue(rs.next());
}

If you need to setup a datasource you should at least set this properties:

• JDBC Driver: herddb.jdbc.Driver
• JDBC URL: jdbc:herddb:server:$(hostname):7000
• Default username: sa
• Default password: hdb

Inside the zip you will find also the standalone HerdDB JDBC Driver named: herddb-jdbc-VERSION.jar. Please nota that this "UBER" jar contains the HerdDB client runtime and all the needed dependencies (like Netty and ZookKeeper).

Setup your first cluster

In order to setup your first cluster you need a ZooKeeper server. If you want to start a standalone ZooKeeper just for playing you can use the following command

bin/service zookeeper start

Then you have to configure HerdDB and change server.mode in conf/server.properties

server.mode=cluster

By default the server will start an embedded Apache BookKeeper server (Bookie)

The JDBC connection string now will be jdbc:herddb:zookeeper:localhost:2181

and the CLI will be:

    bin/herddb-cli.sh -x jdbc:herddb:zookeeper:localhost:2181 -sc

Now unzip the distribution zip in another directory, make the following changes to the conf/server.properties and then start the new node:

    server.mode=cluster
    server.port=7100
    http.port=9846

Connecting to the CLI again you could setup the replication of the default tablespace "herd" to the second node and setup the failover timeframe:

    ALTER TABLESPACE 'herd','expectedreplicacount:2','maxleaderinactivitytime:60000'

You could also create a new tablespace, force a change of leadership, and create a test table:

    CREATE TABLESPACE 'mytablespace','expectedreplicacount:2'
    SELECT * FROM SYSTABLESPACEREPLICASTATE
    ALTER TABLESPACE 'mytablespace','leader:NODEID','maxleaderinactivitytime:60000'
    CREATE TABLE mytablespace.test1 (id long AUTO_INCREMENT PRIMARY KEY, lastname varchar(255), firstname varchar(255), address varchar(255), city varchar(255))
    INSERT INTO mytablespace.test1 (id,lastname,firstname,address,city) values (null,'Bob','Ross','Painter Street','Miami')
    SELECT * from mytablespace.test1

Then you can shutdown the second node (the one that is Leader for the 'mytablespace' tablespace), monitor from the web interface (or from the systemtables) the failover status and try to read the data from the replica:

    SELECT * FROM SYSTABLESPACEREPLICASTATE
    SELECT * from mytablespace.test1

Lastly, if you restart the second node you will see that it will become a "follower" for the 'mytablespace' tablespace

Note that, if you want to test a fully replicated environment, you need to provide an external ZooKeeper cluster (the zookeeper start script embedded in HerdDB supports only single server ensemble).