MonetDB URLs

Some of the tools and libraries, in particular mclient, msqldump and the Java- and Python connectors, allow to bundle all connection parameters into a URL. For example,

    monetdb://localhost:50000/demo?user=monetdb&password=monetdb

Such URLs were already used by the JDBC driver, with a jdbc: prefix, but as of MonetDB Dec2023 the syntax has been extended and unified across the libmapi (C), monetdb-jdbc (Java) and pymonetdb (Python) connectors, and the mclient, msqldump and jdbcclient command-line utilities.

Beside the monetdb: URL scheme there is also the monetdbs: scheme for connections encrypted using TLS (Transport Layer Security). For more details, see TLS.

You may also have come across the legacy mapi:monetdb://host:port/db URL format. This will be phased out in favor of the new mapi:-less format but remain supported where it was supported before.

For a more precise description of the MonetDB URL schemes, suitable for connector developers, see MonetDB URL Spec.

URL Syntax

The URL syntax follows the rules of RFC 3986. The general form is:

 monetdb://[host[:port]]/[database][?param1=value1[&param2=value2...]]
monetdbs://[host[:port]]/[database][?param1=value1[&param2=value2...]]

If necessary, host, database name and parameter values can be percent-encoded. For example, the password M&Ms can be given as

monetdb:///demo?user=snackdb&password=M%26Ms

Host name syntax

The host can be written in multiple ways:

• a host name: dbhost.example.com

• an IPv4 address as dotted decimals: 127.0.0.1

• an IPv6 address in hex between square brackets: [2001:0db8:85a3::8a2e:0370:7334]

• the special string localhost, this will try to connect to Unix Domain sockets as well as TCP sockets. (See below.)

• the special string localhost. with a trailing period. This will only try to connect to TCP sockets, not Unix Domain.

• The empty string is equivalent to localhost. Not all clients allow a port number if the host name is omitted.

Unix Domain Sockets

MonetDB supports two connection mechanisms: TCP sockets and Unix Domain sockets. TCP is supported on all platforms including Windows, Unix Domain only on Unix-like systems such as Linux and MacOS.

TCP is a network protocol. The address consists of a host identifier (IP or host name) combined with a port number. TCP connections can be encrypted with TLS.

Unix domain sockets exist as special files in the file system. They have a path and you see them when you list their directory. For example, a MonetDB instance listening on port TCP 50000 usually also listens on Unix Domain socket /tmp/.s.monetdb.50000. Unix Domain sockets can be slightly more secure and efficient than TCP sockets. They cannot be secured with TLS but there is no need for that as they are only accessible from the host itself.

Not all MonetDB clients support Unix Domain sockets. For example, mclient and pymonetdb do, but JDBC doesn't.

To force the use of Unix Domain sockets, leave the host name empty or localhost and use the sock option to specify the path to the socket. For example, monetdb:///demo?sock=/path/to/sock.

When the host name is empty or localhost and no sock option is given, first one or more default Unix Domain sockets will be tried before resorting to TCP.

Further Parameters

The following tables list the parameters that can be passed in a MonetDB URL.

All clients accept but ignore parameters from this table that do not apply to them. Some clients support additional parameters, their names must always contain an underscore. Unknown parameters with an underscore are silently ignored, unknown parameters without an underscore give an error.

Commonly used parameters:

Parameters for encrypted (TLS) connections (monetdbs:)

Infrequently used parameters