Skip to main content


The JdbcClient program is a textual command line program (inspired by mclient) for interactieve SQL processing and querying written completely in Java using the JDBC API and the MonetDB JDBC driver. It is available as a single small jar file jdbcclient.jre8.jar downloadable from MonetDB Java Download Area. The jar file already includes the MonetDB JDBC driver, which is used to communicate to a MonetDB server, so no further jar files (or classpath settings) are needed.

The JdbcClient program supports startup options. To view them simply type in a shell the command:

     java -jar jdbcclient.jre8.jar --help

This will show following usage information:

Usage java -jar jdbcclient.jre8.jar
		[-h host[:port]] [-p port] [-f file] [-u user]
		[-l language] [-d database] [-e] [-D [table]] [-X<opt>]
		| [--help] | [--version]
or using long option equivalents --host --port --file --user --language
--database --echo --dump.
Arguments may be written directly after the option like -p50000.

If no host and port are given, localhost and 50000 are assumed.
An .monetdb file may exist in the user's home directory.  This file can contain
preferences to use each time JdbcClient is started.  Options given on the
command line override the preferences file.  The .monetdb file syntax is
<option>=<value> where option is one of the options host, port, file, mode
debug, or password.  Note that the last one is perilous and therefore not
available as command line option.
If no input file is given using the -f flag, an interactive session is
started on the terminal.

-h --host     The hostname of the host that runs the MonetDB database.  A port
              number can be supplied by use of a colon, i.e. -h somehost:12345.
-p --port     The port number to connect to.
-f --file     A file name to use either for reading or writing.  The file will
              be used for writing when dump mode is used (-D --dump).  In read
              mode, the file can also be an URL pointing to a plain text file
              that is optionally gzip compressed.
-u --user     The username to use when connecting to the database.
-d --database Try to connect to the given database (only makes sense if
              connecting to monetdbd).
-l --language Use the given language, defaults to 'sql'.
--help        This help screen.
--version     Display driver version and exit.
-e --echo     Also outputs the contents of the input file, if any.
-q --quiet    Suppress printing the welcome header.
-D --dump     Dumps the given table(s), or the complete database if none given.
-Xoutput      The output mode when dumping.  Default is sql, xml may be used for
              an experimental XML output.
-Xhash        Use the given hash algorithm during challenge response. Supported
              algorithm names: SHA512, SHA384, SHA256 and SHA1.
-Xdebug       Writes a transmission log to disk for debugging purposes. If a
              file name is given, it is used, otherwise a file called
              monet<timestamp>.log is created.  A given file never be
              overwritten; instead a unique variation of the file is used.
-Xbatching    Indicates that a batch should be used instead of direct
              communication with the server for each statement.  If a number is
              given, it is used as batch size.  i.e. 8000 would execute the
              contents on the batch after each 8000 statements read.  Batching
              can greatly speedup the process of restoring a database dump.


Using the JdbcClient program

It is easy to start it (assuming you have a MonetDB/SQL server running) from a shell, for example:

% java -jar jdbcclient.jre8.jar -p50000 -ddemo -umonetdb

Welcome to the MonetDB interactive JDBC terminal!
JDBC Driver: MonetDB Native Driver v3.0 (Liberica 20210219 based on MCL v1.19)
Database Server: MonetDB v11.39.13
Current Schema: sys
Type \q to quit (you can also use: quit or exit), \? or \h for a list of available commands
auto commit mode: on

As the password cannot be provided as startup option, you will be asked to enter it after the password: prompt.

Tip: if you do not want to enter the password each time, use a .monetdb file (which contains the user and password settings) similar as for mclient.

If the authentication or connection fails, observe the printed error messages from jdbcclient (and/or the merovingian logs) for clues.

After a successful connection the sql> prompt is shown, allowing you to enter any SQL query or backslash commands and execute it by using the enter-key. You can use multiple lines to enter the SQL query. To execute it enter the ; character after the SQL query, and press the enter-key. For example:

sql> select * from table_types
more> order by 2;
| table_type_id | table_type_name        |
|            20 | GLOBAL TEMPORARY TABLE |
|            30 | LOCAL TEMPORARY TABLE  |
|             3 | MERGE TABLE            |
|             5 | REMOTE TABLE           |
|             6 | REPLICA TABLE          |
|             4 | STREAM TABLE           |
|            10 | SYSTEM TABLE           |
|            11 | SYSTEM VIEW            |
|             0 | TABLE                  |
|             1 | VIEW                   |
10 rows
Elapsed Time: 4 ms

To view a list of available backslash commands enter \? after the sql> prompt and the enter-key.

sql> \?
Available commands:
\q       quits this program (you can also use: quit or exit)
\d       list available user tables and views in current schema
\dS      list available system tables and views in sys schema
\d <obj> describes the given table or view
\l<uri>  executes the contents of the given file or URL
\i<uri>  batch executes the inserts from the given file or URL
\vsci    validate sql system catalog integrity
\vsi <schema>  validate integrity of data in the given schema
\vdbi    validate integrity of data in all user schemas in the database
\? or \h this help screen

Use \q to quit the program. Alternatively you may use quit or exit commands.

The following commands allow you to quickly validate data integrity of: system catalog tables or tables in one schema or all user schemas in the database:
  \vsi  schema_name
The current validations include:
- Primary Key uniqueness
- Primary Key column(s) being NOT NULL (currently only for \vsci)
- Unique constraint uniqueness
- Foreign Key referential integrity
- Column NOT NULL constraint
- Char(n), varchar(n), clob(n), blob(n), json(n) and url(n) max length constraint

It is advised to run \vsci command before and after an upgrade of MonetDB server to check if the system catalog tables are consistent.
Use \vsi my_schema to validate data in all tables of a specific schema.
Use \vdbi to validate integrity of user data in all user schemas in the database.
Note: It can take a long time to complete, depending on your number of user schemas, tables, columns and rows.
Warning: The integrity validation functionality is still beta, so you can get false errors reported.
If you encounter any please let us know via


Note: The JDBC protocol does not support the SQL: DEBUG <query> ; or TRACE <query> ; commands functionality. Use the mclient program for those instead.

Note: the JdbcClient program is provided as a simple tool for performing connectivity and interactive tests using integrated MonetDB JDBC driver.
It is *not* recommended for production environments, the mclient program should be used instead.