RPM Package Install

Install and Configure NuoDB

Download the NuoDB installation package and install it using the rpm command:

sudo rpm --install nuodb-n.n.n.n.x86_64.rpm

For full NuoDB installation details, see Installing NuoDB.

Add the NuoDB bin sub-directory to your $PATH environment variable to save typing the full path when running NuoDB commands, like nuocmd or nuosql.

export NUODB_HOME=/opt/nuodb

export PATH=$PATH:$NUODB_HOME/bin

We’ll disable TLS encryption for this quick-start example. Of course you should avoid running production systems with TLS disabled. To disable TLS run:

$NUODB_HOME/etc/nuoadmin tls disable

Start the NuoDB Admin Service

Start the NuoDB Admin service, nuoadmin.

On newer Linux releases, the command is:

sudo systemctl start nuoadmin

The above command should return a message that NuoDB is starting. If not, check the log file for error messages indicating the possible cause. You can find the log file for the NuoDB Admin Process (AP) in /var/log/nuodb/nuoadmin.log.

When using the package-based install, the NuoDB Admin service will automatically restart on reboot.

The nuocmd command is used to interact with the NuoDB Admin service. For example, the following command shows the NuoDB Admin service named nuoadmin-0 is ACTIVE and the LEADER for the domain, and was started on a host server host1. There is no databases associated with the domain yet.

nuocmd show domain

server version: 6.0-1-fc6a857de9, server license: Limited
server time: 2023-11-20T13:15:28.020, client token: 7dc8fd8bcc6dfd5fcd96dd7414d7a03d94c19779
Servers:
  [nuoadmin-0] host1:48005 [last_ack = 0.85] [member = ADDED] [raft_state = ACTIVE] (LEADER, Leader=nuoadmin-0, log=0/3/3) Connected *
Databases:

Install a Limited Use License

To obtain the license file required to deploy NuoDB with a Limited Use License, contact NuoDB Support. To install the Limited Use License, run:

nuocmd set license --license-file </path/to/nuodb.lic>

For more information, see Obtain and Install a Product License.

Create an Archive

Create a NuoDB archive to store the database data on disk:

nuocmd create archive --db-name hockey --server-id nuoadmin-0 \
  --archive-path /var/opt/nuodb/demo-archives/hockey

In the above example, we’re using the pre-created /var/opt/nuodb/demo-archives directory and calling both the archive and database "hockey" as we’ll be populating it with sample NHL ice hockey team and player statistics later.

The NuoDB Hockey schema contains teams, players, and historical game statistics from past North American NHL (National Hockey League) professional ice hockey games from 1909-2011. Knowledge of the game of ice hockey is not required to follow this example!

The server-id nuoadmin-0 is the name of the NuoDB Admin service we started previously. The database archive will be managed by the Storage Manager (SM). The output of the command should be similar to:

Archive(archive_path=/var/opt/nuodb/demo-archives/hockey,
 db_name=hockey, id=0, server_id=nuoadmin-0, state=PROVISIONED)

To check and confirm the database archive has been created, run:

nuocmd show archives

[0] nuoadmin-0 : /var/opt/nuodb/demo-archives/hockey @ hockey [journal_path = ] [snapshot_archive_path = ] PROVISIONED

Create and Start an Empty Database

Creating a NuoDB database will automatically start a Transaction Engine (TE) and Storage Manager (SM). The TE processes SQL queries and the SM manages reads and writes to the database archive. To create a database hockey run,

nuocmd create database --db-name hockey --dba-user dba \
  --dba-password goalie --te-server-ids nuoadmin-0

In the above example, we’ve named the database "hockey", set up a user "dba" with the password "goalie", and requested a TE to start on server-id nuoadmin-0 which is the name of the NuoDB Admin Process (AP) we started previously. An SM will also be automatically started on server-id nuoadmin-0, which is the server-id associated with the archive we created. The output of the above command should be similar to:

STARTING: StartProcessRequest(archive_id=0, db_name=hockey, engine_type=SM, labels{}, options{}, server_id=nuoadmin-0)
STARTING: StartProcessRequest(db_name=hockey, engine_type=TE, labels{}, options{}, server_id=nuoadmin-0)

Re-running nuocmd show domain will now show the "hockey" database is associated with the domain, and is in state = RUNNING, with an SM and a TE process, both in state MONITORED:RUNNING.

