You are here

Scale Out with the New NuoDB Community Edition Release

Watch "Getting Started with NuoDB" for a demo on how to install the lastest NuoDB Community Edition!

We’re taking a break from our “What’s new in NuoDB 2.6” series to announce the latest exciting news - a new version of NuoDB Community Edition is now available!

For those of you who aren’t familiar with it, NuoDB Community Edition is our totally free, developer version of the NuoDB product. It’s for those looking to research, deploy a database with a small project, or simply get started developing with our technology.

One of the big advantages of using NuoDB is its ability to scale-out.  However, previous versions of NuoDB Community Edition didn’t allow you to do this. Deployment was limited to one Transaction Engine (TE) and one Storage Manager (SM) process on a single host.  

For those of you who could use a refresher, NuoDB has a peer-to-peer, two-layer architecture which includes an in-memory layer of TEs and a storage layer of SMs. The in-memory layer allows the application to naturally build up its own caches of frequently accessed data and the storage layer provides ACID-guarantees and data persistence. Each layer has the ability to elastically scale out (and back), simply by adding and removing TEs and SMs.

We decided to give NuoDB Community Edition a boost by increasing the number of TEs and hosts you can deploy on. You can now scale out your in-memory transaction layer up to three TEs and deploy NuoDB as a distributed database across multiple hosts. This allows you to achieve improved operational workload throughput, fault tolerance, and continuous availability.

We’re really excited for you to get your hands on this new release and try out it! In fact, today, we’ll walk through a straightforward tutorial that will get you up and running with NuoDB Community Edition and showcases the newest capabilities, including

  1. Install NuoDB Community Edition on RHEL
  2. Create a NuoDB database
  3. Populate your database with hockey data
  4. Explore your database using SQL commands and System schema tables
  5. Connect a simple Java client and discover how NuoDB elastically scales out and back in

Let's get started!

Step 1: Install NuoDB Community Edition

Our example specifically shows how to deploy NuoDB in a RHEL environment, but you can also try this out in your Windows environment using NuoDB Documentation as a supplemental guide. You can download NuoDB Community Edition here


Confirm that you are running Java JRE 1.8.

This examples requires you to be running Java JRE 1.8, available for download from Oracle’s website.

Disable Transparent Huge Pages (THP)

Transparent Huge Pages (THP) is a Linux feature that reduces overhead when using large amounts of memory. However, THP causes a memory management problem for several database technologies, including NuoDB, and therefore must be disabled.

To determine if transparent huge pages is enabled, run the following command:

$ cat /sys/kernel/mm/transparent_hugepage/enabled

If the result is [always] madvise never then you will need to disable THP. You can disable it for this now, until the system is restarted with the following commands or:

$ echo madvise > /sys/kernel/mm/transparent_hugepage/enabled
$ echo madvise > /sys/kernel/mm/transparent_hugepage/defrag

You can also permanently disable THP by editing the kernel bootloader and system startup scripts.


Download and install NuoDB Community Edition

Visit the Download page on to download NuoDB Community Edition. After installation, NuoDB will be located in your /opt folder.

Set up your domain password

A NuoDB Domain is a collection of machines or cloud instances that are managed by a Domain administrator and have been provisioned to work together to support one or more NuoDB databases. Each database can run on one or more hosts in the Domain.

The Domain administrator uses Domain credentials (name and password) to gain access and manage the Domain. These are separate from SQL credentials within a provisioned SQL database.

Before you run NuoDB, you must specify the default Domain administrator account password. Do this by editing the file, located in the nuodb/etc folder:

$ vi /opt/nuodb/etc/

Uncomment the line containing the domainPassword property and set the default password. For this example, we’ll use “bird”.

Domain credentials include the name and password of a Domain administrator account. These credentials are not related to SQL credentials within a provisioned SQL database and only apply to domain management.

Set up your environment


To run nuodb commands make sure the nuodb bin directory in your path by executing the following commands.

export NUODB_HOME=/opt/nuodb

Start NuoDB services

With NuoDB Community Edition, you can scale out by dynamically provisioning additional in-memory capacity or availability. This is accomplished by running services across virtual, physical, or cloud hosts that enable resources to be pooled and managed collectively.  You can configure NuoDB to meet various levels of throughput, response times, and durability requirements.

In our example, we are running everything on a single host, so we only need to start a single broker. However, if we were to run NuoDB on more than one virtual or physical host, then we’d need to run one broker per host and set up a peer network so they can communicate with each other. Learn more about peering hosts by reading the NuoDB Documentation.

To start NuoDB services:

$ sudo service nuoagent start

You can also configure your system to automatically start NuoDB services.

Check for errors and validate your installation

At this point, you should be ready to start using NuoDB! But, before we do that, feel free to review log files for errors, located in:


If you find any errors consult the documentation to figure out how to fix them.

Step 2: Create a NuoDB database


First, you need to create a directory for your database and make sure nuodb has permission to read and write to that directory. For this example, we will create a directory for our database called:



