Upgrade from MariaDB Connector/Node.js 2.5 to 3.0

Overview

When upgrading from MariaDB Connector/Node.js 2.5 to 3.0, application code must be updated to reflect changes in connector behavior.

Exact Decoding for BIGINT and DECIMAL

The default behavior for MariaDB Connector/Node.js 2.5 (and for other existing drivers like mysql2) for decoding the data types BIGINTBIGINT and DECIMALDECIMAL is to return a JavaScript Number object. JavaScript uses double-precision floating-point format numbers as specified in IEEE 754, which is returning approximate results for big values.

Integers can only be safely represented between -(2^53 - 1) and 2^53 - 1.

MariaDB Connector/Node.js 3.0, to return precise values, by default returns the objects:

  • DECIMAL => JavaScript String object

  • BIGINT => JavaScript BIGINTBIGINT

For compatibility reasons three options have been added to return BIGINT / DECIMAL as a number object:

Options

Description

Type

Default

insertIdAsNumber

Whether the query should return the last insert id from INSERT/UPDATE command as BigInt or NUMBER. Default 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

checkNumberRange

Used in conjunction with decimalAsNumber, insertIdAsNumber or bigIntAsNumber to determine if an error should be raised when a value can't be converted to a number without losing precision.

boolean

false

Previous options supportBigNumbers and bigNumberStrings still exist for compatibility, but are now deprecated.

Custom Logging API

External logging can now be easily enabled using the new logging API, provided with MariaDB Connector/Node.js 3.0 via the three caller functions:

  • network(string): called for each network exchange.

  • query(string): called for each command.

  • error(Error): called for each error.

Simple example to log network exchanges, queries, and errors:

const pool = mariadb.createPool({
  host: 'mydb.com',
  user:'myUser',
  password: 'myPwd',
  logger: (msg) => console.log(msg)
});

Example of a more detailed use:

const mariadb = require('mariadb');
const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  transports: [
    // - Write all logs with level `error` and below to `error.log`
    // - Write all logs with level `info` and below to `combined.log`
    new winston.transports.Console({ filename: 'error.log', level: 'error' }),
    new winston.transports.Console({ filename: 'combined.log' })
  ]
});

const pool = mariadb.createPool({
  host: 'mydb.com',
  user: 'myUser',
  password: 'myPwd',
  logger: {
    query: (msg) => logger.info(msg),
    error: (err) => logger.error(err),
  }
});

Options

Changes to Default Values

Option

Old Default Value

New Default Value

removeNodeErrorCount

5

Infinity

resetAfterUse

true

false

New Options

Option

Description

Data Type

Default Value

stream

permits to set a function with parameter to set stream

function

null

insertIdAsNumber

Whether the query should return the last insert id from INSERT/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

checkNumberRange

Used in conjunction with decimalAsNumber, insertIdAsNumber or bigIntAsNumber to determine if an error should be raised when a value can't be converted to a number without losing precision.

boolean

false

Deprecated Options

Deprecated Option

Upgrade Guidance

supportBigNumbers

BigInt is now supported. Applications must use BigInt compared to using the external Long package.

bigNumberStrings

BigInt is now supported. Applications must use BigInt compared to using String value for a big number.