MySQL 9.0 Reference Manual Including MySQL NDB Cluster 9.0

27.3.4 JavaScript Stored Program Data Types and Argument Handling

Most MySQL data types are supported for MLE stored program input and output arguments, as well as for return data types. The data types are listed here:

Input arguments (IN and INOUT parameters) are automatically converted into JavaScript types based on the mapping shown in the following table:

Table 27.1 Type Conversion: MySQL to JavaScript

MySQL TypeJavaScript Type
TINYINT, SMALLINT, MEDIUMINT, INT, BOOL, BIGINT, or SERIALIf safe: Number; otherwise: String
FLOAT or DOUBLENumber
CHAR, VARCHAR, TINYTEXT, TEXT, MEDIUMTEXT, or LONGTEXTString
TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB, BINARY, or VARBINARYUint8Array
DATE, DATETIME, or TIMESTAMPDate
TIMEString
YEARNumber

Conversion to or from a MySQL integer whose value lies outside the range -(253-1) (-9007199254740991) to 253-1 (9007199254740991) is lossy. How conversion from MySQL integers to JavaScript is performed can be changed for the current session using mle_set_session_state(); the default behavior is equivalent to calling this function using UNSAFE_STRING as the value for integer_type. See the description of that function for more information.

SQL NULL is supported for all the types listed, and is converted to and from JavaScript null as required.

JavaScript (unlike SQL) is a dynamically typed language, which means that return types are known only at execution time. JavaScript return value and output arguments (OUT and INOUT parameters) are automatically converted back into the expected MySQL type based on the mappings shown in the following table:

Table 27.2 Type Conversion: JavaScript to MySQL

From JavaScript TypeTo MySQL TINYINT, SMALLINT, MEDIUMINT, INT, BIGINT, BOOLEAN, or SERIALTo MySQL CHAR or VARCHARTo MySQL FLOAT or DOUBLETo MySQL TINYTEXT, TEXT, MEDIUMTEXT, or LONGTEXTTo MySQL TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB, BINARY, VARBINARY
BooleanCast to IntegerConvert to string; check whether length of result is within expected rangeCast to FloatIf JavaScript Boolean true: convert to true; If JavaScript Boolean false: convert to falseError
NumberRound value to Integer; check whether value is out of range [a] [b] [c]Convert to String; check whether length of result is within expected rangeRetain value; check whether this is out of range [a] [b]Convert to String; check whether length of result is within expected rangeError
BigIntegerRetain value; check whether out of range [a] [b]Convert to String; check whether length of result is within expected rangeCast to Float; check whether result is out of range [d]Convert to String; check whether length of result is within expected rangeError
StringParse as number and round to Integer; check for out value of rangeRetain value; check whether length is within rangeParse value to Float, check for value out of range values [d]Use existing string value; check whether length of string is within expected rangeError
Symbol or ObjectRaise invalid type conversion errorConvert to String; check whether length of result is within expected rangeRaise invalid type conversion errorConvert to String; check whether length of result is within expected range [e]Error
Typed ArrayRaise invalid type conversion errorConvert to String; check whether length of result is within expected rangeRaise invalid type conversion errorConvert to String; check whether length of result is within expected range [e]Convert to byte array; check whether result is within expected size [f]
null or undefinedNULLNULLNULLNULLNULL

[a] JavaScript Infinity and -Infinity are treated as out-of-range values.

[b] JavaScript NaN raises an invalid type conversion error.

[c] This is done using Math.round().

[d] A non-numeric value raises an invalid type conversion error

[e] Maximum supported string length is 1073741799

[f] Maximum supported BLOB length is 2147483639


Table 27.3 Type Conversion: JavaScript Dates to MySQL

JavaScript TypeMySQL DATEMySQL DATETIME, TIMESTAMPMySQL YEAR
null or undefinedNULLNULLNULL
DateRetain value as is, rounding off any time part to the closest second.Keep value as is.Extract year from the Date
Type convertible to JavaScript Date (formatted string)Cast value to JavaScript Date and handle accordinglyCast value to JavaScript Date and handle accordinglyIf value contains 4-digit year, use it.
Type not convertible to JavaScript DateInvalid type conversion errorInvalid type conversion errorIf value contains 4-digit year, use it.