NuoDB Manager is the Command Line tool you can use to monitor, analyze, and manage your domain and databases.  We’ll be using this tool to create a new database and then scale that database by adding and removing TEs.

Start the NuoDB Manager, specifying the broker and password defined in your file:

$ nuodbmgr --broker localhost --password bird


At minimum, a NuoDB database requires two processes to be running - one TE and one SM.  In this example, we’ll manually create a database by first establishing a storage process (SM), and then adding a transaction engine process (TE).  You will see that the NuoDB Manager also uses the term “node” to describe TE and SM processes.

Start a Storage Manager Process

Creating a new SM process is an important decision because you will be choosing a host that will store your data. If you stop and start an SM, you typically will want to restart it on the same host every time, so it can use the existing archive.  

Making sure you’re in the NuoDB Manager, start your SM process by specifying:

  • What process to start: An SM archive process
  • Where you want to place it: /tmp/databases
  • Which host the process will run on: localhost
  • What you want to call the database: testdb
  • And, since you are creating a new SM in an empty location, initialize a new archive: true
nuodb [domain] > start process sm archive /tmp/databases host localhost database testdb initialize true

Don’t specify any options as we’ll just go with the default ones for now.  After this, NuoDB Manager will indicate that the SM process is up and running.


Start a Transaction Engine process

The decision of where to start a Transaction Engine is typically an easier one to make. TEs are transitory in nature and they store nothing on disk. As the client application reads and writes to NuoDB, the TE will populate with data, ensuring that actively accessed data are held in-memory, close to the application.

To start a TE process, specify:

  • What you want to start: A TE process
  • Which host the process will run on: localhost
  • In which database: testdb
nuodb [domain] > start process te host localhost database testdb

As part of this initial database set-up, we need to assign a username and password. In this example, we’ll use dba for both by entering:

Process command-line options (optional): --dba-user dba --dba-password dba

After execution of this command, NuoDB Manager will indicate that the TE node is up and running.


Confirm your domain is running both processes

When you check your domain, you should see both processes up and running:

nuodb [domain] > show domain summary


Congratulations! You’ve created your first NuoDB database. Now it’s time to add in some data using the NuoDB SQL tool. Exit out of the NuoDB Manager and return to the RHEL command line.


Step 3: Populate your database with hockey data

NuoDB ships with a sample database, which contains hockey-related data.  It’s located in opt/nuodb/samples/quickstart/sql/ and we’re going to use the included SQL files to populate our new database with the hockey data.


/nuosql testdb --user dba --password dba
< /opt/nuodb/samples/quickstart/sql/create-db.sql 


Load the additional hockey data

Enter the following commands to load up the remaining hockey data.

/nuosql testdb --user dba --password dba
< /opt/nuodb/samples/quickstart/sql/Players.sql
/nuosql testdb --user dba --password dba
< /opt/nuodb/samples/quickstart/sql/Scoring.sql
/nuosql testdb --user dba --password dba
< /opt/nuodb/samples/quickstart/sql/Teams.sql

Step 4: Explore your database using SQL commands and the System tables

Beyond providing ACID compliance and elastic scale-out, NuoDB is also easy for developers familiar with SQL databases to work with. NuoDB supports a rich and complete set of SQL functionality, which includes the full ANSI SQL standard as well as additional procedural extensions. It also provides a typical SQL database permission model, giving you control over who or which roles are allowed to perform actions on a schema, table, view, or procedure.

Let’s try a few basic SQL commands to get a sense of what’s in our database.


NuoDB includes NuoDB SQL, a command line tool to explore a database, execute SQL statements, run scripts, access database metadata information, and perform DBA functions. Read more about it by consulting the NuoDB Documentation.

Enter the NuoDB SQL tool by specifying the database you are accessing, your username, and password:

/nuosql testdb --user dba --password dba

Once you’re in NuoDB SQL, you can get help at any point in time by simply using the help command.



By definition, NuoDB always includes two schemas - user and system. The system schema is a read-only schema whereas the user schema can hold tables and data. You can also create additional schema as needed.

Use the show schemas command to take a look at what schemas our database includes:


Where is our hockey data? If you don’t create and specify a new schema for your data, NuoDB will automatically enter data into the user schema by default.

Let’s check by entering the user schema and showing the tables in that schema.


We can also look at the data in a specific table:


Let’s try something a bit more complex.  This query lists all the Goalies who played  their first NHL game with the league in 2011:

SELECT p.firstname,p.lastname,p.firstnhl,p.lastnhl,s.teamid,s.stint,gamesplayed FROM players p LEFT OUTER JOIN scoring s ON p.playerid = s.playerid AND p.firstnhl = s.year AND s.position = 'G' WHERE p.firstnhl = 2011 AND s.gamesplayed IS NOT NULL ORDER BY LASTNAME,FIRSTNAME,TEAMID;