nuocmd show domain

server version: 6.0-1-fc6a857de9, server license: Enterprise
server time: 2023-11-20T14:05:22.124, client token: 7dc8fd8bcc6dfd5fcd96dd7414d7a03d94c19779
Servers:
  [nuoadmin-0] host1:48005 [last_ack = 0.85] [member = ADDED] [raft_state = ACTIVE] (LEADER, Leader=nuoadmin-0, log=0/15/15) Connected *
Databases:
  hockey [state = RUNNING]
    [SM] host1:48006 [start_id = 0] [server_id = nuoadmin-0] [pid = 39] [node_id = 1] [last_ack =  9.30] MONITORED:RUNNING
    [TE] host1:48006 [start_id = 1] [server_id = nuoadmin-0] [pid = 40] [node_id = 2] [last_ack =  7.47] MONITORED:RUNNING

If your nuocmd show domain output indicates your hockey database is not in the RUNNING state you can investigate by running the following command. This will display any errors that may have occurred during the database startup phase.

nuocmd show database --db-name hockey --all-incarnations

Import a Sample Database

Create the sample ice hockey database schema by running the following commands:

for sqlfile in create-db.sql Players.sql Scoring.sql Teams.sql; do
    nuosql hockey --schema hockey --user dba --password goalie \
        < $NUODB_HOME/samples/quickstart/sql/$sqlfile >/dev/null 2>&1;
done

Log into nuosql:

nuosql hockey --user dba --password goalie

At the SQL> prompt type the following commands to connect to the hockey schema and display the tables that belong to the hockey schema.

use hockey;

show tables;

   Tables in schema HOCKEY
       HOCKEY
       PLAYERS
       SCORING
       TEAMS
       VW_PLAYER_STATS is a view

Try out some SQL commands on the hockey database, such as:

select * from TEAMS where TEAMS.YEAR=2011;

Now try a more advanced query such as:

select p.lastName, p.firstName, s.year, s.teamID, s.gamesPlayed
from   players p, scoring s
where  p.birthCountry = 'Slovakia'
and    s.playerID = p.playerID
order by p.lastName;

To exit, type:

quit

To re-invoke nuosql, type:

nuosql hockey --schema hockey --user dba --password goalie

Try out some more NuoDB SQL commands as described in SQL Language, such as the SQL System Information Functions.

Or use a 3rd party utility such as DbVisualizer or SQL Workbench/J to explore the sample ice hockey database. See Using DbVisualizer and Using SQL Workbench/J.

Shutdown

To shutdown the database:

nuocmd shutdown database --db-name hockey

Re-running nuocmd show domain will now show the "hockey" database in the state NOT_RUNNING, with both the SM and TE shutdown, but with the nuoadmin service still running.

To shutdown the NuoDB Admin service:

nuocmd shutdown server --server-id nuoadmin-0

After shutting down the NuoDB Admin service, nuocmd can no longer be used as there’s no NuoDB Admin service to which to connect.

Restart

If the NuoDB Admin service was shutdown, restart it using the same command we used to start it initially:

On newer Linux releases, the command is:

sudo systemctl start nuoadmin

The database archive was not deleted, and therefore is still available. To restart the database and the SM and TE database processes:

nuocmd start database --db-name hockey --te-server-ids nuoadmin-0

To restart an additional TE:

nuocmd start process --db-name hockey --server-id nuoadmin-0 \
  --engine-type TE

The limit is three TEs and one SM when using the NuoDB Limited License.

Running nuocmd show domain shows that each database engine invocation receives a unique start_id. Each start_id is uniquely identifiable and is never reused within a given NuoDB Admin domain, whereas node_id assignments for each database engine invocation are unique per database invocation and reset back to 1 on database restart.

Next Steps

We hope you’ve enjoyed your quick start guide to NuoDB. If you had any questions or comments, please contact NuoDB Support. We’d love to hear from you!

If you wish to run a larger proof-of-concept (POC) using the NuoDB Enterprise Edition (EE), which enables unlimited scale out of the database Storage Managers (SMs) and Transactions Engines (TEs), please contact sales@nuodb.com for an Enterprise Edition license.

Here’s a selection of potential next steps. Those sections involving multiple SMs require an Enterprise Edition license: