文件首頁
MySQL 9.0 參考手冊
相關文件
MySQL 9.0 發行說明
下載本手冊
PDF (美式信紙) - 40.0Mb
PDF (A4) - 40.1Mb
Man Pages (TGZ) - 258.2Kb
Man Pages (Zip) - 365.3Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb
MySQL 9.0 參考手冊  /  ...  /  JavaScript 儲存程式資料類型與引數處理

27.3.4 JavaScript 儲存程式資料類型與引數處理

大多數 MySQL 資料類型都支援用於 MLE 儲存程式的輸入和輸出引數，以及傳回資料類型。資料類型在此列出

  • 整數：支援所有 MySQL 整數資料類型的變體和別名，包括 TINYINT、SMALLINT、MEDIUMINT、INT 和 BIGINT。

    所有這些類型都支援 SIGNED 和 UNSIGNED。

    也支援 BOOL 和 SERIAL，並將它們視為整數類型。

  • 字串：支援 CHAR、VARCHAR、TEXT 和 BLOB 字串類型。

    這些類型的支援方式與 MySQL 伺服器相同，但有以下例外

    1. 字串引數和傳回類型必須使用 utf8mb4 字元集；對這些使用任何其他字元集都會引發錯誤。此限制適用於引數和傳回類型宣告；伺服器會嘗試根據需要將其他字元集的引數值轉換為 utfmb4，如同使用 SQL 儲存程式一樣。

    2. 支援的 LONGTEXT 值的最大長度為 1073741799 個字元。

    對 BLOB 類型的支援包括對 BINARY 和 VARBINARY 的支援。

    也支援 MySQL JSON 資料類型。

  • 浮點數：支援 FLOAT 和 DOUBLE 及其別名。REAL 也被視為浮點數，但 UNSIGNED FLOAT 和 UNSIGNED DOUBLE 在 MySQL 中已過時，並且 MLE 不支援它們。

  • 時間類型：支援 DATE、DATETIME 和 TIMESTAMP，並將它們轉換為 JavaScript Date 值。TIME 值被視為字串；YEAR 值被視為數字。

    第一次執行指定的 JavaScript 儲存程序時，它會與目前的 MySQL 會話時區相關聯，並且此時區會繼續由儲存程式使用，即使 MySQL 會話時區同時發生變更，也會在 MLE 元件會話的持續時間內，或直到調用 mle_session_reset() 為止。如需更多資訊，請參閱本節稍後的時區支援。

根據下表所示的對應，輸入引數（IN 和 INOUT 參數）會自動轉換為 JavaScript 類型

表 27.1 類型轉換：MySQL 至 JavaScript

MySQL 類型JavaScript 類型
TINYINT、SMALLINT、MEDIUMINT、INT、BOOL、BIGINT 或 SERIAL如果安全：Number；否則：String
FLOAT 或 DOUBLENumber
CHAR、VARCHAR、TINYTEXT、TEXT、MEDIUMTEXT 或 LONGTEXTString
TINYBLOB、BLOB、MEDIUMBLOB、LONGBLOB、BINARY 或 VARBINARYUint8Array
DATE、DATETIME 或 TIMESTAMPDate
TIMEString
YEARNumber

轉換自或轉換為值超出範圍 -(253-1) (-9007199254740991) 到 253-1 (9007199254740991) 的 MySQL 整數會造成資訊遺失。可以使用 mle_set_session_state() 為目前的連線變更從 MySQL 整數到 JavaScript 的轉換方式；預設行為等同於使用 UNSAFE_STRING 作為 integer_type 的值來呼叫此函式。如需更多資訊，請參閱該函式的說明。

所有列出的類型都支援 SQL NULL，並根據需要轉換為 JavaScript null 和從 JavaScript null 轉換。

JavaScript（與 SQL 不同）是一種動態類型語言，這表示只有在執行時才知道傳回類型。JavaScript 傳回值和輸出引數（OUT 和 INOUT 參數）會根據下表所示的對應自動轉換回預期的 MySQL 類型。