Passing a MySQL zero date (00-00-0000) or zero-in-date value (such as 00-01-2023) leads to the creation of an Invalid Date instance of Date. When passed a MySQL date which is invalid (for example, 31 February), MLE calls a JavaScript Date constructor with invalid individual date and time component values.

The MySQL TIME type is handled as a string, and is validated inside MySQL. See Section 13.2.3, “The TIME Type”, for more information.

Table 27.4 Type Conversion: MySQL JSON to JavaScript

MySQL JSON TypeJavaScript Type
NULL, JSON NULLnull
JSON OBJECTObject
JSON ARRAYArray
JSON BOOLEANBoolean
JSON INTEGER, JSON DOUBLE, JSON DECIMALNumber
JSON STRINGString [a]
JSON DATETIME, JSON DATE, JSON TIMEString
JSON BLOB, JSON OPAQUEString

[a] A MySQL JSON string, when converted to a Javascript string, becomes unquoted.


Table 27.5 Type Conversion: JavaScript to MySQL JSON

JavaScript TypeMySQL JSON Type
null, undefinedNULL
BooleanError [a]
NumberError [f]
String
  • Can be parsed as JSON: JSON string, JSON object, or JSON array

  • Cannot be parsed as JSON: Error

  • 'null': JSON null

BigIntError [b]
ObjectJSON object or error (see text following table)
ArrayJSON array
Symbol
  • Inside an object: ignored

  • Inside an array: JSON null

Scalar value: Error

[a] A value within a container such as a JSON array or JSON object is converted (loss of precision is possible for Number values). A scalar value throws an error.

[b] JavaScript BigInt values cannot be converted to MySQL JSON; attempting to perform such a conversion always raises an error, regardless of whether the value is inside a container or not.


It may or may not be possible to convert a Javascript Object to MySQL JSON, depending on how toJSON() is implemented for the object in question. Some examples are listed here:

Time zone support.  A JavaScript stored program uses the MySQL session timezone in effect at the time it is first invoked. This time zone remains in effect for this stored program for the duration of the session in the session.

Changing the MySQL session time zone is not automatically reflected in stored programs which have been used and thus are already cached. To make them use the new time zone, call mle_session_reset() to clear the cache; after this, stored programs use the new time zone.

Supported time zone types are listed here:

Range checks and invalid type conversion checks are performed following stored program execution. Casting is done inside JavaScript using type constructors such as Number() and String(); rounding to Integer is performed using Math.round().

An input argument (IN or INOUT parameter) named in a JavaScript stored program definition is accessible from within the routine body using the same argument identifier. Output arguments (INOUT and OUT parameters) are also available in JavaScript stored procedures. The same argument identifier can be used to set the value using the JavaScript assignment (=) operator. As with SQL stored procedure OUT arguments, the initial value is set to JavaScript null.

Caution

You should not override program arguments using let, var, or const inside JavaScript stored programs. Doing so turns them into variables which are local to the program, and makes any values passed into the program using the same-named parameters inaccessible.

Example:

mysql> CREATE FUNCTION myfunc(x INT)
    ->   RETURNS INT LANGUAGE JAVASCRIPT AS
    -> $$
    $>   var x
    $>   
    $>   return 2*x
    $> $$
    -> ;
Query OK, 0 rows affected (0.03 sec)

mysql> SELECT myfunc(10);
ERROR 6000 (HY000): MLE-Type> Cannot convert value 'NaN' to INT 
from MLE in 'myfunc(10)'

The JavaScript return statement should be used to return scalar values in stored functions. In stored procedures, this statement does not return a value, and merely exits the code block (this may or may not also exit the routine depending on program flow). return cannot be used to set stored procedure OUT or INOUT argument values; these must be set explicitly within the routine.