What's new in this release?

Support and Certifications

Changes Since 8.1.0 GA

• Enhancements
  • The driver is now compiled with a Visual Studio 2022 compiler for the Windows platforms. As a result, you must have Microsoft Visual C/C++ runtime version 14.40.33810 or higher on your machine to run the driver.
  • The driver has been enhanced to support the TLSv1.3 cryptographic protocol. See Crypto Protocol Version for details.
  • The driver has been enhanced to allow you to configure whether the driver inserts String values that exceed the column length defined in the relational schema. You can configure this behavior using the new String Truncation Method For Writes (StringTruncationMethodForWrites) options. See String Truncation Method for Writes for details.
  • The driver has been enhanced to allow you to increase the default length of VARCHAR columns to increase the size of data values you can insert with the driver. You can configure the new Min Varchar Size (MinVarcharSize) option to specify minimum default length of fields mapped to VARCHAR. See Min Varchar Size for details.
  • The driver has been enhanced to allow you to specify the format in which the driver renders the MongoDB composite timestamp. This allows you to specify the format of the MongoDB composite timestamp that is most appropriate for your use case. You can configure this driver behavior using the new Timestamp Format (TimestampFormat) option. See Timestamp Format for details.
  • The SQL engine server has been enhanced to automatically start and stop the service as needed. When the new Broker mode is enabled (SQLEngineMode=3), the SQL engine operates in an external Java process that is monitored by the driver's Broker. The Broker eliminates the need to explicitly start and stop the service, as well as more efficiently manage memory and resource consumption. See Using the SQL engine server for details.
  • The driver has been enhanced to support replacing the internal mapping files at connection. When Create Map (CreateMap) is set to 1 (ForceNew), the driver replaces the schema map files specified by the Schema Map (SchemaMap) option with newly generated files at the same location. In addition, if you are upgrading from driver version 8.0 to 8.1, the driver retains a copy of the 8.0 version of the schema map files as a backup when generating the 8.1 version of the files. See Create Map for details.

  • The driver has been enhanced with the new Array Normalization Threshold (ArrayNormalizationThreshold) connection option. Array Normalization Threshold allows you to specify the length of arrays (in elements) at which the driver begins to normalize arrays to child tables when generating a flattened view. This provides you with a method to control the size and focus of your parent table when encountering large arrays or nested arrays. See Array Normalization Threshold for details

  • The driver has been enhanced to support data compression for all messages passed between the client and server. Data compression can significantly reduce network traffic, which, in turn, can lower data transfer costs for cloud services. See Network Message Compressors for details.
  • The driver has been enhanced to support MongoDB views created in the database. MongoDB views are discovered during the sampling process and mapped using the same schema format used for your collections. See MongoDB views for details.
  • The driver has been enhanced to support generating legacy virtual keys for newly-discovered nested objects. For driver versions earlier than 8.1, the driver used legacy virtual keys (unique identifiers) as a foreign key to associate the child table back to the parent. When the new LegacyVirtualKeys (LegacyVirtualKeys) option is set to 1 (true), the driver generates legacy virtual keys in the object_name_GENERATED_ID column in new and migrated schemas. This functionality allows you to maintain consistent column naming for driver generated virtual key columns when migrating normalized schema maps from the 8.0 format. See Legacy Virtual Keys for details.
  • The driver has been enhanced to support connections to Microsoft Azure Cosmos DB for MongoDB. See Microsoft Azure Cosmos DB for MongoDB for details.
  • The driver has been enhanced to support the JavaScript and Regex data types. See Data types for details.
• Changed behavior
  • The driver no longer compresses messages passed between the client and the server by default. Additional research has uncovered that network compression might not provide the best performance in all environments. As a result, the default behavior of the Network Message Compressors (NetworkMessageCompressors ) option has been changed to none. See Network Message Compressors for details.
  • The behaviors of valid values for the Create Map (CreateMap) option have been changed as follows:

    • If set to 0 (No), the driver uses the current group of internal files specified by the Schema Map option. If the files do not exist, the connection fails.

    • If set to 2 (NotExist), the driver uses the current group of internal files specified by the Schema Map (SchemaMap) option. If the files do not exist, the driver creates them.

    See Create Map for details.

  • The SchemaDefinition attribute has been added as an alias for the Schema Map (SchemaMap) option. This change allows users to continue using their configurations for earlier versions of the driver until they are able update their connection settings. Note that SchemaDefinition is a deprecated attribute and may not be supported in future versions of the driver. See Schema Map for details.

Changes for 8.1.0 GA

• Enhancements
  • The driver has been enhanced to support generating legacy virtual keys for new nested objects. Legacy virtual keys are unique identifiers used to handle joins in version 8.0 and earlier of the driver. When the Legacy Virtual Keys (LegacyVirtualKeys) option is set to 1 (true), the driver generates legacy virtual keys in the object_name_GENERATED_ID column for new and migrated schemas. This functionality provides a method to continue using legacy virtual keys, if you prefer. See Legacy Virtual Keys for details.
  • The normalization algorithm has been upgraded to improve sampling performance and optimize the generation of tables in the relational view. In addition, the new Schema Format (SchemaFormat) connection option allows you to determine to which relational view the driver maps data, including normalized, mixed, and flattened views. See Mapping objects to tables for details.
  • The driver supports migrating schema maps and internal files created with the 8.0 version of the driver so that they can be used by the 8.1 driver. By migrating these files, you can continue to execute the same SQL statements that you did with the 8.0 driver while still leveraging the advantages of the 8.1 driver. See Migrating schema maps and native files to 8.1 for details.
  • The driver has been enhanced to support LDAP (Lightweight Directory Access Protocol) authentication. See LDAP authentication for details.
  • The new Schema Filter (SchemaFilter) connection option allows you to specify the database and collections pairs for which you want the driver to fetch metadata. Configuring this option can significantly improve connection times by limiting the collections for which metadata is fetched to only those that are required by your application. See Schema Filter for details.
  • The new Qualify Normalized Names (QualifyNormalizedNames) option allows you to determine whether names of relational child-tables normalized from arrays, objects, subdocuments are prefixed with the collection name and names of any parent objects. See Qualify Normalized Names for details.
  • The new Special Char Behavior (SpecialCharBehavior) option allows you to control how the driver handles the mapping of native identifiers containing characters that would require them to be quoted in SQL statements. This option provides a method to choose to continue using identifiers that require quotation marks or for the driver to modify affected identifier names so that quotation marks are not required. See Special Char Behavior for details.
  • The new JSON columns (JSONColumns) option allows you to determine whether the driver exposes documents and arrays embedded within a collection as JSON formatted fields in addition to the individual collection and array elements being mapped as fields when using flattened mapping. Note that Querying JSON values can be an expensive operation that could negatively impact performance; therefore, you should only query JSON values when necessary. See JSON Columns for details.
  • The new Flatten Array Base (FlattenArrayBase) option allows you to specify the starting ordinal value appended to column names for flattened arrays. When flattening arrays, column names are appended with an underscore and the ordinal value (<array_name>_<ordinal_location>). This option allows you to determine whether the first ordinal value in the series is either a 0 or a 1. See Flatten Array Base for details.
  • The driver has been enhanced to support replica set failover for write operations. This feature can be enabled by specifying your replica set name using the new Replica Set Name (ReplicaSetName) connection option. SeeReplica set failover for write operations and Replica Set Name for details.
  • The driver has been enhanced to support connections to MongoDB Atlas clusters using a DNS seed list. Instead of specifying connection information for individual nodes, the driver allows you to specify the name of the DNS SRV record using the Host Name (HostName) option. The driver then uses a DNS lookup to discover the member nodes in the cluster to which it can connect. You can control whether driver performs a DNS lookup using the new Enable DNS Lookup (EnableDNSLookup) option. See MongoDB Atlas clusters for details.
  • On Windows, the driver now includes the MongoDB Configuration Manager for quick configuration and testing of your driver in a web browser. The tool allows you to:
    • Configure data sources and connection strings
    • Test connectivity for your data sources and connection strings
    • Execute SQL commands for testing purposes

    For details, see Configuring data sources with the Configuration Manager, Generating connection strings with the Configuration Manager, and Testing connections and queries with the Configuration Manager.

  • The driver has been enhanced with the new Authentication Database (AuthenticationDatabase) connection option, which provides a method to specify the database in which the user id was created for user id and password authentication (AuthenticationMethod=userIdPassword). This allows you to explicitly select a set of credentials when the same user ID was created on multiple databases. See Authentication Database for details.
  • The driver has been enhanced to support the SCRAM-SHA-256 authentication method for user ID and password authentication. When user ID and password authentication is enabled (AuthenticationMethod=UserIDPassword), the driver detects and uses the most secure method supported by the server. See Authentication Method for details.
  • The driver has been enhanced to use proxy server settings defined in the JVM system option by default. If no proxy settings are defined in the connection string or data source, the driver will attempt to use the values of the http.proxyHost and http.proxyPort JVM system option to connect to the database. See Proxy server for details.
  • The driver has been enhanced to allow you to limit sampling to only new collections when refreshing the schema map. This provides for quicker processing times if you only want to map new collections or if existing collections are unchanged. You can limit sampling to only new collections by specifying the NEW option in a Refresh Map statement. See Refresh Map (EXT) for details.
  • The driver has been enhanced to support the native Decimal128 data type, which maps to the Decimal ODBC type by default. See Data types for details.
  • The driver has added support for the MinKey and MaxKey special values. See MinKey and MaxKey values for details.
  • The driver has been enhanced to include timestamp in the internal packet logs by default. If you want to disable the timestamp logging in packet logs, set PacketLoggingOptions=1. The internal packet logging is not enabled by default. To enable it, set EnablePacketLogging=1.
  • The CAST_TO_NATIVE function escape has been introduced to select or insert a value of a specific native type. This can be particularly useful when MongoDB has inconsistent native types for a given field. Currently, CAST_TO_NATIVE can only be used with the ObjectID type in SELECT statement filters and literal INSERT values. See CAST_TO_NATIVE function escape for details.
