MSERVER5(1)

📦
version 11.55.7 · 2 versions
, in nixpkgs unstable

🎀 NAME 🎀

mserver5 — the MonetDB server version 5. This is the mserver5 page from the MonetDB Applications manual, section 1, and it's literally the main-character server process. 💅

✨ SYNOPSIS ✨

mserver5 [ options ]

🦋 DESCRIPTION 🦋

okay so mserver5 (also written Mserver5) is the current MonetDB server, and it does all the processing when clients ask for a certain database. It's the one doing the actual work, but plot twist: it's usually more common to start, monitor, and connect to the mserver5 process through monetdbd(1), bestie. 🫶

This manual describes the options that mserver5 understands. It's 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 let you adjust them to appropriate values where sensible. For normal usage, it is preferred to apply any configuration through these programs. iykyk ✨

🌸 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 set up 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). periodt. 💀

🔥 MSERVER5 OPTIONS 🔥

mserver5 can be started with options as arguments. Here's the whole menu, no skips, no "oops I forgot one" energy. 🍓

  • --dbpath=path — Path where mserver5 should find a database. Shorthand for option gdk_dbpath. Default value: /nix/store/6mdghwpnnzs4vqhhw8gxy258dg8l0aa9-monetdb-11.55.7/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. If path is equal to stdout, the trace will be written to the standard output which is normally captured by monetdbd(1) and written to its log file. ✨
  • --config=file — Config file to read options from. This file can contain all options that can be set with the --set flag. See CONFIG FILE FORMAT.
  • --single-user — Allow only a single user at a time. lowkey exclusive. 💅
  • --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. Also see the loadmodules entry in monetdb(1). 🧚
  • --without-geom — Start the server without geom support, even if it is available. Normally the server will refuse to start if geom is loaded, but the database was created by a server without geom support. With this option it is possible to start the server anyway. no cap. 🌈
  • --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. 💖
  • --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. 🚨
  • --process-wal-and-exit — Stop the server immediately after processing the write-ahead log.
  • --clean-BBP — Clean up junk BATs from the BBP (i.e. the database). These are BATs that were accidentally left around by older versions of the software (the current version is not known to do this) and so this option should not normally be used. 🫠
  • --logging component=level — Set the specified logging component to the specified level as if the SQL query call logging.setcomplevel(component,level) had been executed, except this is done before SQL is initialized. ⭐
  • --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
    • 256 — (TESTINGMASK) Used for testing
    • 512 — (TMMASK) Transaction management
    • 1024 — (TEMMASK) Locks and Triggers
    • 4096 — (PERFMASK) BBP Performance
    • 8192 — (DELTAMASK) Delta debugging (?)
    • 16384 — (LOADMASK) Module loading
    • 32768 — (PUSHCANDMASK)
    • 65536 — (TAILCHKMASK) Check sizes of .tail files during low-level commit
    • 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)
    • 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).

✨ MSERVER5 PARAMETERS ✨

