About this book

In modern software applications, often there is the necessity to manage very big amounts of unstructured data with varying schema. In this scenario, instead of relational databases, we can use OrientDB, an open source NoSQL DBMS written in Java. Inspite ofDespite being a document-based database, the relationships are managed with direct connections between records. It supports schema-less, schema-full, and schema-mixed modes.

Getting Started with OrientDB will be your handy, quick reference guide, for all document-graph DBMS functionality. Administrative tasks, deployment, designing a database, different ways of querying and consuming data - all that you need to know about OrientDB is presented keeping with practical usage in mind. You will be able to install, setup, deploy, and configure databases with OrientDB for applications.

Getting Started with OrientDB will allow you to use its OreintDB’s main functionality immediately. The book will guide you through the discovery of one of the most powerful NoSQL databases available today. It will then take you through downloading and installing OrientDB, cluster deployment, programming, discovering OrientDB’s potential, and its features.

The book covers useful administrative topics such as import/export, automatic backups, and configuration tips. Furthermore, design concepts like user management, document databases, graph databases, and dictionaries are covered. Finally, concepts and programming examples are shown in Java.

Publication date:
August 2013
Publisher
Packt
Pages
138
ISBN
9781782169956

 

Chapter 1. Installing OrientDB

There are several editions of OrientDB Server, each of them meets some criteria, and you have to choose which one you need. Keep in mind, however, that the data files are compatible through the server versions, so you can switch from one version to another anytime.

The three available versions are:

  • OrientDB Standard Edition

  • OrientDB GraphEd Edition

  • OrientDB Enterprise Edition

There was another version which was focused on the key/value pair's management. It was called OrientKV Server but now it has deprecated and is no longer supported. In fact, the other versions of OrientDB have the capability to manage the key/value indexes as well, so if you need to manage large associative arrays or very big hash tables, you can use them to do that.

 

Standard Edition


The Standard Edition is the "main" edition of OrientDB; the other ones are extensions of the Standard Edition and add some specific capabilities to it.

The Standard Edition is shipped with a rich set of out of the box features; all of them are immediately available after the server installation.

Some of these features are:

  • Graph database support

  • Document database support

  • Object database support

  • Dictionary indexes support

  • A SQL-like query language

  • Transaction support

  • Hooks (a sort of trigger, but at the system level rather than class level)

  • Custom SQL function (to write your own functions in Java to expand the SQL parser)

  • Stored procedures

  • Plugin support to add features to the server's core

  • REST interface

  • Java API library

  • Clustering

  • Command-line administration console

  • Web-based administration console (OrientDB Studio)

 

Graphed Edition


The Graphed Edition adds the TinkerPop Blueprints interface and the Gremlin query language to the Standard Edition.

Note that the Graphed Edition does not add the graph capabilities to OrientDB.

Relations through edges and other graph features are first-class capabilities in OrientDB, and are present in the Standard Edition too.

The Graphed Edition provides a layer on top of the OrientDB databases, so you can manage them through the Blueprints interface and provide the support to use the Gremlin language, if you want to use this de-facto query language for the graph databases instead of the OrientDB SQL-like language.

 

Key/Value Edition


The OrientDB Key Value server has not been supported since April 2011, and its source code was removed from the public repository in January 2013.

Its functionalities are available in the other versions.

In fact, each new OrientDB database has a special structure called Dictionary. The scope of the dictionary is to provide key/value management features to implement, for example, lookup tables, caches, and logs. You can also define as many dictionaries as you like, as per you needs.

 

Enterprise Edition


The Enterprise Edition will be released in 2013 and will add enterprise-class features to the Standard Edition, like an advanced monitoring cockpit, a collection of metrics related to the servers and clusters, Business Intelligence capabilities, and professional support.

 

Installing from the latest stable release


To install OrientDB you have to download its latest stable release, and you must have a Java virtual machine (Java SE 6 or above) installed on your target system.

Since the JVM is the only requirement to run an OrientDB server, this means it can be installed on any system supported by the Java platform, even the Raspberry Pi!

You can find the binary packages on the OrientDB official site: www.orientdb.org.

Currently, the 1.3.0 version is available and you can find two packages under the download section:

  • orientdb-1.3.0.tar.gz which is a standard edition

  • orientdb-graphed-1.3.0.tar.gzwhich is a graph edition

Installing the Standard Edition

Download the orientdb-1.3.0.tar.gz file from the OrientDB site, and extract its content to a directory on your system.

Now you should have a directory tree similar to the structure shown as follows:

/orientdb-1.3.0
/benchmarks
/bin
/config
/databases
/lib
/log
/www
 history.txt
 license.txt
 readme.txt

The following is an explanation for the preceding directory tree structure:

  • benchmarks: scripts to perform several benchmark tests

  • bin: scripts to run and to stop the server and the command-line console

  • config: XML configuration files

  • database: default path for the database files

  • lib: the JAR files

  • log: default path for the server logfiles

  • www: the OrientDB Studio web application

  • history.txt: the change logfile

  • license.txt: the Apache 2 license

  • readme.txt: instruction to build OrientDB from the source code

