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.
The URL syntax follows the rules of RFC 3986. The general form is:
monetdb://[host[:port]]/[database][?param1=value1[¶m2=value2...]]
monetdbs://[host[:port]]/[database][?param1=value1[¶m2=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
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.
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.
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:
Parameter | Description |
---|---|
user | user name to authenticate as |
password | password to authenticate with |
sock | path to Unix domain socket to connect to |
autocommit | initial value of autocommit, one of yes/no/true/false/on/off |
schema | initial schema |
timezone | client time zone as minutes east of UTC |
replysize | rows beyond this limit are retrieved on demand, <1 means unlimited |
Parameters for encrypted (TLS) connections (monetdbs:
)
Parameter | Description |
---|---|
cert | path to TLS certificate to authenticate server with |
certhash | require hash of server certificate to start with these hex digits; overrides cert |
clientkey | path to TLS key (+certificates) to authenticate with as client |
clientcert | path to TLS certs for 'clientkey', if not included there |
Infrequently used parameters
Parameter | Description |
---|---|
sockdir | Directory for implicit Unix domain sockets (e.g., /tmp/.s.monetdb.PORT) |
language | for internal use only |
binary | specific to pymonetdb, yes/no/true/false/on/off or a number |
maxprefetch | specific to pymonetdb |
fetchsize | alias for replysize, for interoperability with JDBC |
hash | specific to jdbc |
debug | specific to jdbc |
logfile | specific to jdbc |