表 27.2：類型轉換：JavaScript 到 MySQL

從 JavaScript 類型轉換為 MySQL TINYINT、SMALLINT、MEDIUMINT、INT、BIGINT、BOOLEAN 或 SERIAL轉換為 MySQL CHAR 或 VARCHAR轉換為 MySQL FLOAT 或 DOUBLE轉換為 MySQL TINYTEXT、TEXT、MEDIUMTEXT 或 LONGTEXT轉換為 MySQL TINYBLOB、BLOB、MEDIUMBLOB、LONGBLOB、BINARY、VARBINARY
布林值轉換為整數轉換為字串；檢查結果長度是否在預期範圍內轉換為浮點數如果 JavaScript 布林值為 true：轉換為 「true」；如果 JavaScript 布林值為 false：轉換為 「false」錯誤
Number將值四捨五入為 Integer；檢查值是否超出範圍 [a] [b] [c]轉換為 String；檢查結果長度是否在預期範圍內保留值；檢查此值是否超出範圍 [a] [b]轉換為 String；檢查結果長度是否在預期範圍內錯誤
BigInteger保留值；檢查是否超出範圍 [a] [b]轉換為 String；檢查結果長度是否在預期範圍內轉換為浮點數；檢查結果是否超出範圍 [d]轉換為 String；檢查結果長度是否在預期範圍內錯誤
String剖析為數字並四捨五入為整數；檢查值是否超出範圍保留值；檢查長度是否在範圍內將值剖析為浮點數，檢查值是否超出範圍 [d]使用現有字串值；檢查字串長度是否在預期範圍內錯誤
Symbol 或 Object引發無效的類型轉換錯誤轉換為 String；檢查結果長度是否在預期範圍內引發無效的類型轉換錯誤轉換為 String；檢查結果長度是否在預期範圍內 [e]錯誤
陣列引發無效的類型轉換錯誤轉換為 String；檢查結果長度是否在預期範圍內引發無效的類型轉換錯誤轉換為 String；檢查結果長度是否在預期範圍內 [e]轉換為位元組陣列；檢查結果是否在預期大小內
null 或 undefinedNULLNULLNULLNULLNULL

[a] JavaScript Infinity 和 -Infinity 會被視為超出範圍的值。

[b] JavaScript NaN 會引發無效的類型轉換錯誤。

[c] 這是使用 Math.round() 完成的。

[d] 非數值會引發無效的類型轉換錯誤

[e] 最大支援的字串長度為 1073741799


表 27.3：類型轉換：JavaScript 日期到 MySQL

JavaScript 類型MySQL DATEMySQL DATETIME、TIMESTAMPMySQL YEAR
null 或 undefinedNULLNULLNULL
Date保留值不變，並將任何時間部分四捨五入到最接近的秒數。保持值不變。從 Date 中擷取年份
可轉換為 JavaScript Date 的類型（格式化字串）將值轉換為 JavaScript Date 並進行相應處理將值轉換為 JavaScript Date 並進行相應處理如果值包含 4 位數年份，則使用它。
不可轉換為 JavaScript Date 的類型無效的類型轉換錯誤無效的類型轉換錯誤如果值包含 4 位數年份，則使用它。

傳遞 MySQL 零日期 (00-00-0000) 或日期中的零值（例如 00-01-2023）會導致建立 Date 的 Invalid Date 執行個體。當傳遞無效的 MySQL 日期（例如，2 月 31 日）時，MLE 會使用無效的個別日期和時間元件值呼叫 JavaScript Date 建構函式。

MySQL TIME 類型會被當作字串處理，並在 MySQL 內部進行驗證。如需更多資訊，請參閱 第 13.2.3 節，「TIME 類型」。

表 27.4：類型轉換：MySQL JSON 到 JavaScript

