27.3.4 JavaScript Stored Program Data Types and Argument Handling

27.3.4 JavaScript Stored Program Data Types and Argument Handling

대부분의 MySQL 데이터 타입은 MLE 스토어드 프로그램의 입력 및 출력 인자, 그리고 반환 데이터 타입으로 지원됩니다. 해당 데이터 타입은 다음과 같습니다:

• Integer: MySQL 정수 데이터 타입의 모든 변형 및 별칭이 지원되며, 다음을 포함합니다: TINYINT, SMALLINT, MEDIUMINT, INT, 및 BIGINT.

SIGNED 및 UNSIGNED는 이 모든 타입에 대해 지원됩니다.

BOOL 및 SERIAL 역시 지원되며, 정수 타입으로 취급됩니다.

• String: CHAR, VARCHAR, TEXT, 및 BLOB 문자열 타입이 지원됩니다.

이들 타입은 다음 예외 사항을 제외하고 MySQL 서버에서와 동일하게 지원됩니다:

1. 문자열 인자 및 반환 타입은 utf8mb4 또는 바이너리 문자 집합을 사용할 수 있습니다. 다른 문자 집합을 사용하는 경우 오류가 발생합니다. 이 제한은 인자 및 반환 타입 선언에 적용됩니다. 서버는 SQL 스토어드 프로그램과 마찬가지로, 필요한 경우 다른 문자 집합을 사용하는 인자 값 을 utfmb4로 변환하려고 시도합니다.

2. LONGTEXT 값의 최대 지원 길이는 1073741799 (2⁳⁰ - 2²⁴ - 2²³ - 1) 문자입니다. LONGBLOB의 경우 최대 지원 길이는 2147483639 (2³¹ - 2²⁸ - 1)입니다.

BLOB 타입에 대한 지원에는 BINARY 및 VARBINARY에 대한 지원도 포함됩니다.

MySQL JSON 데이터 타입 역시 지원됩니다.

• Floating point: FLOAT 및 DOUBLE가 해당 별칭과 함께 지원됩니다. REAL 역시 부동소수점으로 처리되지만, UNSIGNED FLOAT 및 UNSIGNED DOUBLE은 MySQL에서 더 이상 사용되지 않으며, MLE에서는 지원되지 않습니다.

• Temporal types: DATE, DATETIME, 및 TIMESTAMP가 지원되며, JavaScript Date 값으로 변환됩니다. TIME 값은 문자열로 처리됩니다. YEAR 값은 숫자형으로 처리됩니다.

특정 JavaScript 스토어드 프로시저가 처음 실행되는 시점에, 해당 프로시저는 현재 MySQL 세션 타임존과 연관되며, 이 타임존은 MLE 컴포넌트 세션이 지속되는 동안, 또는 mle_session_reset()이 호출될 때까지, MySQL 세션 타임존이 동시에 변경되더라도, 스토어드 프로그램에서 계속 사용됩니다. 자세한 내용은 이 섹션의 뒷부분에 있는 Time zone support를 참조하십시오.

• VECTOR, DECIMAL, NUMERIC, 및 BIT 타입은 모두 MySQL 9.5에서 지원됩니다.

입력 인자(IN 및 INOUT 파라미터)는 아래 표에 제시된 매핑에 따라 JavaScript 타입으로 자동 변환됩니다:

Table 27.1 Conversion of MySQL data types to JavaScript types

MySQL Type	JavaScript Type
TINYINT, SMALLINT,<br> MEDIUMINT, INT,<br> BOOL, BIGINT, or<br> SERIAL	안전한 경우: Number; 그렇지 않으면: String
FLOAT or DOUBLE	Number
CHAR, VARCHAR,<br> TINYTEXT, TEXT,<br> MEDIUMTEXT, or<br> LONGTEXT	String
TINYBLOB, BLOB,<br> MEDIUMBLOB, LONGBLOB,<br> BINARY, or VARBINARY	Uint8Array
DATE, DATETIME, or<br> TIMESTAMP	Date
TIME	String
YEAR	Number
VECTOR	Float32Array
DECIMAL	session.options.decimalType 값<br> (STRING 또는 NUMBER)에 따라 String 또는 Number. 기본값은 String으로 변환.
BIT(M)	- BIT(M)<br><= JavaScript.MAX_SAFE_INTEGER:<br>Number<br><br>- BIT(M)<br>> JavaScript.MAX_SAFE_INTEGER:<br>BigInt