To run the server, just go into the bin directory, and launch the server.bat (on Windows OS) or server.sh (on Unix/Linux systems).

If you are using a Unix-based system, you may have to set the execution permission to the script files:

chmod +x ./bin/*.sh

If you plan to run OrientDB outside the bin directory, you have to set the bin path in the PATH environment variable, furthermore you have to set the ORIENTDB_HOME environment variable to the path's directory in which you extracted the tar.gz package.

The ORIENTDB_HOME variable is used by the scripts to guess the OrientDB position.

Now you can launch the server.

In the bin directory there are several scripts, for both Windows and Linux:

  • aserver.*: just ignore them, they are experiments for the next releases

  • console.*: run the command-line console

  • dserver.*: run the server in distributed mode

  • orientdb.sh: script to run/stop OrientDB as a daemon on Unix-like systems

  • server.*: run the server

  • shutdown.*: shutdown the server in a clean way (that is, do not kill it)

Note

Type server.bat (on Windows) or ./server.sh (on Unix/Linux).

You should have an output similar to this:

2013-04-19 09:20:21:600 INFO OrientDB Server v1.3.0 (build @[email protected]) is starting up... [OServer]
2013-04-19 09:20:22:936 INFO -> Loaded memory database 'temp' [OServer]
2013-04-19 09:20:23:148 INFO Listening binary connections on 0.0.0.0:2424 [OServerNetworkListener]
2013-04-19 09:20:23:151 INFO Listening http connections on 0.0.0.0:2480 [OServerNetworkListener]
2013-04-19 09:20:23:181 INFO Installing GREMLIN language v.2.2.0-SNAPSHOT [OGraphServerHandler]
2013-04-19 09:20:23:195 INFO OrientDB Server v1.3.0 is active. [OServer]

Now you can run the console to connect to the server and try some simple commands.

In another terminal window, go to the bin directory and launch the console script.

Type ? and see all the available commands:

The first command you have to supply is the connect command, to connect to a server:

connect remote:127.0.0.1/demo admin admin

The server replies:

Connecting to database [remote:127.0.0.1/demo] with user 'admin' ...OK
orientdb>

You can try the simple command:

info

Tip

OrientDB is shipped with a demo database, moreover, it starts an in-memory database called temp.

To exit from the console, type:

exit

Now to shutdown the server, go to the bin directory and launch the shutdown script.

Installing the Graphed Edition

The procedure is similar to that used for the Standard Edition.

Go to the download page www.orientdb.org and grab the orientdb-graphed-1.3.0.tar.gz file.

Once you have downloaded the file, unzip it in a convenient directory.

The tree structure is same as that of the Standard Edition. There are some differences in some of them:

  • bin: there are the gremlin.* scripts to run the Gremlin scripts from command line, batches, and shells

  • databases: there is the Tinkerpop demo database instead of the OrientDB one

  • lib: in addition to the OrientDB libraries, there are also the libraries of the Tinkerpop Stack, and other necessary JARs

Again to run the server, just go into the bin directory, and launch the server.bat (on Windows OS) or server.sh (on Unix-like systems).

Remember to set the right execution permission to the script files:

chmod +x ./bin/*.sh

and to set the ORIENTDB_HOME environment variable.

Tip

Check if another instance of OrientDB is running. If so, terminate it to avoid the port binding conflicts.

Once the server is started, take a look at the last two output rows. Here you can see if the Gremlin language support is loaded:

2013-04-19 09:20:23:181 INFO Installing GREMLIN language v.2.2.0-SNAPSHOT [OGraphServerHandler]
2013-04-19 09:20:23:195 INFO OrientDB Server v1.3.0 is active. [OServer]

Now you can run the console tool from another terminal window. Also, in this case, you should see a notice indicating that the Gremlin language support is available.

In other terminal, go to the bin directory and launch the console command:

OrientDB console v.1.3.0 (build 16) www.orientechnologies.com

Type help to display all the commands supported.

Installing extensions for GREMLIN language v.2.2.0-SNAPSHOT
orientdb>

OrientDB Graphed Edition is shipped with the Tinkerpop demo database.

Try to connect to the db:

connect remote:127.0.0.1/tinkerpop admin admin

And then try to execute the info command:

info

To exit from the console type:

exit
 

Compiling from the latest source snapshot


The source code is available through the GitHub platform at the URL http://github.com/nuvolabase/orientdb.

Since the build process will put the generated file in a directory called release, which will be a sibling of the source directory, I suggest you create a directory just for OrientDB. Inside that directory create a new directory to place the downloaded source code.

You can download the latest source code by selecting the master branch and downloading the master.zip file using the ZIP button.

Otherwise, you can clone the GIT repository on your machine using git. Type:

git clone git://github.com/nuvolabase/orientdb.git

To build OrientDB from source code you must have a JDK SE 6 or above, and the Ant Tool version 1.6.5 or above.

You can download Ant from http://ant.apache.org/.

Please note that the ant executable directory must be included in the PATH environment variable.

Once you have downloaded the source code and installed the necessary tool, you can proceed to build OrientDB.

Go into the source code directory and type:

ant clean install

You can also launch the build.bat (or build.sh in Unix-like system), however these scripts call ant.

To build the Graphed Edition too, type:

ant clean installg

At the end of the build process you should have a screen shown as follows:

The generated files are in the release\orientdb-x.y.z-SNAPSHOT and release\orientdb-graphed-x.y.z-SNAPSHOT directories, where x.y.z is the current version under development.

Running the test suite

To run the test suite against a freshly-built OrientDB snapshot, you can type the following command:

ant test

After the test suite has finished (you should have 0 errors), in the database directory of the Standard Edition, you should have some databases created to run the tests, including the demo database.

There are another set of tests that need of Maven to be executed.

So, if you want to execute these tests you must download Maven from http://maven.apache.org/download.cgi

and install it following the instruction provided in the readme.txt file within the installation package.

Once you have Maven on your system, you can type:

mvn clean test
 

Installing as a daemon/service


OrientDB can run as a background process. The setup process depends on the server platform.

Linux systems

OrientDB is shipped with a script that can be used to run OrientDB like a daemon.

It supports the start/stop/status parameters and can be configured to execute OrientDB with a specified user's credentials.

The script is orientdb.sh and is located in the /bin directory of the installation path.

You must open it and change the first lines:

ORIENTDB_DIR="YOUR_ORIENTDB_INSTALLATION_PATH"
ORIENTDB_USER="USER_YOU_WANT_ORIENTDB_RUN_WITH"

Set the installation path and the user as stated, save the script, and deploy like other scripts for the other daemon.

Different Linux distribution uses different ways to manage the start/stop process at the system bootstrap/shutdown.

Windows systems

Since OrientDB is a Java application, it does not offer any native way to run as a Windows service.

However, there are some tools that can be wrapped with any executable so that it can be installed and managed as a Windows service.

The correct procedure to do this is illustrated at the wiki page https://github.com/nuvolabase/orientdb/wiki/Wrapping-As-A-Windows-Service. The steps are as follows:

  1. You must download the Apache Commons Daemon tools for your system. The latest version is available at: http://www.apache.org/dist/commons/daemon/binaries/windows/.

  2. Download and unzip it.

  3. You will find a prunsrv.exe file in the root directory. This is the file for x86/32 bit systems. In the directory amd64 there is a version of the prunsrv.exe file for x86/64 architectures, while the directory ia64 contains a version of the prunsrv.exe file for the Itanium machines.

  4. Let's say you have installed OrientDB in the %ORIENTDB_HOME% directory, you have to create a new directory called %ORIENTDB_HOME%/service.

  5. Copy to this new directory the two .exe files shipped with the Apache Commons Daemon tools: prunmgr.exe and prunsrv.exe, according to the architecture of your machine.

  6. Rename prunsrv.exe to OrientDB.exe, and prunmgr.exe to OrientDBw.exe.

  7. Copy to the same directory the file installService.bat.

  8. In order to execute this script you must locate the jvm.dll file installed on your system. Generally this file is in the %JAVA_HOME%\jre\bin\server directory.

  9. Assuming that Java is installed in the C:\Program Files\Java\jdk1.6.0_37 path, and that OrientDB is installed in the C:\OrientDB\releases\orientdb-1.4.0-SNAPSHOT directory, you must type the following command:

    installService.bat "C:\Program Files\Java\jdk1.6.0_37\jre\bin\server\jvm.dll" C:\OrientDB\releases\orientdb-1.4.0-SNAPSHOT
    
  10. Now you can open the Windows Services Management Console and see OrientDB listed as a service.

 

Summary


In this chapter, we had our first encounter with OrientDB. We have seen the available versions, have learned to build it from the latest available source code, and have run a server instance.

We have also seen how to deploy it as a Windows service.

In the next chapter, we will go into more detail about the OrientDB architecture. We will explore the first basic concepts, such as how the data are organized and stored on filesystem, the security framework, and how to perform administrative tasks using the embedded tools.

About the Author

  • Claudio Tesoriero

    Claudio Tesoriero is an OrientDB Certified Developer and a senior software engineer with twenty years' experience in Information Technology. His first experience was with the Italian Ministry of the Treasury, then he worked for the Bull Group (www.bull.com) and got involved in projects developed for Telecom Italia (www.telecomitalia.it) and in R&D projects developed in collaboration with the Rome Tor Vergata University. He then worked for FutureSpace Spa (www.futurespace.it) and he participated in the implementation of various projects for the government administration. Currently, he is the cofounder of BaasBox, a solution of Backend as a Service based on the Play! Framework and OrientDB.

    Browse publications by this author
Book Title
Access this book, plus 7,500 other titles for FREE
Access now