Changeset: f31366ece930 for monetdb-java URL: https://dev.monetdb.org/hg/monetdb-java/rev/f31366ece930 Added Files: release.md Removed Files: release.txt Branch: default Log Message:
Convert release.txt to release.md and add TLS info Plus various other changes. diffs (295 lines): diff --git a/release.txt b/release.md rename from release.txt rename to release.md --- a/release.txt +++ b/release.md @@ -1,5 +1,8 @@ RELEASE NOTES +============= + MonetDB JDBC driver version 3.3 (Liberica) +<br> Release date: 2023-02-23 The Java Database Connectivity (JDBC) API provides universal data access from @@ -15,70 +18,88 @@ The sources for this JDBC driver and rel https://dev.monetdb.org/hg/monetdb-java/file/tip -The MonetDB JDBC connection URL format to use is: - jdbc:monetdb://<hostname>[:<portnr>]/<databasename>[?<property>=<value>[&<property>=<value>]] +URL Format +---------- + +The MonetDB JDBC connection URL format is: + +<pre> +jdbc:<b>monetdb</b>://[<host>[:<port>]]/<databasename>[?<properties>] (not encrypted) +OR +jdbc:<b>monetdbs</b>://[<host>[:<port>]]/<databasename>[?<properties>] (encrypted) -Note: For a successful connection the database name part must be provided - and be equal to the name of the database served by the mserver5 process running on - the specified host and listening to the specified port number (default port is 50000). +where <properties> are &-separated: prop1=value1[&prop2=value2[&prop3=value3...]] +</pre> + +The second form (monetdbs) is for creating a TLS-protected connection. TLS (Transport Layer Security) +is the mechanism that is also used for HTTPS. + +Property keys and values support percent-escaped bytes. For example, the +password 'chocolate&cookies' can be passed as follows: `jdbc:monetdb:///demo?user=me&password=chocolate%26cookies`. + +Note: MonetDB-Java version 3.3 and earlier did not support percent-escapes. +If your password contains percent-characters, these must now be encoded as `%25`. Supported connection properties are: - user=<login name> - password=<secret value> - so_timeout=<time in milliseconds> default is: 0 (no timeout) - treat_clob_as_varchar=false default is: true - treat_blob_as_binary=false default is: true - language=<sql or mal> default is: sql - fetchsize=<nr of rows> default is: 250; -1 means fetch everything at once - autocommit=false default is: true - debug=true default is: false - logfile=<name of logfile> - hash=<SHA512, SHA384, SHA256 or SHA1> + +| Property | Default | Notes | +| ----------------------------------------- | ------- | --------------------------------------------------- | +| user=<login name> | - | required | +| password=<secret value> | - | required | +| so_timeout=<time in milliseconds> | - | | +| treat_clob_as_varchar=<bool> | true | | +| treat_blob_as_binary=<bool> | true | | +| language=<sql or mal> | sql | | +| replysize=<nr of rows> | 250 | -1 means fetch everything at once | +| autocommit=<bool> | true | | +| schema=<schema name> | - | initial schema to select | +| timezone=<minutes east of UTC> | system | | +| debug=true | false | | +| logfile=<name of logfile> | | | +| hash=<SHA512, SHA384, SHA256 or SHA1> | | | +| cert=<path to certificate> | - | TLS certificate must be in PEM format | +| certhash=sha256:<hexdigits and colons> | - | required hash of server TLS certificate in DER form | + -The treat_clob_as_varchar property (when set to true) will let the method -ResultSetMetaData.getColumnType(int) to return Types.VARCHAR instead of Types.CLOB -for CLOB ResultSet columns. Generic JDBC applications such as SQuirreL SQL and DBeaver -will than use rs.getString() instead of rs.getClob() to fetch any CLOB column data. -Using rs.getString() avoids creating new objects and multiple copies of the clob -string data resulting in (much) faster response and better user experience. -This property is turned on by default as of release monetdb-jdbc-3.0.jre8.jar. -You can turn it off if you prefer the old behavior. +Booleans <bool> can be written as 'true', 'false', 'yes', 'no', 'on' and 'off'. Property 'fetchsize' is accepted as an alias of 'replysize'. + +Client authentication (Mutual TLS, or MTLS) is not yet supported. + +When the properties 'treat_clob_as_varchar' and 'treat_blob_as_binary' are enabled, -The treat_blob_as_binary property (when set to true) will let the method -ResultSetMetaData.getColumnType(int) to return Types.VARBINARY instead of Types.BLOB -for BLOB ResultSet columns. Generic JDBC applications such as SQuirreL SQL and DBeaver -will than use rs.getBytes() instead of rs.getBlob() to fetch any BLOB column data. -Using rs.getBytes() avoids creating new objects and multiple copies of the blob -string data resulting in (much) faster response and better user experience. -This property is turned on by default as of release monetdb-jdbc-3.0.jre8.jar. -You can turn it off if you prefer the old behavior. +The properties 'treat_clob_as_varchar' and 'treat_blob_as_binary' control which +type is returned by ResultSetMetaData.getColumnType(int) for CLOB and BLOB columns. +When 'treat_clob_as_varchar' is enabled, Types.VARCHAR is returned instead of Types.CLOB +for CLOB columns. When 'treat_blob_as_binary' is enabled, Types.VARBINARY is returned instead +of Types.BLOB for BLOB columns. +This will cause generic JDBC applications such as SQuirrel SQL and DBeaver to use +the more efficient '#getString()' and '#getBytes()' API rather than '#getClob()' and +'#getClob()'. +These properties are enabled by default since MonetDB-Java version 3.0. -We recommend to set following connection properties: - so_timeout=20000 -Multiple connection properties are separated by the & character. -For example: - jdbc:monetdb://localhost:41000/mydb?user=monetdb&password=onlyiknow&so_timeout=20000 +Use +--- See also: https://www.monetdb.org/Documentation/SQLreference/Programming/JDBC - -The MonetDB JDBC driver class name is: org.monetdb.jdbc.MonetDriver +The MonetDB JDBC driver class name is `org.monetdb.jdbc.MonetDriver`. This has been changed as of release 3.0 (monetdb-jdbc-3.0.jre8.jar). The old driver class (nl.cwi.monetdb.jdbc.MonetDriver) has been deprecated -since 12 Nov 2020 and removed from release 3.4 (monetdb-jdbc-3.4.jre8.jar). -Please use the new driver class name asap in your configuration files and Java code. +since 12 Nov 2020 and has been removed in release 3.4 (monetdb-jdbc-3.4.jre8.jar). JDBC COMPLIANCE +--------------- + The MonetDB JDBC driver is a type 4 driver (100% pure Java) and -complies to JDBC 4.2 definition, see +complies to the JDBC 4.2 definition, see http://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/index.html and https://en.wikipedia.org/wiki/Java_Database_Connectivity Within the current implementation not all functionalities of the JDBC -interface are available. It is believed, however, that this +interface are available. It is believed however, that this implementation is rich enough to be suitable for a majority of application settings. @@ -91,11 +112,11 @@ please let us know at our bugtracker: Currently implemented JDBC 4.2 interfaces include: * java.sql.Driver - The next method is NOT useable/supported: + The following method is NOT useable/supported: - getParentLogger * java.sql.Connection - The next features/methods are NOT useable/supported: + The following features/methods are NOT useable/supported: - createArrayOf, createNClob, createStruct, createSQLXML - prepareStatement with array of column indices or column names - setHoldability (close/hold cursors over commit is not configurable) @@ -120,7 +141,7 @@ Currently implemented JDBC 4.2 interface parameters to a specific procedure. * java.sql.Statement - The next methods/options are NOT useable/supported: + The following methods/options are NOT useable/supported: - cancel (query execution cannot be terminated, once started) see also: https://github.com/MonetDB/monetdb-java/issues/7 or https://www.monetdb.org/bugzilla/show_bug.cgi?id=6222 @@ -128,12 +149,12 @@ Currently implemented JDBC 4.2 interface - executeUpdate with column indices or names - setMaxFieldSize - setCursorName - The next methods will add an SQLWarning: + The following methods will add an SQLWarning: - setEscapeProcessing(true) for Sep2022 (11.45) and older servers - setEscapeProcessing(false) for Jun2023 (11.47) and newer servers * java.sql.PreparedStatement - The next methods are NOT useable/supported: + The following methods are NOT useable/supported: - setArray - setAsciiStream - setBinaryStream @@ -147,7 +168,7 @@ Currently implemented JDBC 4.2 interface * java.sql.ParameterMetaData * java.sql.CallableStatement - The next methods are NOT useable/supported: + The following methods are NOT useable/supported: - all getXyz(parameterIndex/parameterName, ...) methods because output parameters in stored procedures are not supported by MonetDB - all registerOutParameter(parameterIndex/parameterName, int sqlType, ...) methods @@ -165,7 +186,7 @@ Currently implemented JDBC 4.2 interface - setUnicodeStream (note: this method is Deprecated) * java.sql.ResultSet - The next methods are NOT useable/supported: + The following methods are NOT useable/supported: - getArray - getAsciiStream, getUnicodeStream - getNClob @@ -183,12 +204,12 @@ Currently implemented JDBC 4.2 interface * java.sql.Blob A simple implementation using a byte[] to store the whole BLOB. - The next method is NOT useable/supported: + The following method is NOT useable/supported: - setBinaryStream * java.sql.Clob A simple implementation using a StringBuilder to store the whole CLOB. - The next methods are NOT useable/supported: + The following methods are NOT useable/supported: - setAsciiStream - setCharacterStream @@ -197,7 +218,7 @@ Currently implemented JDBC 4.2 interface and by class: org.monetdb.jdbc.types.URL * javax.sql.DataSource (not tested) - The next method is NOT useable/supported: + The following method is NOT useable/supported: - getParentLogger @@ -214,20 +235,25 @@ The following java.sql.* interfaces are * java.sql.Struct +ON CLIENT support +----------------- Since release 3.2 (monetdb-jdbc-3.2.jre8.jar), the MonetDB JDBC driver has -support for the ON CLIENT clause of the COPY statement. To make use of +support for the ON CLIENT clause of the COPY statement. To use this functionality you must register handlers for upload and download of data. The MonetConnection class has been extended with 2 methods: - public void setUploadHandler(UploadHandler uploadHandler) - public void setDownloadHandler(DownloadHandler downloadHandler) -The API has been extended with interfaces and utility classes: - public interface org.monetdb.jdbc.MonetConnection.UploadHandler - public interface org.monetdb.jdbc.MonetConnection.DownloadHandler - public static class org.monetdb.jdbc.MonetConnection.Upload - public static class org.monetdb.jdbc.MonetConnection.Download - public class org.monetdb.util.FileTransferHandler - which implements MonetConnection.UploadHandler, MonetConnection.DownloadHandler + +* public void setUploadHandler(UploadHandler uploadHandler) +* public void setDownloadHandler(DownloadHandler downloadHandler) + +The API has been extended with some further interfaces and utility classes: +* public interface org.monetdb.jdbc.MonetConnection.UploadHandler +* public interface org.monetdb.jdbc.MonetConnection.DownloadHandler +* public static class org.monetdb.jdbc.MonetConnection.Upload +* public static class org.monetdb.jdbc.MonetConnection.Download +* public class org.monetdb.util.FileTransferHandler + which implements the UploadHandler and DownloadHandler interfaces. + See file onclient.txt for more information on how to use these from Java. The JdbcClient application has also been extended to support COPY ... @@ -236,10 +262,12 @@ explicit new startup argument --csvdir "/path/to/csvdatafiles" or on MS Windows --csvdir "C:\\path\\to\\csvdatafiles" -in order to allow the JdbcClient to down/up load data to/from local csv files. +in order to allow the JdbcClient to access local files. -Notes and Tips for Java Programmers using MonetDB JDBC driver: +Notes and tips +-------------- + - After creating a Connection object check for SQLWarnings via conn.getWarnings(); - Close JDBC ResultSet, Statement, PreparedStatement, CallableStatement and @@ -292,7 +320,7 @@ Notes and Tips for Java Programmers usin See also the example Java JDBC program on: https://www.monetdb.org/Documentation/SQLreference/Programming/JDBC -WARNING: +**WARNING**: The current implementation of the MonetDB JDBC driver is *NOT* multi-thread safe. If your program uses multiple threads concurrently on the same Connection (so one MapiSocket), this may lead to incorrect behavior @@ -300,7 +328,7 @@ WARNING: You will need to serialize the processing of the threads in your Java program. Alternatively you can use a separate JDBC Connection for each thread. -Note: as of Febr 2021 (monetdb-jdbc-3.0.jre8.jar) we compile all +Note: as of version 3.0 (monetdb-jdbc-3.0.jre8.jar) we compile all the java sources to target: Java SE 8 (profile compact2), so you need a JRE/JDK JVM of version 8 or higher to use it. _______________________________________________ checkin-list mailing list -- checkin-list@monetdb.org To unsubscribe send an email to checkin-list-le...@monetdb.org