We’ve been using the NuoDB SQL client to connect to our database. Let’s learn how to get more information about these transaction and how they are occurring. To do this, we can use SQL commands to query the tables found in the System schema. Here are some examples:

This command queries the table for name and position, and then adds the id of the TE that we ran the query on using the built-in getnodeid() function.

SQL> select name, position, getnodeid() as te from limit 3;

Here’s a command which presents information about all current connections to the database.


You can also show information about each of the TE and SM processes in the database. Each row in the SYSTEM.NODES table represents one process.


Step 5: Connect a simple Java Client and discover how NuoDB elastically scales out and back in

Now that we have a populated NuoDB database, we want to see how an application interacts with the database, and how that changes when we add TEs. First, we need to build and run the application.

Download and compile GettingStarted

We’ll be using this simple Java application called, available in the nuodb-samples Github repository.

The program runs a SQL query in a loop, in multiple threads. Each thread will make its own connection to NuoDB.

Create a new folder in your /tmp director for the repository, then download and navigate to where the file is located.

git clone
cd nuodb-samples/GettingStarted

Update the permissions and run the build script that compiles the program.

chmod u+x *.sh

Run GettingStarted and observe its connections to the TE

Run the program using the run script:


When you run the program, it will report out which TE within NuoDB it connected to in order to execute the SQL command. You can see that when NuoDB consists of one SM and one TE, it will always connect to the single TE (called TE 2).

This is exactly how previous versions of NuoDB Community Edition, limited to a single TE and a single SM, operated. Users could enjoy learning how to use NuoDB and typical database functionality but could not experience the benefits of scale out.


Run the program while scaling out to three TEs and then scaling back in

Let’s see what happens when we try out the new capabilities this NuoDB release offers and scale out our TEs to three!

Go back into the NuoDB Manager tool to add two more TEs. We’ve already specified a username and password previously and do not need to specify any additional options. After doing so, your domain should show one SM and three TEs running in your database:


Exit out of the NuoDB Manager and run the program again. This time, we see that NuoDB distributes SQL command execution evenly among all TEs (TE 2, 3, and 4), spreading the load using a “round robin”  approach.


With this scaled out deployment, the processing load is evenly spread across all available Transaction Engines.

Kill one of the TEs to observe how the application continues to run without interruption

With NuoDB, you can scale out and scale back your processes with no interruption to the application. Let’s try it now.

Run the application directly from the command line. Set the time option to run the application continuously for 30 seconds.

./ -time 30


While the program is running, use another terminal window to shut down a TE process essentially scaling-in our NuoDB deployment.  In this example, we shut down the TE on node 3.

> shutdown process

To shutdown a TE process, specify:

  • The host the process is running on: localhost.localdomain
  • The process ID: for example 389 (find the pid from the “show domain summary” command).

By default, NuoDB will perform a graceful shutdown of the process.


Once the process is shut down, you can go back to the terminal running the program and check to see how it handled the loss of TE 3. NuoDB will send out a transient exception when the client thread (task) tries to communicate with its assigned TE - the one that’s now shut down. However, once the client process retries the connection, NuoDB simply connects the client thread to one of the other, still-running, TEs. Notice also that the client threads that were not connected to the TE that we shut down continued processing with no loss of service.


You can see that once the affected client threads have reconnected to a running TE, all transactions continue to be completed without interruption.


With traditional monolithic databases (Oracle, SQLServer, MySQL, etc), clients typically have to treat connection errors as fatal. However, with NuoDB, many of these errors are transient instead and the transaction can be retried. As long as there is a TE with availability in the NuoDB database, then the retry on a new connection will subsequently be successful.

In this example, we’ve deployed all processes on a single machine. However, if we had a more demanding application than our simple program, running all processes on a single machine would limit performance in terms of workload throughput, processing power, and storage capacity. When NuoDB Community Edition is deployed across multiple hosts (one for each engine), application performance can improve dramatically.

Want an example of performance gains when deploying NuoDB Community Edition on multiple hosts?  We’ll be teaching you how to try out this capability in an upcoming TechBlog!  

Don’t miss out!  Follow us on Twitter at @NuoDB and sign up for the TechBlog RSS feed!


christina-wongAs Director of Product Marketing, Christina Wong is responsible for driving and defining product marketing in support of overall go-to-market strategy for NuoDB. Her 10+ years of marketing, sales, and engineering experience spans a broad range of high-tech industries.

Follow Christina on Twitter at @tehWong


Thank you for an excellent Getting Started guide! I ran the whole lot on my Ubuntu 18.10 system without a hitch

Cheers, John

Glad to hear it! If you haven't already, we recommend enabling our Insights functionality to understand the performance and overall health of your NuoDB database environment. Please reach out if you have any questions along the way.

Add new comment

Try it now!

Monitor NuoDB Performance with NuoDB Insights

insights promotion

Enable NuoDB Insights to access a dashboard of database and systems metrics to help you optimize your database environment.

Learn more about NuoDB Insights