MySQL Type	JavaScript Type

값이 -(2⁵³-1) (-9007199254740991)에서 2⁵³-1 (9007199254740991) 범위를 벗어나는 MySQL 정수로 변환하거나 이로부터 변환하는 경우, 손실이 발생합니다. MySQL 정수에서 JavaScript로의 변환 방식은 mle_set_session_state()를 사용하여 현재 세션에 대해 변경할 수 있습니다.

기본 동작은 이 함수에 integer_type 값으로 UNSAFE_STRING을 사용하여 호출한 것과 동일합니다. 자세한 내용은 해당 함수 설명을 참조하십시오.

SQL NULL은 나열된 모든 타입에 대해 지원되며, 필요에 따라 JavaScript null로 변환되거나 그 반대로 변환됩니다.

JavaScript는 (SQL과 달리) 동적 타입 언어이며, 이는 반환 타입이 실행 시점에만 알려진다는 것을 의미합니다.

JavaScript 반환 값 및 출력 인자 (OUT 및 INOUT 파라미터)는 아래 표에 제시된 매핑에 따라 예상되는 MySQL 타입으로 자동 변환됩니다:

Table 27.2 Type Conversion: JavaScript to MySQL

From JavaScript Type	To MySQL TINYINT, SMALLINT,<br> MEDIUMINT, INT,<br> BIGINT, BOOLEAN, or<br> SERIAL	To MySQL CHAR or VARCHAR	To MySQL FLOAT or DOUBLE	To MySQL TINYTEXT, TEXT,<br> MEDIUMTEXT, or<br> LONGTEXT	To MySQL TINYBLOB, BLOB,<br> MEDIUMBLOB,<br> LONGBLOB, BINARY,<br> VARBINARY	To MySQL VECTOR	To MySQL DECIMAL (NUMERIC)	To MySQL BIT
Boolean	Integer로 캐스팅	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	Float로 캐스팅	JavaScript Boolean``true인 경우:<br> “true”로 변환; JavaScript<br> Boolean``false인 경우:<br> “false”로 변환	Error	Error	Decimal로 변환	Bit로 변환
Number	값을 Integer로 반올림; 범위 초과 여부 확인	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	값을 유지; 범위 초과 여부 확인	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	Error	Error	Decimal로 변환	Bit로 변환
BigInteger	값을 유지; 범위 초과 여부 확인	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	Float로 캐스팅; 결과가 범위 초과인지 확인	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	Error	Error	Decimal로 변환	Bit로 변환
String	숫자로 parse하여 Integer로 반올림; 범위 초과 값인지 확인	값을 유지; 길이가 범위 내인지 확인	값을 Float로 parse; 범위 초과 값인지 확인	기존 string 값을 사용; string 길이가<br> 예상 범위 내인지 확인	Error	Error	Decimal로 변환	Bit로 변환
Symbol or Object	잘못된 타입 변환 오류 발생	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	잘못된 타입 변환 오류 발생	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	Error	Error	Error	Error
Typed Array	잘못된 타입 변환 오류 발생	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	잘못된 타입 변환 오류 발생	String으로 변환; 결과 길이가<br> 예상 범위 내인지 확인	byte array로 변환; 결과가 예상 크기 내인지 확인	Float32Array로 취급; byte array로 변환하며,<br> 예상 VECTOR 필드 크기 내인지 확인	Error	Error
null or undefined	NULL	NULL	NULL	NULL	NULL	NULL	NULL	NULL

Notes:

• JavaScript Infinity 및 -Infinity는 범위를 벗어난 값으로 처리됩니다.

• JavaScript NaN은 잘못된 타입 변환 오류를 발생시킵니다.

• 모든 반올림은 Math.round()를 사용하여 수행됩니다.

