Release Notes for MariaDB Connector/Node.js 3.0.0

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.0 was released on 2021-06-30. It is a Beta release of MariaDB Connector/Node.js.

Prepared Statements

  • Support added for prepared statements with mysql2 compatible methods.

    • the connection.prepare(sql) Promise method can be used to prepare queries

    • the connection.execute(sql[, values]) Promise method can be used to prepare and execute queries.

    These methods permit the use of streaming parameters and run execute() with a prepared cache length. The default for prepareCacheLength is 256.

connection.prepare(sql)

  • connection.prepare(sql) Promise method will PREPARE a command that can be executed many times.

    • sql: string | JSON SQL string value or JSON object to supersede default connections options. JSON objects must have an sql property. For instance, { dateStrings: true, sql: 'SELECT now()' }

    Returns a promise that:

    • resolves with a PREPARE object

    • rejects with an Error

    The connection.prepare(sql) Promise method requires prepare.close() to properly close the object:

    const prepare = await conn.prepare('INSERT INTO mytable(id,val) VALUES (?,?)');
    await prepare.execute([1, 'val1'])
    prepare.close();
    

connection.execute(sql[, values])

  • connection.execute(sql[, values]) Promise method will PREPARE, EXECUTE, and CLOSE a command. The connection.execute method is most useful if the command will be used often and if prepare cache is enabled (default). If the PREPARE result is already in cache, only the EXECUTE command is executed. MariaDB server 10.6 will avoid re-sending result-set metadata if it has not changed, permitting even faster results.

    • sql: string | JSON SQL string or JSON object to supersede default connection options. When using JSON object, object must have a sql key. For instance, { dateStrings: true, sql: 'SELECT now()' }

    • values: array | object Defines placeholder values. Usually an array, but in cases of only one placeholder, can be given as a string.

    Returns a promise that:

    • resolves with a JSON object for UPDATE, INSERT, or DELETE statements or a result-set object for result-set

    • rejects with an Error

    const res = await conn.execute('SELECT * FROM mytable WHERE someVal = ? and otherVal = ?', [1, 'val1']);
    

Data Types

  • DECIMAL data types now return as JavaScript String objects, instead of Number objects.

  • BIGINT data types now return as JavaScript BigInt objects, instead of Number objects.

Connection Options

  • Adds insertAsNumber connection option. When set to true, insertAsNumber causes the last insert ID's from INSERT and UPDATE statements to return as JavaScript Number objects, instead of the default BigInt objects, for backwards compatibility.

  • Adds decimalAsNumber connection option. When set to true, decimalAsNumber causes DECIMAL data types to return as Number objects instead of String objects, for backwards compatibility.

  • Adds bigIntAsNumber connection option. When set to true, bigIntAsNumber causes BIGINT data types to return as Number objects, instead of the default BigInt object, for backwards compatibility.

  • Deprecates supportBigNumbers connection option.

  • Deprecates bigNumberStrings connection option.

  • Adds support in logger connection option for mapping logs to an external logger. This option uses the network() function to log each network exchange, query() to log each SQL query, and error() to log each error.

Migration

Default behavior for decoding BIGINT / DECIMAL datatype for MariaDB Connector/Node.js version 2.x and mysql/mysql2 drivers return a JavaScript Number object. BIGINT / DECIMAL values might not be in the safe range, resulting in approximate results.

MariaDB Connector/Node.js version 3.x returns a reliable default, returning:

  • DECIMAL => JavaScript String

  • BIGINT => JavaScript BigInt object

For compatibility with previous version or mysql/mysql driver, 3 options have been added to return BIGINT / DECIMAL as number, as previous defaults.

Option

Description

Type

Default

insertIdAsNumber

Whether the query should return last insert id from an INSERT or UPDATE command as BIGINT or NUMBER, default is to return BIGINT

boolean

false

decimalAsNumber

Whether the query should return DECIMAL as NUMBER. If enabled, this might return approximate values

boolean

false

bigIntAsNumber

Whether the query should return BIGINT data type as NUMBER. If enabled, this might return approximate values

boolean

false

Installation