Server Setup & Configuration

Starting a MonetDB database server is as simple as starting the daemon program monetdbd. At the time of this writing, 'monetdbd' is only available on UNIX-like platforms. The MonetDB daemon program encapsulates an arbitrary number of database servers and takes care of their configuration. The general concept of the MonetDB daemon program is that it builds upon a given directory, often referred to as the dbfarm. There can be at most one instance of monetdbd monitoring a dbfarm, but multiple monetdbd processes can be running on the same system.

The next (optional) step is to create a .monetdb configuration file with information to ease using the Monetdb client interface, called mclient.

shell> cat ~/.monetdb
language=<"sql" or "mal">

In the simple case, monetdbd is started by the system through some init script, and databases are created by the local DBA, and assigned to users. A more flexible approach for users, however, is the case where a user runs monetdbd itself. Because a dbfarm can be anywhere in the filesystem, and needs nothing more than just being an ordinary directory, a user can use monetdbd to initialise his/her own dbfarm in an accessible place. For example:

% monetdbd create ~/my-dbfarm
% monetdbd get all ~/my-dbfarm
property        value
dbfarm          /Users/fabian/my-dbfarm
status          no monetdbd is serving this dbfarm
mserver         unknown (monetdbd not running)
logfile         merovingian.log
sockdir         /tmp
port            50000
exittimeout     60
forward         proxy
discovery       true
discoveryttl    600
control         no
passphrase      <unknown>
mapisock        /tmp/.s.monetdb.50000
controlsock     /tmp/.s.merovingian.50000

After the creation of the personal dbfarm directory, the get command can be used to inspect the dbfarm-wide settings of the newly created environment. Note that the above output differs per system, per user and per dbfarm. Important setting is the port to use to open up services for clients. In particular for a user installation, these often may conflict with another running monetdbd, hence it is wise to change these to a private port in situations where such conflicts may arise:

% monetdbd set port=54321 ~/my-dbfarm
% monetdbd get all ~/my-dbfarm
property         value
dbfarm           /Users/fabian/my-dbfarm
status           no monetdbd is serving this dbfarm
mserver          unknown (monetdbd not running)
logfile          merovingian.log
sockdir          /tmp
port             54321
exittimeout      60
forward          proxy
discovery        true
discoveryttl     600
control          no
passphrase       <unknown>
mapisock         /tmp/.s.monetdb.54321
controlsock      /tmp/.s.merovingian.54321

Note that control defaults to "no". For remote control connections, control has to be set to "yes", and a passphrase has to be set as well. When set, it will show as a hash in get's output.

When the settings look ok, the next step is to simply start monetdbd:

% monetdbd start ~/my-dbfarm

If the above command returned without any message, the monetdbd process was successfully started. The logfile (default merovingian.log) should show that the daemon has started, bound some ports, and discovered itself.

From this part on, monetdbd can be given commands through the monetdb command (without the trailing 'd'). The monetdb client utility knows commands much like monetdbd, but it is much more focussed towards giving information about what is going on inside monetdbd. The monetdb client utility is the main tool to use to manage the dbfarm.

The dbfarm we created is empty, as such there are no databases inside it. With monetdb we can create a new database:

% monetdb create my-first-db
created database in maintenance mode: my-first-db

This simple command created the necessary bits inside the dbfarm for a database called my-first-db. It is created in maintenance mode, since otherwise anyone could access it before it is properly setup. If the command gives an access-denied error, most probably another monetdbd is running on the system. In that case try adding -p54321(the port) as arguments to monetdb in order to tell it which monetdbd to contact as in the status example. In the status view of monetdb the newly created database will show up as a locked database:

% monetdb -p54321 status
name state uptime health
my-first-db locked

Albeit the database is locked, it can be started, such that the monetdb superuser can access the database:

% monetdb start my-first-db
starting database 'my-first-db'... done

% monetdb status
    name        state     uptime       health
my-first-db     locked           18s  100%,  0s

The database remains locked, but the uptime field indicates the database is actually running. If setting up the database is ready, the database can be made available for other users (if any, see MonetDB SQL tutorial) to connect to it using the release command:

% monetdb release my-first-db
taken database out of maintenance mode: my-first-db

% monetdb status
     name        state     uptime       health
my-first-db     running       2m 48s  100%,  0s

The next step is to make a connection to the database using mclient which requires the -d argument to specify which database to connect to. It will ask for username and password when none given or provided via a '.monetdb' file. The default username/password is monetdb/monetdb:

% mclient -dmy-first-db
Welcome to mclient, the MonetDB/SQL interactive terminal (Dec2011-SP1)
Database: MonetDB v11.7.7 (Dec2011-SP1), 'mapi:monetdb://'
Type \q to quit, \? for a list of available commands
auto commit mode: on

Like for the monetdb command, if this fails with some database does not exist error, try giving the port (not the controlport!) to mclient such that it finds the correct monetdbd, e.g.:

% mclient -p54321 -dmy-first-db

It may be necessary to stop individual databases, or even make them unavailable. The monetdb commands stopand lockcan perform these tasks. To completely stop the monetdbd daemon process for a dbfarm, stop it using the stop command of monetdbd:

% monetdbd stop ~/my-dbfarm

This should stop the monetdbd and all the databases that are started inside it. To verify that monetdbd has indeed stopped, review the end of the merovingian.log file. It should report all databases being shut down, and the daemon shutting down.