ok so mserver5 talks to the GDK kernel through MAL, aka the MonetDB Assembler Language 💅 and MonetDB 5 has this whole extensive optimiser framework that transforms MAL plans into plans that are more optimal — or even functional, like distributed ones 🦋. These parameters are the ones that control behaviour at the MAL level. iykyk.

  • monet_vault_key — so the authorisation tables inside mserver5 can be encrypted with a key, so that literally just reading the BATs doesn't spill your credentials 🙈. This setting points to a file that stores the secret key that unlocks the password vault. The file can contain anything. It's read up to the first null-byte (\0), which means you can pad it to any length you want with trailing null-bytes to obfuscate how long the key is 👀. Wanna generate a key? You can do it with a tool like pwgen and just add a few of the passwords it generates together. Just — please — don't pick a key that's too small, bestie. 🔥 Also important: if there's no vault key file, some default key is used to encrypt the authorisation tables. And changing this setting (which is effectively changing the key) for a database that already exists makes that database unusable, because nobody can log in anymore 💀. If you're using monetdbd(1), a per-database vault key gets set for you 🫶.
  • max_clients — controls how many client slots get allocated for clients to connect, and therefore caps the maximum number of clients connected at the same time. Ngl, MonetDB is not designed to handle massive amounts of connected clients. If that's your workload, the funnel capability from monetdbd(1) might be the more suitable solution 👑. Default is 64.
  • mapi_usock — the name of the UNIX domain socket file the server listens on for connections. If the name contains the substring ${PORT}, that part gets replaced by the decimal representation of the TCP/IP port (the mapi_port option). That's especially useful if the port was specified as 0 ✨. Heads up though: there's usually a severe system-imposed limit on how long that file name can be 😭.
  • mapi_port — the TCP/IP port number the server listens on for connections. This only gets used if the value of the mapi_listenaddr option isn't equal to none. Default 50000. If the value is 0, the server uses a so-called ephemeral port, i.e. one the system assigns. Once it successfully starts listening on a port, you can grab the value of the port from the file .conn inside the database (--dbpath) directory 🎀.
  • mapi_listenaddr — the TCP/IP interface the server listens on for connections. The possibilities 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 won't listen on any TCP/IP interface at all (so you need to use the UNIX domain socket interface, bestie 💅).
    • hostname — the server listens on whatever interface that hostname designates, looked up using the normal hostname lookup facilities 🦋.
  • allow_hge_upgrade — set this to yes to let the server upgrade the database from one without 128 bit integer support to one with 128 bit integer (also known as HUGEINT) support 🔥. Note that the upgrade only happens if the server genuinely does support 128 bit integers. Also note: 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. Also, 128 bit integers need support from the C compiler and are therefore not available on all platforms — and it can be turned off at compile time too.

🎀 SQL PARAMETERS 🎀

The SQL component of MonetDB 5 runs on top of the MAL environment, and it has its own SQL-level specific settings, obviously 💅.

  • 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 you're using monetdbd. During SQL initialization, the optimizer pipeline is checked against the dependency information kept in the optimizer library to make sure there are no conflicts and that 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.
  • default_pipe — the default pipeline, which contains the mitosis-mergetable-reorder optimizers, aimed at large tables and improved access locality 👑.
  • no_mitosis_pipe — identical to the default pipeline, except that optimizer mitosis and dependent optimizers are omitted. It's used mainly to make some tests work deterministically, and to check/debug whether "unexpected" problems are related to mitosis (and/or mergetable) 👀.
  • sequential_pipe — identical to the default pipeline, except that optimizers mitosis, dataflow and dependent optimizers are omitted. It's used mainly to make some tests work deterministically, i.e. avoid ambiguous output, by avoiding parallelism 🌈.
  • 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 😭 — so like, be sure about this one.
  • 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 gets compiled first and then executed, which 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. And on top of all that — if the C code causes a crash, all bets are off 💀💀.
  • idle_timeout=seconds — set the idle timeout. If there's an active transaction and the client hasn't provided any input to the server for the specified amount of time, the server closes the connection and aborts (rolls back) the transaction ⏳. The default is 0, which means no timeout.
  • raw_strings=true — this boolean option controls how the sql scanner interprets string literals 🎀. If the value is false, strings are interpreted as if they were delimited with E-quotes, meaning strings are interpreted as C strings and backslash characters are needed to escape special characters. If the value is true, strings are interpreted as if they were delimited with R-quotes, meaning 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 that mserver5 can read consists of parameters of the form name=value. The file is line-based, and 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 that first equals sign is not stripped. Trailing whitespace in a parameter value is retained verbatim 👀. Any line beginning with a hash (#) is ignored, and so are lines containing only whitespace. The values following the equals sign in parameters are all a string — quotes aren't needed, and if you write them they become part of the string 💅.

🌈 SEE ALSO 🌈

monetdbd(1), monetdb(1), mclient(1)

and that's the whole thing bestie, you're officially a MonetDB girlie now 👑🫶 this page came from MonetDB, dated 2025-12-09, and it's MSERVER5(1) — go forth and configure responsibly 💖✨

📦 where this page comes from