TAR File Install

Installation and Configuration

The TAR package is useful if you do not have permissions to create system directories or run systemctl or service commands on the system you plan to install it on. The installation steps are outlined here:

  1. Download the NuoDB TAR package file.

  2. Move the file to the directory in which you wish to install NuoDB.

  3. Unpack the file and cd to the resultant directory as follows:

In this example, we are installing NuoDB version 4.2-1 into the /home/pkgs directory, which should already exist and allow writing. Of course you may use any other directory you like, such as $HOME/pkgs etc.

cd /home/pkgs
tar xzf ~/Downloads/nuodb-4.2.0.1.linux.x86_64.tar.gz
cd nuodb-4.2.0.1.linux.x86_64

Whichever directory you choose, make sure that you have read and write permissions to the directory. All commands which follow assume the current working directory pwd is the base /home/pkgs/nuodb-4.2.0.1.linux.x86_64 directory.

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=$(pwd)
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:

./etc/nuoadmin tls disable

Start the NuoDB Admin Service

Start the NuoDB Admin service, using the nuoadmin script:

./etc/nuoadmin start

$NUODB_HOME/var/log/nuoadmin.log is the persistent log file for the nuoadmin process. The above command should return a message that NuoDB is starting. If not, check the log file for error messages indicating the possible cause.

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. In this example, localhost has been set to the host machine name of host1 in the nuoadmin.conf file. 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 a 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. In this example the database will be created in a sub-directory located in the $NUODB_HOME product distribution directory. You may wish to locate the sample database in a different location to separate the NuoDB product distribution files and the database files. Regardless of your choice, ensure you have read and write permissions to the directory you choose in order to run the nuocmd create archive command.

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

In the above example, we’re using the pre-created $NUODB_HOME/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=/home/pkgs/nuodb.4.2.0.1.linux.x86_64/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 : /home/pkgs/nuodb.4.2.0.1.linux.x86_64/var/opt/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 used to start it initially:

./etc/nuoadmin start

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: