Release Notes for MariaDB Connector/Node.js 3.0.1

This page is part of MariaDB's Documentation.

The parent of this page is: Release Notes for MariaDB Connector/Node.js 3.0

Topics on this page:

Overview
Notable Changes
Issues Fixed
Installation
Upgrade
Resources

Overview

MariaDB Connector/Node.js is the interface between Node.js applications and MariaDB Server. MariaDB Connector/Node.js enables development of Node.js applications.

MariaDB Connector/Node.js 3.0.1 was released on 2022-07-26. This release is of General Availability (GA) maturity.

Notable Changes

MariaDB Connector/Node.js 3.0 supports Node.js 18. (CONJS-197)
The Pool class includes more detailed information about the pool in error messages. (CONJS-208)
- Starting with this release, error messages contain the following details about the pool:
```
(pool connections: active=1 idle=0 limit=1)
```
The Pool class differentiates between errors that occur during pool initialization and errors that occur during connection creation. (CONJS-200)
- Starting with this release, when an error occurs during pool initialization, the error message begins with the following string:
```
Error during pool initialization:
```
- And when an error occurs during connection creation, the error message begins with the following string:
```
Pool fails to create connection:
```
The Pool class implements an error event that can be used to handle errors. (CONJS-200)

The implementation of the trace parameter has been improved, so that the calling method is included in the trace, even when using a pool and when the methods are called asynchronously. (CONJS-209)

When the trace parameter is set to true and the application calls a driver method, the initial call stack is saved using Error.captureStackTrace. When an error occurs, the saved call stack is shown in the stack trace.

For example, consider the following application code:

const pool = mariadb.createPool({
  host: 'mydb.com',
  user: 'myUser',
  connectionLimit: 5,
  trace: true
});

await pool.query('wrong query');

Starting with this release, the stack trace could look like the following:

sql: wrong query - parameters:[]
  at Object.module.exports.createError (errors.js:57:10)
  at ...
From event:
  at Function._PARAM (C:\temp\mariadb-connector-nodejs2\lib\connection-promise.js:104:30)
  at PoolPromise.query (C:\temp\mariadb-connector-nodejs2\lib\pool-promise.js:102:40)
  at Context.<anonymous> (C:\temp\mariadb-connector-nodejs2\test\integration\test-pool.js:60:18)
  at callFn (C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runnable.js:366:21)
  at Test.Runnable.run (C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runnable.js:354:5)
  at Runner.runTest (C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runner.js:678:10)
  at C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runner.js:801:12
  at next (C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runner.js:593:14)
  at C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runner.js:603:7
  at next (C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runner.js:486:14)
  at Immediate.<anonymous> (C:\temp\mariadb-connector-nodejs2\node_modules\mocha\lib\runner.js:571:5)
  at processImmediate (internal/timers.js:464:21) {
text: "You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near 'wrong query' at line 1",
sql: 'wrong query - parameters:[]',
fatal: false,
errno: 1064,
sqlState: '42000',
code: 'ER_PARSE_ERROR'
}
*/

MariaDB recommends setting the trace parameter to false in production environments, because saving the initial call stack incurs extra overhead that can slow down queries.

The checkNumberRange connection parameter has been added for compatibility with Connector/Node.js 2.5 and earlier. (CONJS-198)
- Starting with this release, when checkNumberRange is used in conjunction with decimalAsNumber, insertIdAsNumber or bigIntAsNumber, an error is raised with the following error message if the value can't be converted to a number without losing precision:
```
value BAD_VALUE can't safely be converted to number
```
Performance has been enhanced for result-sets with multiple rows. (CONJS-210)

Issues Fixed

When an error occurs during handshake with the server, an error with a misleading message is raised. (CONJS-193)
- In earlier releases, the following error message would be shown:
```
TypeError: Cannot read properties of undefined (reading 'charset')
```
When the connection character set is changed by executing SET NAMESSET NAMES using a parameterized query, an error is raised. (CONJS-194)
- In earlier releases, the following error message would be shown:
```
Uncaught TypeError: opts.emit is not a function
```
When parsing negative BIGINTBIGINT values, an error is raised. (CONJS-195)
- In earlier releases, the following error message would be shown:
```
TypeError: Cannot mix BigInt and other types, use explicit conversions
```
When a connection is returned to the pool by calling connection.close() instead of connection.release(), the connection is killed instead of being returned to the pool. (CONJS-196)
- MariaDB recommends returning connections to the pool by calling connection.release()
- connection.close() exists for compatibility reasons.
When batch() is called with TypeScript, the wrong type can be returned. (CONJS-199)
When column.geometry() is called and the column's value can't be parsed as a valid geometry value, an error with a misleading message is raised. (CONJS-201)
- In earlier releases, the following error message would be shown:
```
TypeError: column.readGeometry is not a function.
```
When the server raises the ER_CON_COUNT_ERROR error, the error is not properly handled. (CONJS-202)
When changeUser() is called and connection attributes are set, an error with a misleading message is raised. (CONJS-203)
- In earlier releases, the following error message would be shown:
```
Cannot read property 'charset' of undefined
```
When connection.destroy() is called and no other connections can be created (such as when the max_connections has been reached), an error with a misleading message is raised. (CONJS-206)
- In earlier releases, the following error message would be shown:
```
TypeError: Cannot read property 'startPacket' of undefined
  at Quit.start (lib\cmd\quit.js:17:9)
```
When password is provided as an array and authentication occurs with the mysql_clear_password client authentication plugin, authentication fails. (CONJS-204)
- With MariaDB Enterprise Server, the mysql_clear_password client authentication plugin is used when the user account uses the pam authentication plugin and pam_use_cleartext_plugin is enabled. If pam_use_cleartext_plugin is not enabled, the dialog client authentication plugin is used instead.
When the timeout parameter is set and batch() is called, the query hangs, but an error should be raised. (CONJS-205)
- Starting with this release, the following error message is shown:
```
Cannot use timeout for Batch statement
```

Installation

Install MariaDB Connector/Node.js

Upgrade

MariaDB Connector/Node.js 3.0 is fully compatible with MariaDB Connector/Node.js 3.3. As a new fully compatible major version, MariaDB Connector/Node.js 3.3 supersedes MariaDB Connector/Node.js 3.0, and users should upgrade to 3.3.