MSERVER5(1)

NAME
mserver5 - the MonetDB server version 5

SYNOPSIS
mserver5 [ options ]

DESCRIPTION
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 manual 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.

OPERATION
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 sending it a termination signal (SIGINT, SIGTERM, SIGQUIT).

MSERVER5 OPTIONS
Mserver5 can be started with options as arguments.

--dbpath=path
    Path where mserver5 should find a database. Shorthand for option gdk_dbpath. Default value: @@HOMEBREW_CELLAR@@/monetdb/11.49.9/var/monetdb5/dbfarm/demo.

--dbextra=path
    Path where mserver5 should store transient data. Default value is the value of the --dbpath option. If the value of path is in-memory, transient data is not stored on disk at all but kept in memory at all times.

--dbtrace=path
    File name for the trace log file for mserver5. Default value is the file mdbtrace.log inside the directory specified with the --dbpath option.

--config=file
    Config file to read options from. This file can contain all options as can be set with the --set flag. See CONFIG FILE FORMAT.

--single-user
    Allow only a single user at a time.

--readonly
    The database is opened in read-only mode.

--set option=value
    Set individual configuration option. For possible options, see PARAMETERS sections.

--loadmodule=module
    Load extra module in the form of a dynamic link library (.dll or .so file) which should be located in the lib/monetdb5 directory. This option can be repeated for different modules.

--help
    Print list of options.

--version
    Print version and compile configuration.

--in-memory
    Run mserver5 in-memory. No data will be written to disk. The name of the database that a client can connect to is in-memory.

--debug[=value]
-d[value]
    Set debug level. This is mostly for debugging purposes. The value together with the = sign is optional. If not specified, it defaults to 2. In the short form -d, the value, if present, must immediately (i.e. without space) follow the option. The values of multiple instances of this flag are OR-ed together. The value is an integer, which can be (a bit-wise OR of):
    1   (THRDMASK) thread-specific debug output
    2   (CHECKMASK) property checking on new BATs
    16  (IOMASK) major IO activity
    32  (BATMASK) BAT handling
    128 (PARMASK) Thread management
    512 (TMMASK) Transaction management
    1024
        (TEMMASK) Locks and Triggers
    4096
        (PERFMASK) BBP Performance (?)
    8192
        (DELTAMASK) Delta debugging (?)
    16384
        (LOADMASK) Module loading
    1048576
        (ACCELMASK) Accelerator debugging
    2097152
        (ALGOMASK) show low level algorithm chosen
    16777216
        (NOSYNCMASK) disable forcefully synchronizing files to disk. If this flag is set, there is no guarantee that the database remains consistent after a crash. DO NOT USE (unless you really don't care about your data).
    33554432
        (DEADBEEFMASK) disable ``cleaning'' of freed memory in GDKfree() which only happens in a debug build (i.e. with assertions enabled) 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 unnecessarily large plans); used only for development & testing; set automatically by Mtest.py
--algorithms
    Equivalent to --debug=(ALGOMASK).
--forcemito
    Equivalent to --debug=(FORCEMITOMASK | NOSYNCMASK).
--heaps
    Equivalent to --debug=(HEAPMASK).
--io
    Equivalent to --debug=(IOMASK | PERFMASK).
--memory
    Equivalent to --debug=(ALLOCMASK).
--modules
    Equivalent to --debug=(LOADMASK).
--performance
    Equivalent to --debug=(DEADBEEFMASK).
--properties
    Equivalent to --debug=(CHECKMASK).
--threads
    Equivalent to --debug=(THRDMASK | PARMASK).
--transactions
    Equivalent to --debug=(TMMASK | DELTAMASK | TEMMASK).
--read-password-initialize-and-exit
    Read an unencrypted password from standard input and use it to set the password for the monetdb administrator user, initialize the database, and exit. If the database was already initialized, the administrator password is not changed. This option is used by monetdbd(1) when creating a new database with an administrator password and should not be used otherwise.

MSERVER5 PARAMETERS
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.
monet_vault_key
    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 (``\0''), 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 choose 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 no one is any longer able to login. If you use monetdbd(1), a per-database vault key is set.
max_clients
    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. Default 64.
mapi_usock
    The name of the UNIX domain socket file on which the server will listen for connections. If the name contains the substring ${PORT}, that part will be replaced by the decimal representation of the TCP/IP port (option mapi_port). This is especially useful if the port was specified as 0. Note, there is usually a severe system-imposed length limitation on the name of the file.