• Changed behavior
  • The default mapping behavior of the driver has been changed from generating a normalized view of data to one that is a mixture of normalized and flattened views. The mixed view reduces the number of tables generated while providing a more intuitive data model. You can configure the mapping behavior using the new Schema Format (SchemaFormat) option. For details see Mixed view and Schema Format for details.
  • The Schema Tool and manual customizations of the schema map are not currently supported. However, you can control certain aspects of relational data model generated by the driver using mapping connection options. . See Connection option descriptions for details.
  • The Create Database (CreateDB) connection option has been replaced by the Create Map (CreateMap) option. The valid values and behavior are identical for both options. See Create Map for details.
  • The Database (Database) connection options has been replaced by the Database Name (DatabaseName) option. The valid values and behavior are identical for both options. See Database Name for details.
  • The User Name (LogonID) connection option has been replaced with the User (User) option. The valid values and behavior are identical for both options. See User for details.
  • The Login Timeout (LoginTimeout) is not currently supported. To specify the login time out behavior for an individual connection, set a value in the SQL_ATTR_LOGIN_TIMEOUT connection attribute using the SQLSetConnectAttr() function.
  • The Config Options (ConfigOptions) connection option is no longer supported. As a result, the driver has been enhanced to support setting each of the configuration options formerly supported by Config Options as standalone connection options. See Connection option descriptions for details.
  • The following Config Options are no longer supported:
    • DefaultVarcharSize
    • MaxVarcharSize
    • MinVarcharSize

    To determine the default length of VARCHAR fields, the driver multiplies the largest discovered field by 1.5. For example, if the largest detected field has a length of 100 characters, the driver sets the default length to 150 characters.

  • The driver does not currently support the IBM System z Linux platform.
  • Support has ended for database versions earlier than MongoDB 3.6.
  • Support for has ended for the following 32-bit platforms:

    • HP-UX PA RISC
    • Solaris x86
    • Solaris SPARC

    JVM support for 32-bit versions of HP-UX PA RISC, Solaris x86, and Solaris SPARC ended with Oracle JDK 7, OpenJDK 7, IBM SDK 7. As a result, the driver can no longer receive updates for these platforms due to the driver’s JVM requirements.