MySQL JSON 類型JavaScript 類型
NULL、JSON NULLnull
JSON OBJECTObject
JSON ARRAY陣列
JSON BOOLEAN布林值
JSON INTEGER、JSON DOUBLE、JSON DECIMALNumber
JSON STRINGString [a]
JSON DATETIME、JSON DATE、JSON TIMEString
JSON BLOB、JSON OPAQUEString

[a] MySQL JSON 字串在轉換為 JavaScript 字串時，會變成不加引號。


表 27.5：類型轉換：JavaScript 到 MySQL JSON

JavaScript 類型MySQL JSON 類型
null、undefinedNULL
布林值錯誤 [a]
Number錯誤 [a]
String

  • 可以剖析為 JSON：JSON 字串、JSON 物件或 JSON 陣列

  • 無法剖析為 JSON：錯誤

  • 'null'：JSON null

BigInt錯誤 [b]
ObjectJSON 物件或錯誤（請參閱表格後面的文字）
陣列JSON 陣列
Symbol

  • 在物件內：忽略

  • 在陣列內：JSON null

純量值：錯誤

[a] 容器內的值（例如 JSON 陣列或 JSON 物件）會被轉換（Number 值可能會遺失精確度）。純量值會擲回錯誤。

[b] JavaScript BigInt 值無法轉換為 MySQL JSON；嘗試執行此類轉換一律會引發錯誤，無論值是否在容器內。


是否可以將 JavaScript Object 轉換為 MySQL JSON 可能取決於如何為所討論的物件實作 toJSON()。以下列出一些範例

  • JavaScript Date 類別的 toJSON() 方法會將 Date 轉換為具有無效 JSON 語法的字串，因此會擲回轉換錯誤。

    對於 Set 類別，toJSON() 會傳回 "{}"，這是有效的 JSON 字串。

    對於類似 JSON 的物件，toJSON() 會傳回有效的 JSON 字串。

時區支援。 JavaScript 預存程式會使用首次叫用時生效的 MySQL 連線時區。此時區在連線期間對此預存程式保持生效。

變更 MySQL 連線時區不會自動反映在使用過且因此已快取的預存程式中。若要使其使用新的時區，請呼叫 mle_session_reset() 以清除快取；在此之後，預存程式會使用新的時區。

此處列出支援的時區類型

  • 與 UTC 的時區偏移量，例如 +11:00 或 -07:15。

  • 支援 IANA 時區資料庫中定義的時區，但使用閏秒的組態除外。例如，支援 Pacific/Nauru、Japan 和 MET，但不支援 leap/Pacific/Nauru 和 right/Pacific/Nauru。

在執行預存程式後，會執行範圍檢查和無效的類型轉換檢查。轉換在 JavaScript 內部使用類型建構函式完成，例如 Number() 和 String()；四捨五入為 Integer 是使用 Math.round() 完成的。

JavaScript 預存程式定義中命名的輸入引數（IN 或 INOUT 參數）可以使用相同的引數識別碼，從常式主體內存取。輸出引數（INOUT 和 OUT 參數）也可在 JavaScript 預存程序中使用。可以使用相同的引數識別碼，使用 JavaScript 指派 (=) 運算子設定值。如同 SQL 預存程序 OUT 引數，初始值設定為 JavaScript null。

注意

您應該不 使用 JavaScript 預存程式內的 let、var 或 const 來覆寫程式引數。這樣做會將它們變成程式的本機變數，並使使用相同名稱參數傳遞到程式的任何值無法存取。

範例

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)'

在儲存函數中，應使用 JavaScript 的 return 語句來返回純量值。在儲存程序中，此語句不會返回任何值，僅會退出程式碼區塊（這也可能或可能不會退出常式，取決於程式流程）。return 不能用於設定儲存程序的 OUT 或 INOUT 引數值；這些值必須在常式內明確設定。


上一步   首頁   上一層   下一步
相關文件
MySQL 9.0 發行說明
下載本手冊
PDF (美式信紙) - 40.0Mb
PDF (A4) - 40.1Mb
Man Pages (TGZ) - 258.2Kb
Man Pages (Zip) - 365.3Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb