You are here

Getting Started: Running a Database

Error message

Note: This blog was published over a year ago. Content may be out of date.

In a previous entry I talked about how installing the software is a provisioning step that gets you ready to work with NuoDB. Great, but what you probably want to do is actually run a database.

If you login to the web console (you should .. it’s cool) you’ll see a big “Start Database” button. Click this, walk through a few steps and you’ve got a database running that is expandable, secure and ready for use. If you want to understand a little more about what you just did, keep reading.

A NuoDB database is a collection of processes running the same executable in one of two modes. One of these modes we call a Transaction Engine. It’s what SQL clients connect to, is completely in-memory and acts as an on-demand cache. The TEs understand and enforce the A, C and I in ACID.  On its own, a single TE is a relational database limited to what it can fit into memory.

The other mode is called a Storage Manager, and this provides durability. An SM doesn’t talk SQL or any other application-specific language. What it does is make sure that committed transactions result in durable, consistent state in a local archive and act as a backing store when the TE caches can’t hold all the data. Each SM in a database maintains a complete, independent archive of your data.

Taken together, TEs and SMs provide the behavior of a full, relational database. If you need more transactional throughput add another TE. If you want more redundant copies of your data add an SM. If you want higher availability add both types on separate hosts. To get started, however, all you really need is a single TE and a single SM. If you used the Web Console from a local install, or ran the quick-start example then this is probably what you’ve got running.

Let’s say you wanted to automate starting this database. Later this spring we’ll be rolling out additional tools & scripting interfaces. In the GA product you use the NuoDB Manager to automate database management. This can be run interactively, can take piped input or a single file that contains a string of commands. Here’s an example file that starts a durable database called tea:

# define which host in the domain should run your processes
set property host value

# start the Storage Manager first to maintain durability ... give the
# database the name "tea"
start process sm database tea archive /tmp/tea-archive initialize true

# start the Transaction Engine with an initial DBA account
start process te options '--dba-user dba --dba-password oolong'

You can capture that text to a file and run NuoDB Manager with the –file option, or you can run interactively and type each command as it appears here. You’ll need to change “dbhost” to the name or address of a host where you installed NuoDB. For instance, assume you installed the software on your local machine. Then you’d change that value to “localhost” and run the command as:

java -jar jar/nuodbmanager.jar --broker localhost --password bird --file FILENAME

There are a couple of things to note here. First, the archive directory in this example is under /tmp. Obviously you don’t want to put a durable database there :). In a typical UNIX installation you’d put this under /var (or maybe /home to get started). Anywhere that isn’t transient is a good choice.

Second, when the SM is started you’re saying “initialize true”. All that means is that you’re pointing to a directory that’s empty, or that doesn’t exist. You’re telling the SM to start up clean and synchronize with the running database (or, in this case, create a new database that doesn’t exist yet). If there’s already a database stored there then the SM will complain and fail to start, to protect accidental corruption.

Finally, note the flags being passed to the TE. The first time you start a Transaction Engine you need to specify an initial DBA account. This is the root user for SQL access to your database. You do this once per-database and then you never need to do it again. With the database running you can now connect via NuoSQL, a JDBC client or any of our layer drivers using the account “dba” and the password “oolong”.

At this point you can use NuoDB Manager to extend the database (add TEs and/or SMs), monitor it as it runs and shutdown processes when you no longer need them. If you run NuoDB Console you can do the same things, and see live statistics graphs. Check it out, and let use know what you think!

Add new comment