The first step is to setup a database storage directory in the filesystem, conceptually called a database farm (dbfarm). It is recommended to use the same filesystem for both storage directory and MonetDB software binaries. A database farm can be initialized with the program monetdbd, which is the MonetDB database server daemon. This directory will be the location to an arbitrary number of databases. It is also the location for the daemon configuration file and log file(s).
MonetDB database server daemon is only available for the Unix family of operating systems.
For setup of MonetDB software on Windows OS go to Windows page.
MonetDB software ships with default credentials.
Do not forget to create databases using the password option or to change the default credentials while in maintenance mode.
The program monetdbd is the MonetDB database server daemon. On top of its main purpose of being the daemon, it also used to initialize a database farm directory.
It is strongly advised to check monetdbd manual page for a comprehensive explanation of all available features. Command line manual is also available via man monetdbd.
In the simple case, monetdbd is started by the host system through some init script (potentially systemd), and databases are created by the local database administrator and assigned to system users by adding the users to the system group that runs the database server programs. If systemd is in play and MonetDB software suite via OS package manager, the default system user and group that run the database daemon and servers is monetdb.
To find details about systemd open the manual pages: man systemd, man systemd.service and man systemctl.
Some important sections to read are unit and Environment of systemctl manual.
MonetDB software suite ships a unit file to manage the MonetDB service. This file can be found in MonetDB source repository monetdbd.service.in. Here is a snippet:
[Unit]
Description=MonetDB database server daemon
Documentation=man:monetdbd https://www.monetdb.org/documentation/admin-guide/manpages/monetdbd/
After=network.target
[Service]
Type=forking
User=monetdb
Group=monetdb
UMask=0007
(...)
The default location of the dbfarm for a daemon managed by systemd is /var/monetdb5/dbfarm. To change the location of the dbfarm to be managed by the daemon run:
systemctl edit monetdbd
and add the following content:
[Service]
Environment=DBFARM=/some/other/directory
This command will create an override.conf file whose contents will take precedence over the default unit file provided.
Running systemctl edit monetdbd will open the default editor at the appropriate location for editing.
After adding the content and saving the changes, systemd manager configuration needs to be reloaded. To do this run:
systemctl daemon-reload
Now, restart monetdbd service:
systemctl restart monetdbd
and check monetdbd service status:
systemctl status monetdbd
MonetDB daemon should be operational managing the desired dbfarm.
A more flexible approach for users 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 initialize its own dbfarm in a location allowed by the system for that user.
monetdbd create $HOME/my_dbfarm
As part of dbfarm initialization, the file .merovingian_properties is created in the dbfarm directory. This file records any configuration property changes. It will be empty except for some header comments telling to not edit this file manually. An empty file indicates that the daemon will use all default properties when started. If a property is changed, that change is recorded in this file. To retrieve all the current dbfarm properties use monetdbd get all command. To retrieve a specific dbfarm property use monetdbd get <property_name> command.
monetdbd get all $HOME/my_dbfarm
| property | value |
|---------------------|------------------------------------|
| hostname | server_hostname |
| dbfarm | $HOME/my_dbfarm |
| status | no monetdbd is serving this dbfarm |
| mserver | unknown (monetdbd not running) |
| logfile | $HOME/my_dbfarm/merovingian.log |
| pidfile | $HOME/my_dbfarm/merovingian.pid |
| loglevel | information |
| sockdir | /tmp |
| listenaddr | localhost |
| port | 50000 |
| exittimeout | 60 |
| forward | proxy |
| discovery | no |
| discoveryttl | 600 |
| control | no |
| passphrase | <unset> |
| snapshotdir | <unset> |
| snapshotcompression | .tar.lz4 |
| keepalive | 60 |
| mapisock | /tmp/.s.monetdb.50000 |
| controlsock | /tmp/.s.merovingian.50000 |
For some properties, changing their value will only take effect after a daemon restart.
Check monetdbd manual to see what is the case for each property.
One important dbfarm property is the control property and its default no value. By default, communication with the daemon is done over Unix Domain Sockets. To allow communication with the daemon over network, set control property to yes. It is also mandatory to set the passphrase. When set, it will show as a hash value in the output of monetdbd get passphrase.
Controling the daemon with user other than monetdb require that user to be part of monetdb group.
After adding that user to the group, log out and log back in.
Another important dbfarm property is the port property to be used by the daemon, especially if you intend to run multiple dbfarms in the same host system. To change a dbfarm property use monetdbd set <property_name>=<new_value> command.
monetdbd set port=65432 $HOME/my_dbfarm
There can be at most one instance of monetdbd serving a dbfarm, but multiple monetdbd processes can be running on the same system, each with its own dedicated dbfarm and network socket and port.
To start the daemon on a dbfarm directory use monetdbd start command. If the start command returns without any message, the monetdbd process was successfully started.
monetdbd start $HOME/my_dbfarm
The monetdbd program logs information into a file named merovingian.log by default. It is located in the dbfarm directory.
2026-01-01 10:13:50 MSG merovingian[525218]: Merovingian 11.55.5 (hg id: 691e862e16ce) starting
2026-01-01 10:13:50 MSG merovingian[525218]: monitoring dbfarm $HOME/my_dbfarm
2026-01-01 10:13:50 MSG merovingian[525218]: accepting connections on TCP socket localhost:65432
2026-01-01 10:13:50 MSG merovingian[525218]: accepting connections on UNIX domain socket /tmp/.s.monetdb.65432
2026-01-01 10:13:50 MSG control[525218]: accepting connections on UNIX domain socket /tmp/.s.merovingian.65432
To stop the daemon from serving the database farm use monetdbd stop command. If the stop command returns without any message, the monetdbd process was successfully stopped.
monetdbd stop $HOME/my_dbfarm
With daemon started and serving the dbfarm, databases can now be created. To achieve this use the program monetdb which is the MonetDB database server daemon client.
It is strongly advised to check monetdb manual page for a comprehensive explanation of all available features. Command line manual is also available via man monetdb.
To create a database use monetdb create command. A new directory with the same name of the database is created in the dbfarm directory. Do not edit any of the files manually, otherwise there is a risk of corruption of the database.
Each newly created database has a default user monetdb with a default password monetdb, and it is the default database administrator.
Use the option -p of the create command to override the default password of the monetdb user.
monetdb create -p 'very_strong_password' my_first_db
created database with password for monetdb user: my_first_db
Each newly created database also as its own configuration properties. Before starting the database, these properties can be checked and changed. Commands to retrive or change specific database properties follow the same process of the daemon. To retrieve all properties of a database use monetdb get all command. To retrieve a specific database property use monetdb get <property_name> command.
monetdb get all my_first_db
| name | prop | source | value |
|-------------|------------------|---------|--------------|
| my_first_db | name | - | my_first_db |
| my_first_db | type | default | database |
| my_first_db | shared | default | yes |
| my_first_db | nthreads | default | 20 |
| my_first_db | ncopyintothreads | default | 20 |
| my_first_db | optpipe | default | default_pipe |
| my_first_db | readonly | default | no |
| my_first_db | embedr | default | no |
| my_first_db | embedpy3 | default | no |
| my_first_db | embedc | default | no |
| my_first_db | listenaddr | default | <unset> |
| my_first_db | nclients | default | 64 |
| my_first_db | dbextra | default | <unset> |
| my_first_db | memmaxsize | default | <unset> |
| my_first_db | vmmaxsize | default | <unset> |
| my_first_db | raw_strings | default | <unset> |
| my_first_db | loadmodules | default | <unset> |
| my_first_db | idletimeout | default | <unset> |
For some properties, changing their value will only take effect after a database restart.
Check monetdb manual to see what is the case for each property.
After creating a database with the -p option, it is ready to be started and be available to regular users. To start the database user monetdb start command.
monetdb start my_first_db
To check the status of the running database use monetdb status command. The output is divided into four columns, name, state, health, and remarks. The state column contains two characters that identify the state of the database, based on Booting (starting up), Running, Stopped, Crashed and Locked (under maintenance). This is followed by the uptime when running. The health column contains the percentage of successful starts and stops, followed by the average uptime. The remarks column can contain arbitrary information about the database state, but
usually contains the URI the database can be connected to. Check the manual for documentation on the optional flags -l, -c and -s.
monetdb status my_first_db
name state health remarks
my_first_db R 33s 100% 0s mapi:monetdb://server_hostname:65432/my_first_db
Databases can be placed in maintenance mode. To do so, use monetdb lock command. A database under maintenance can only be connected to by an administrator user (by default the monetdb user).
monetdb lock my_first_db
To take a database back from maintenance mode use the command monetdb release. A released database is available again for normal use by any client, and is started on demand.
monetdb release my_first_db
To stop a database use the command monetdb stop. This will first attempt to stop the database, waiting for exittimeout seconds and if that fails, kill the database.
monetdb stop my_first_db
To kill a database use the command monetdb kill. The kill command immediately terminates the database by sending the SIGKILL signal. Any data that hasn't been committed will be lost. This command should only be used as last resort for a database that doesn't respond any more.
monetdb kill my_first_db
To destroy a database use the command monetdb destroy. It removes the given database, including all its data and logfiles. Once destroy has completed, all data is lost. Be careful when using this command.
monetdb destroy my_first_db
Databases can also be created without the -p option. After creating a database without this option, it is not immediately available for general use. The database is placed in maintenance mode and gives the database administrator the opportunity to start the database, login as monetdb user and change the default password with a SQL query.
Do not forget to change default credentials while in maintenance mode.
To interact with database servers, the command line interface mclient is available. Before mclient starts parsing command line options, it reads a configuration file. If the environment variable DOTMONETDBFILE is set and not empty, it reads the file pointed to by that variable. If set but empty, no configuration file is read. If unset, mclient first looks for a file .monetdb in the current working directory, and if that doesn't exist, it looks for a file monetdb in the XDG configuration directory ($XDG_CONFIG_HOME which defaults to $HOME/.config if not set), and finally for a file .monetdb in the current user's home directory. This file can contain defaults for the flags user, password, language, database, save_history, format, host, port, and width. To disable reading the .monetdb file, set the variable DOTMONETDBFILE to the empty string in the environment.
It is strongly advised to check mclient manual page for a comprehensive explanation of all available features. Command line manual is also available via man mclient.
mclient -d my_first_db -u monetdb
password: very_strong_password
Welcome to mclient, the MonetDB/SQL interactive terminal (unreleased)
Database: MonetDB 11.55.5 (hg id: 691e862e16ce), 'mapi:monetdb://server_hostname:65432/my_first_db'
FOLLOW US on https://github.com/MonetDB/MonetDB
Type \q to quit, \? for a list of available commands
auto commit mode: on
If the daemon is serving a dbfarm but databases under that dbfarm are not running, attempting to connect to a database will automatically start that database, if not under maintenance.
Stopping the daemon from serving the dbfarm will also stop all databases that are running in that farm. To verify that
monetdbdprocess has indeed stopped, review the end of themerovingian.logfile. It should report all databases being shut down, and the daemon shutting down.
A optional flag
-ais available formonetdbcommandsstart,stop,kill,lockandrelease, which applies the command to all databases being served by the daemon.