mserver5 − the MonetDB server version 5
mserver5 is the current MonetDB server that performs all processing on request of clients for a certain database.
Note that while mserver5 is the process that does the actual work, it is usually more common to start, monitor and connect to the mserver5 process through monetdbd(1).
This man-page describes the options that mserver5 understands. It is intended for people who really need to work with mserver5 itself. In regular cases, the programs monetdbd(1) and monetdb(1) control the many options, and allow to adjust them to appropriate values where sensible. For normal usage, it is preferred to apply any configuration through these programs.
When the build-time configuration did not disable this, a mserver5 process presents the user with a console prompt. On this prompt, MAL commands can be executed. The architecture is setup to handle multiple streams of requests. The first thread started represents the server, which is the console prompt, reading from standard input and writing to standard output.
The server thread started remains in existence until all other threads die. The server is stopped by Ctrl-D on its console, typing quit() or by sending it a termination signal (SIGINT, SIGTERM, SIGQUIT).
mserver5 can be started with options and scripts as arguments. The MAL scripts will be executed directly after startup on the console, which eases e.g. testing of MAL scripts directly, without starting a client.
Path where mserver5 should find a database. Shorthand for option gdk_dbpath. Default value: @localstatedir@/monetdb5/dbfarm/demo.
MAL statement to execute as part of the startup of the server.
Config file to read options from. This file can contain all options as can be set with the --set flag. See CONFIG FILE FORMAT.
Disable the console prompt, do not read commands from standard input. Default: no
Set individual configuration option. For possible options, see PARAMETERSsections.
Print list of options.
Print version and compile configuration.
GDK (Goblin Database Kernel) is the current columnar storage kernel engine of the MonetDB 5 database. It is the component that manages and performs operations on BATs (Binary Association Tables), single columns. The parameters here affect the behaviour of GDK which may nagatively impact performance if set wrongly. The kernel tries to choose the values for optimal performance. Changing these parameters is discouraged.
Memory chunks of size >= gdk_mem_bigsize (in bytes) will be mmaped anonymously. Default: 1<<20 == 1024576 == 1 MiB
Enable or disable the vmtrim thread which tries to unload memory that is not in use. Default: yes
You can enable debug output for specific kernel operations. By default debug is switched off for obvious reasons. The value of gdk_debug is an integer, which value can be (a combination of):
1 = THRDMASK = thread-specific debug output 2 = CHECKMASK = property enforcing on new BATs 4 = MEMMASK = memory allocation 8 = PROPMASK = property checking on all values: tells about wrongly set properties 16 = IOMASK = major IO activity 32 = BATMASK = BAT handling 128 = PARMASK = Thread management 256 = HEADLESSMASK = Warn about BAT heads that are not "headless-ready" 512 = TMMASK = Transaction management 1024 = TEMMASK = Locks and Triggers 4096 = PERFMASK = BBP Performance (?) 8192 = DELTAMASK = Delta debugging (?) 16384 = LOADMASK = Module loading 2097152 = ALGOMASK = show join/select algorithm chosen 4194304 = ESTIMASK = show result size estimations (for join, select) 16777216 = JOINPROPMASK = disable property checking with join & outerjoin (e.g., for performance measurements) 33554432 = DEADBEEFMASK = disable "cleaning" of freed memory in GDKfree() (e.g., for performance measurements) 67108864 = ALLOCMASK = exhaustive GDK malloc & free tracing for debugging (GDK developers, only) 134217728 = OPTMASK = trace the actions, decisions and effects of MAL optimizers 268435456 = HEAPMASK = trace/debug HEAPextend; used only for development & debugging 536870912 = FORCEMITOMASK = forcefully activate mitosis even on small tables, i.e., split small tables in as many (tiny) pieces as there are cores (threads) available; this allows us to test mitosis functionality without requiring large data sets (--- at the expense of a potentially significant interpretation overhead for unnecessary large plans); used only for development & testing; set automatically by Mtest.py
Note that mserver5 recognizes a series of command line options that sets one or more of these debug flags as well:
--threads (THRDMASK | PARMASK) --memory (MEMMASK | ALLOCMASK) --properties (CHECKMASK | PROPMASK | BATMASK) --io (IOMASK | PERFMASK) --heaps (HEAPMASK) --transactions (TMMASK | DELTAMASK | TEMMASK) --modules (LOADMASK) --algorithms (ALGOMASK | ESTIMASK) --performance (JOINPROPMASK | DEADBEEFMASK) --optimizers (OPTMASK) --forcemito (FORCEMITOMASK)
mserver5 instructs the GDK kernel through the MAL (MonetDB Assembler Language) language. MonetDB 5 contains an extensive optimiser framework to transform MAL plans into more optimal or functional (e.g. distributed) plans. These parameters control behaviour on the MAL level.
You can enable the server listing the parsed MAL program for any script parsed on the command line. The value of mal_listing is an integer that have the following possible values:
0 = Disable 1 = List the original input 2 = List the MAL instruction 4 = List the MAL type information 8 = List the MAL UDF type 16 = List the MAL properties 32 = List the hidden details 64 = List the bat tuple count
The authorisation tables inside mserver5 can be encrypted with a key, such that reading the BATs does not directly disclose any credentials. The monet_vault_key setting points to a file that stores a secret key to unlock the password vault. It can contain anything. The file is read up to the first null-byte (’ ’), hence it can be padded to any length with trailing null-bytes to obfuscate the key length. Generating a key can be done for example by using a tool such as pwgen and adding a few of the passwords generated. Make sure not to chose a too small key. Note that on absence of a vault key file, some default key is used to encrypt the authorisation tables. Changing this setting (effectively changing the key) for an existing database makes that database unusable as noone is any longer able to login. If you use monetdbd(1), a per-database vault key is set.
Controls how many client slots are allocated for clients to connect. This settings limits the maximum number of connected clients at the same time. Note that MonetDB is not designed to handle massive amounts of connected clients. The funnel capability from monetdbd(1) might be a more suitable solution for such workloads.
The SQL component of MonetDB 5 runs on top of the MAL environment. It has its own SQL-level specific settings.
Enable debugging using a mask. This option should normally be disabled (0). Default: 0
The default SQL optimizer pipeline can be set per server. See the optpipe setting in monetdb(1) when using monetdbd. During SQL initialization, the optimizer pipeline is checked against the dependency information maintained in the optimizer library to ensure there are no conflicts and at least the pre-requisite optimizers are used. The setting of sql_optimizer can be either the list of optimizers to run, or one or more variables containing the optimizer pipeline to run. The latter is provided for readability purposes only. Default: default_pipe
The following are possible pipes to use:
The minimal pipeline necessary by the server to operate correctly. minimal_pipe=inline,remap,deadcode,multiplex,garbageCollector
The default pipe line contains as of Feb2010 mitosis-mergetable-reorder, aimed at large tables and improved access locality. default_pipe=inline,remap,costModel,coercions,evaluate,emptySet,aliases,pushselect,mitosis,mergetable,deadcode,commonTerms,joinPath,reorder,deadcode,reduce,matpack,dataflow,history,multiplex,garbageCollector
The no_mitosis pipe line is identical to the default pipeline, except that optimizer mitosis is omitted. It is used mainly to make some tests work deterministically, and to check/debug whether "unexpected" problems are related to mitosis (and/or mergetable). no_mitosis_pipe=inline,remap,costModel,coercions,evaluate,emptySet,aliases,pushselect,mergetable,deadcode,commonTerms,joinPath,reorder,deadcode,reduce,matpack,dataflow,history,multiplex,garbageCollector
The sequential pipe line is identical to the default pipeline, except that optimizers mitosis & dataflow are omitted. It is use mainly to make some tests work deterministically, i.e., avoid ambigious output, by avoiding parallelism. sequential_pipe=inline,remap,costModel,coercions,evaluate,emptySet,aliases,pushselect,mergetable,deadcode,commonTerms,joinPath,reorder,deadcode,reduce,matpack,history,multiplex,garbageCollector
The default pipeline used in the November 2009 release. nov2009_pipe=inline,remap,evaluate,costModel,coercions,emptySet,aliases,mergetable,deadcode,constants,commonTerms,joinPath,deadcode,reduce,dataflow,history,multiplex,garbageCollector
Debugging the optimizer pipeline The best way is to use mdb and inspect the information gathered during the optimization phase. Several optimizers produce more intermediate information, which may shed light on the details. The opt_debug bitvector controls their output. It can be set to a pipeline or a comma separated list of optimizers you would like to trace. It is a server wide property and can not be set dynamically, as it is intended for internal use.
The conf-file readable by mserver5 consists of parameters of the form "name=value".
The file is line-based, each newline-terminated line represents either a comment or a parameter.
Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is not stripped. Trailing whitespace in a parameter value is retained verbatim.
Any line beginning with a hash (#) is ignored, as are lines containing only whitespace.
The values following the equals sign in parameters are all a string where quotes are not needed, and if written be part of the string.