• MySQL FLOAT로 BigInt 또는 비숫자 값을 갖는 String을 캐스팅하려는 시도는 항상 잘못된 타입 변환 오류를 발생시킵니다.

• 문자열의 최대 지원 길이는 1073741799입니다.

• BLOB 값의 최대 지원 길이는 2147483639입니다.

• JavaScript.MAX_SAFE_INTEGER는 9007199254740991 (2⁵³-1)과 같습니다.

Table 27.3 Type Conversion: JavaScript Dates to MySQL

JavaScript Type	MySQL DATE	MySQL DATETIME, TIMESTAMP	MySQL YEAR
null or undefined	NULL	NULL	NULL
Date	time 부분을 가장 가까운 초 단위로 반올림하여 값을 그대로 유지	값을 그대로 유지	Date에서 year를 추출
JavaScript Date로 변환 가능한 타입 (형식화된<br>string)	값을 JavaScript Date로 캐스팅하고 이에 따라 처리	값을 JavaScript Date로 캐스팅하고 이에 따라 처리	값에 4자리 year가 포함되어 있으면 이를 사용
JavaScript Date로 변환할 수 없는 타입	잘못된 타입 변환 오류	잘못된 타입 변환 오류	값에 4자리 year가 포함되어 있으면 이를 사용

MySQL zero date (00-00-0000) 또는 zero-in-date 값(예: 00-01-2023)을 전달하면 Date의 Invalid Date 인스턴스가 생성됩니다.

잘못된 MySQL date(예: 2월 31일)가 전달되면, MLE는 잘못된 개별 date 및 time 구성 요소 값을 사용하여 JavaScript Date 생성자를 호출합니다.

MySQL TIME 타입은 문자열로 처리되며, MySQL 내부에서 검증됩니다. 더 자세한 내용은 Section 13.2.3, “The TIME Type”을 참조하십시오.

Table 27.4 Conversion of MySQL JSON types to JavaScript

MySQL JSON Type	JavaScript Type
NULL, JSON NULL	null
JSON OBJECT	Object
JSON ARRAY	Array
JSON BOOLEAN	Boolean
JSON INTEGER, JSON DOUBLE,<br> JSON DECIMAL	Number
JSON STRING	String
JSON DATETIME, JSON DATE,<br> JSON TIME	String
JSON BLOB, JSON OPAQUE	String

참고

MySQL JSON 문자열이 JavaScript 문자열으로 변환될 때, 따옴표는 제거됩니다.

Table 27.5 Conversion of JavaScript types to MySQL JSON

JavaScript Type	MySQL JSON Type
null, undefined	NULL
Boolean	Error
Number	Error
String	- JSON으로 parse 가능한 경우: JSON string, JSON object, 또는<br>JSON array<br><br>- JSON으로 parse 불가능한 경우: Error<br><br>- 'null': JSON<br>null
BigInt	Error
Object	JSON object 또는 error (표 아래 텍스트 참조)
Array	JSON array
Symbol	- object 내부: 무시됨<br><br>- array 내부: JSON null<br><br>단독 scalar 값: Error

Notes:

• JSON array 또는 JSON object와 같은 컨테이너 내부의 값은 변환됩니다(Number 값의 경우 정밀도 손실 가능성이 있음). 단독 스칼라 값은 error를 발생시킵니다.

• JavaScript BigInt 값은 MySQL JSON으로 변환할 수 없습니다. 이러한 변환을 시도하면, 값이 컨테이너 내부에 있는지 여부와 무관하게 항상 error가 발생합니다.

• JavaScript Object를 MySQL JSON으로 변환할 수 있는지는 해당 object에 대해 toJSON()이 어떻게 구현되어 있는지에 따라 달라집니다. 몇 가지 예는 다음과 같습니다:

  • JavaScript Date 클래스의 toJSON() 메서드는 Date를 invalid JSON 문법을 갖는 문자열로 변환하므로, 변환 error를 발생시킵니다.

  • Set 클래스의 경우, toJSON()은 "{}"를 반환하며, 이는 유효한 JSON 문자열입니다.

  • JSON 유사 object의 경우, toJSON()은 유효한 JSON 문자열을 반환합니다.

Conversion to and from MySQL ENUM and SET. ENUM은 JavaScript String으로 변환되며, SET은 JavaScript Set object로 변환됩니다. 다음 표와 같습니다:

Table 27.6 Conversion of the MySQL ENUM and SET types to JavaScript

MySQL Type	JavaScript Type
ENUM	String
SET	Set

다음 표는 JavaScript 타입을 MySQL ENUM 또는 SET 타입으로 변환하는 규칙을 보여줍니다:

Table 27.7 Type Conversion: JavaScript types to MySQL ENUM and SET

JavaScript Type	To MySQL ENUM	To MySQL SET
String	값을 유지; string이 유효한 ENUM 값인지 확인	값을 유지; string이 유효한 SET 값인지 확인
null, undefined	NULL	NULL
Set	Error	comma로 구분된 string으로 변환; string이 유효한<br>SET 값인지 확인
Any other type	Error	Error

Additional notes

• ENUM 또는 SET 값이나 그 JavaScript 대응 값에 사용되는 모든 값은 utf8mb4 문자 집합을 사용해야 합니다. 자세한 내용은 Section 12.9.1, “The utf8mb4 Character Set (4-Byte UTF-8 Unicode Encoding)”을 참조하십시오.

• 서버 SQL 모드는 JavaScript의 잘못된 값을 ENUM 또는 SET 컬럼에 삽입하려 할 때 어떻게 처리되는지에 영향을 줄 수 있습니다. strict 모드(기본값)가 설정된 경우, 잘못된 값은 error를 발생시킵니다. 그렇지 않으면, 빈 문자열이 warning과 함께 삽입됩니다. Section 7.1.11, “Server SQL Modes”를 참조하십시오.

Conversion to and from MySQL DECIMAL and NUMERIC. MySQL decimal 타입(DECIMAL 및 NUMERIC)은 session.options.decimalType (STRING 또는 NUMBER) 값에 따라 JavaScript String 또는 Number로 변환됩니다. 기본 동작은 해당 값을 String으로 변환하는 것입니다.

MySQL decimal 타입이 기본적으로 Number로 변환되도록 세션 레벨에서 이 변수를 설정하려면, 다음과 같이 mle_set_session_state()를 호출하십시오:

1mle_set_session_state("decimalType":"NUMBER")

이 함수가 호출될 때 MLE 스토어드 프로그램 캐시는 비어 있어야 합니다. 비어 있지 않은 경우 mle_session_reset()을 사용하여 캐시를 비울 수 있습니다. 자세한 내용은 mle_set_session_state() 설명을 참조하십시오.

JavaScript 스토어드 루틴 내에서 decimalType 옵션을 설정하려면, 다음과 같이 Session.setOptions()를 사용하십시오:

1session.setOptions('{"decimalType":"mysql.DecimalType.NUMBER"}')

이 설정은 루틴의 lifetime 동안 MySQL decimal 값을 Number로 변환하는 기본값을 지정합니다. mysql.DecimalType.STRING을 사용하면 String을 기본값으로 지정합니다.

JavaScript 값을 MySQL DECIMAL 타입(또는 그 별칭 NUMERIC)으로 변환하는 규칙은 다음 표와 같습니다:

Table 27.8 Type Conversion: JavaScript types to MySQL DECIMAL

JavaScript Type	Returns
Object, Array, or<br> Symbol	Error: Conversion not supported
Boolean, Number,<br>String, or BigInt	DECIMAL value
null, undefined	SQL NULL

decimal 값이 가질 수 있는 최대치는 DECIMAL(M, D)의 정밀도와 스케일에 의해 결정됩니다. 여기서 M 은 정밀도(최대 자릿수)로 1–65 범위를 가지며, D 는 소수점 오른쪽 자릿수로 0–30 범위를 가집니다. 또한 M 은 D 이상이어야 합니다. (자세한 내용은 Section 13.1.3, “Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC”을 참조하십시오.)

decimal 값이 DECIMAL(M, D)에 의해 지정된 범위를 초과하거나, DECIMAL(M, D)의 제약 조건 내에 저장될 수 없는 경우, 동작은 서버 SQL 모드에 따라 달라집니다( Section 7.1.11, “Server SQL Modes” 참조):

• Strict SQL Mode: error가 발생하고, 작업이 실패합니다.

• 그 외: 값은 지정된 범위의 가장 가까운 유효한 최소값 또는 최대값으로 자동 보정되며, warning이 발생합니다.

Time zone support. JavaScript 스토어드 프로그램은 처음 호출되는 시점에 유효한 MySQL 세션 타임존을 사용합니다. 이 타임존은 세션이 지속되는 동안 해당 스토어드 프로그램에 대해 계속 유효하게 유지됩니다.

MySQL 세션 타임존을 변경해도, 이미 사용되어 캐시에 있는 스토어드 프로그램에는 자동으로 반영되지 않습니다. 이들이 새로운 타임존을 사용하게 하려면, mle_session_reset()을 호출하여 캐시를 비워야 합니다. 이후 스토어드 프로그램은 새로운 타임존을 사용합니다.

지원되는 타임존 타입은 다음과 같습니다:

• +11:00 또는 -07:15와 같은 UTC 기준 타임존 오프셋.

• IANA time zone database에 정의된 타임존이 지원되며, leap second를 사용하는 구성은 예외입니다. 예를 들어, Pacific/Nauru, Japan, MET은 지원되지만, leap/Pacific/Nauru 및 right/Pacific/Nauru는 지원되지 않습니다.

범위 검사 및 잘못된 타입 변환 검사는 스토어드 프로그램 실행 후 수행됩니다. 캐스팅은 Number() 및 String()과 같은 JavaScript 타입 생성자를 사용하여 수행되며, Integer로의 반올림은 Math.round()를 사용하여 수행됩니다.

JavaScript 스토어드 프로그램 정의에 명시된 입력 인자 (IN 또는 INOUT 파라미터)는 루틴 본문 내에서 동일한 인자 식별자를 사용하여 접근할 수 있습니다. 출력 인자 (INOUT 및 OUT 파라미터) 역시 JavaScript 스토어드 프로시저에서 사용할 수 있습니다. 동일한 인자 식별자를 사용하여 JavaScript 대입(=) 연산자로 값을 설정할 수 있습니다.

SQL 스토어드 프로시저의 OUT 인자와 마찬가지로, 초기 값은 JavaScript null로 설정됩니다.

주의

JavaScript 스토어드 프로그램 내부에서 let, var, 또는 const를 사용하여 프로그램 인자를 재정의해서는 안 됩니다. 이렇게 하면 인자가 프로그램의 로컬 변수로 변경되어, 동일한 이름의 파라미터를 통해 프로그램으로 전달된 값에 접근할 수 없게 됩니다.

Example:

1mysql> CREATE FUNCTION myfunc(x INT)
2    ->   RETURNS INT LANGUAGE JAVASCRIPT AS
3    -> $$
4    $>   var x
5    $>
6    $>   return 2*x
7    $> $$
8    -> ;
9Query OK, 0 rows affected (0.03 sec)
10
11mysql> SELECT myfunc(10);
12ERROR 6000 (HY000): MLE-Type> Cannot convert value 'NaN' to INT
13from MLE in 'myfunc(10)'

JavaScript return 문은 스토어드 함수에서 스칼라 값을 반환하는 데 사용해야 합니다. 스토어드 프로시저에서 이 문은 값을 반환하지 않으며, 단지 코드 블록을 종료할 뿐입니다 (이는 프로그램 흐름에 따라 루틴을 종료할 수도 있고 그렇지 않을 수도 있습니다).

return은 스토어드 프로시저의 OUT 또는 INOUT 인자 값을 설정하는 데 사용할 수 없으며, 이 값들은 루틴 내부에서 명시적으로 설정해야 합니다.

JavaScript 스토어드 루틴 내부에서 MySQL 스토어드 프로시저 및 스토어드 함수에 접근하는 방법에 대한 정보는 Section 27.3.6.10, “Stored Routine API”를 참조하십시오.