mapi_port
    The TCP/IP port number on which the server will listen for connections. This is only used if the value of the mapi_listenaddr option is not equal to none. Default 50000. If the value is 0, the server will use a so called ephemeral port, i.e. one that is assigned by the system. After successfully starting to listen to a port, the value of the port can be retrieved from the file .conn inside the database (--dbpath) directory.
mapi_listenaddr
    The TCP/IP interface on which the server will listen for connections. Possibilites are:
    localhost
        The server listens only on the IPv4 and IPv6 loopback interface. This is the default.
    127.0.0.1
        The server listens only on the IPv4 loopback interface.
    ::1 The server listens only on the IPv6 loopback interface.
    all The server listens on all IPv4 and IPv6 interfaces.
    0.0.0.0
        The server listens on all IPv4 interfaces.
    ::  The server listens on all IPv6 interfaces.
    none
        The server will not listen on any TCP/IP interface (you need to use the UNIX domain socket interface).
    hostname
        The server will listen on the interface designated by hostname which is looked up using the normal hostname lookup facilities.
allow_hge_upgrade
    Set this parameter to yes to allow the server to upgrade the database from one without 128 bit integer support to one with 128 bit integer (also known as HUGEINT) support. Note, the upgrade will only happen if the server does indeed support 128 bit integers. Also note that there is no going back from a database with 128 bit integer support to one without. This option does nothing if no upgrade is required. 128 bit integers requires support from the C compiler and is therefore not available on all platforms. It can also be turned off at compile time.

SQL PARAMETERS
The SQL component of MonetDB 5 runs on top of the MAL environment. It has its own SQL-level specific settings.
sql_debug
    Enable debugging using a mask. This option should normally be disabled (0). Default: 0.
sql_optimizer
    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. Default: default_pipe.
    The following are possible pipes to use:
    minimal_pipe
        The minimal pipeline necessary by the server to operate correctly. minimal_pipe=inline,remap,emptybind,deadcode,for,dict,multiplex,generator,profiler,garbageCollector
    default_pipe
        The default pipeline contains the mitosis-mergetable-reorder optimizers, aimed at large tables and improved access locality. default_pipe=inline,remap,costModel,coercions,aliases,evaluate,emptybind,deadcode,pushselect,aliases,for,dict,mitosis,mergetable,aliases,constants,commonTerms,projectionpath,deadcode,matpack,reorder,dataflow,querylog,multiplex,generator,candidates,deadcode,postfix,profiler,garbageCollector
    no_mitosis_pipe
        The no_mitosis pipeline 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,aliases,evaluate,emptybind,deadcode,pushselect,aliases,mergetable,aliases,constants,commonTerms,projectionpath,deadcode,matpack,reorder,dataflow,querylog,multiplex,generator,candidates,deadcode,postfix,profiler,garbageCollector
    sequential_pipe
        The sequential pipeline 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,aliases,evaluate,emptybind,deadcode,pushselect,aliases,for,dict,mergetable,aliases,constants,commonTerms,projectionpath,deadcode,matpack,reorder,querylog,multiplex,generator,candidates,deadcode,postfix,profiler,garbageCollector
embedded_py
    Enable embedded Python. This means Python code can be called from SQL. The value is true or 3 for embedded Python 3. Note that by enabling embedded Python, users of the server are allowed to execute arbitrary Python code, and are therefore able to read and modify all data that the server process has access to.
embedded_r=true
    Enable embedded R. This means R code can be called from SQL. Note that by enabling embedded R, users of the server are allowed to execute arbitrary R code, and are therefore able to read and modify all data that the server process has access to.
embedded_c=true
    Enable embedded C. This means C code can be called from SQL. The C code will first be compiled and then executed. This means a C compiler must be available. Note also that by enabling embedded C, users of the server are allowed to execute arbitrary C code, and are therefore able to read and modify all data that the server process has access to. In addition, if the C code causes a crash, all bets are off.
raw_strings=true
    The boolean option raw_strings controls how the sql scanner interprets string literals. If the value is false then strings are interpreted as if they were delimited with E-quotes, that is strings are interpreted as C strings and backslash characters are needed to escape special characters. If the value is true then strings are interpreted as if they were delimited with R-quotes, that is all characters are interpreted literally. Single quote characters need to be doubled inside strings. The default value is false.

CONFIG FILE FORMAT
The configuration 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.

SEE ALSO
monetdbd(1), monetdb(1), mclient(1)