Skip to content

Commit 3cfe236

Browse files
patrickbirchpatrickbirch
committed
PS-9197 [DOCS] Document JS stored routines (8.0)
 new file: docs/install-js-lang.md new file: js-lang-overview.md modified: mkdocs-base.yml new file: uninstall-js-lang.md
1 parent 0d7e07d commit 3cfe236

7 files changed

+155
-0
lines changed

‎docs/install-js-lang.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Install js_lang component
2+
3+
The `plugin_dir` system variable specifies where the component library is located. If you need to, you should set the `plugin_dir` variable when you start the server.
4+
5+
To install the `js_lang` component, you need to run the following command:
6+
7+
```{.bash data-prompt="mysql>"}
8+
mysql> INSTALL COMPONENT 'file://component_js_lang';
9+
```
10+
11+
If you decide to uninstall the component, you may have to restart the server before you can reinstall it.
12+
13+
When you install the `component_js_lang`, it gives you a new global privilege called `CREATE_JS_ROUTINE`. This privilege allows you to create JS routines within the database.
14+
15+
For more details, check out [INSTALL COMPONENT](install-component.md).

‎docs/js-lang-overview.md

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# JS language support overview
2+
3+
Creating stored procedures in JavaScript within a MySQL-compatible database offers a flexible and efficient way to handle complex data processing. It boosts performance and makes the development process easier for those familiar with JavaScript.
4+
5+
| **Advantage** | **Details** |
6+
|---|---|
7+
| **Developer Benefits** | Most developers know JavaScript well and can start writing procedures quickly. You process complex data like JSON and strings using familiar JavaScript methods. Developers use their existing JavaScript skills to write database code faster. |
8+
| **Performance Benefits** | Process your data directly in the database instead of moving it around. Network traffic decreases when data stays in the database. |
9+
| **Code and Tools** | Use JavaScript's built-in functions for data tasks. Connect with JavaScript libraries and tools you already use. Write procedures using modern JavaScript features. |
10+
| **Security Benefits** | Keep business rules inside stored procedures. Control database access through procedures. Protect your data by limiting direct table access. |
11+
12+
## Limitations
13+
14+
The JS procedure parameters cannot be [JS reserved words](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words) and must be [legal JS identifiers](https://www.capscode.in/blog/valid-identifier-in-js).
15+
16+
Our implementation offers the same level of JS support as the V8 engine inside the context of a database engine. You can check out the details at [v8.dev/docs](https://v8.dev/docs) and [tc39.es/ecma262](https://v8.dev/docs). You have access to the standard operators, data types, objects (like Math), and functions defined in the ECMAScript standard. You do not have access to node.js or a browser.
17+
18+
Within a typical database environment, direct access to external files (like reading or writing files on the server's file system) and DOM objects (which are browser-specific) is restricted. Our implementation adheres to a trusted external routine language policy, ensuring that routines cannot perform operations beyond what is normally possible for database users. Consequently, file or network I/O operations are not supported within our routines.
19+
20+
Our system supports asynchronous JavaScript (JS) code, but it doesn’t work well for database routines. Since everything runs on the same thread and there’s nothing to wait for asynchronously, using asynchronous code is unnecessary and not recommended.
21+
22+
We always run JS code in strict mode, and you cannot disable or change this setting.
23+
24+
## Converting data types to JS
25+
26+
SQL and JS use different data types, so our implementation converts values when passing SQL parameters to JS and back. The following rules explain how these conversions work:
27+
28+
SQL `NULL` values are converted to JS `null` values.
29+
30+
| Source SQL data type | Target JS data type |
31+
|---|---|
32+
| BOOLEAN, TINYINT, SHORTINT, MEDIUMINT, INT | Number |
33+
| BIGINT | Number for values [-2^53-1, 2^53-1], BigInt object otherwise |
34+
| DECIMAL | String |
35+
| FLOAT, DOUBLE | Number |
36+
| BIT(k) | Number for k ≤ 53, BigInt for k > 53 |
37+
| TIME, DATE, TIMESTAMP, DATETIME | String |
38+
| YEAR | Number |
39+
| CHAR, VARCHAR, TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXT | String. Fails if length exceeds 2^29 - 24. |
40+
| BINARY, VARBINARY, TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB | DataView |
41+
| ENUM, SET | String |
42+
| GEOMETRY and other spatial types | DataView |
43+
| JSON | Object |
44+
45+
When the data converts to a JS string, it automatically changes from the SQL parameter’s character set to `utf8mb4`, which JS uses.
46+
47+
## Converting data types to SQL
48+
49+
The target SQL data type defines how the system converts values. The system typically converts a JS value to one of the basic types, such as string, integer, or double, depending on the SQL data type. After the conversion, the system stores the result in the SQL parameter or return value. This step can fail if the value is too large or has an incorrect format, which will cause an error. During the process, JS strings automatically convert from `utf8mb4` to the character set of the SQL parameter.
50+
51+
JS `null` and `undefined` values always convert to SQL `NULL` values for the target SQL type.
52+
53+
| Target SQL data type | Rules for converting JS value |
54+
|---|---|
55+
| BOOLEAN, TINYINT, SHORTINT, MEDIUMINT, INT, BIGINT | JS integer values are stored as integers in the SQL parameter. BigInt values are also stored as integers. All other JS values, including non-integer Numbers, are converted to strings and stored in the SQL parameter. |
56+
| DECIMAL | The system converts the JS value to a string and stores the string in the SQL parameter. |
57+
| FLOAT, DOUBLE | SQL stores JS Numbers as doubles (floating-point numbers). SQL converts other JS values to strings and stores the result in a SQL parameter. |
58+
| BIT | JS BigInt values store as integers in SQL parameters. Other JS values convert to Numbers, and the result is stored in SQL parameters. JS values that cannot convert to Numbers cause an error. |
59+
| TIME, DATE, TIMESTAMP, DATETIME | The JS value converts to a string, and the string stores in the SQL parameter. |
60+
| CHAR, VARCHAR, TINYTEXT, TEXT, MEDIUMTEXT, ENUM | The JS value converts to a string, and the result stores in the SQL parameter. If needed, the charset converts during the process. |
61+
| BINARY, VARBINARY, TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB | Binary data from JS ArrayBufferView and ArrayBuffer objects is directly stored in the SQL parameter. For other JS values, the value is converted to a string and stored in the SQL parameter. |
62+
| SET | JS integer values are stored as integers in the SQL parameter. Non-integer Number values are stored as doubles (floating-point values). BigInt values are stored as integers. All other JS values are converted to strings and stored in the SQL parameter, with charset conversion if needed. |
63+
| GEOMETRY | Binary data from JS ArrayBufferView or ArrayBuffer objects is stored as is in the SQL parameter, assuming the data represents a valid SQL GEOMETRY value. For other JS values, an error occurs. |
64+
| JSON | JS values are converted into a JSON string using JSON.stringify(), and the result is stored in the SQL parameter. |

‎docs/js-lang-privileges.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# JavaScript routine support
2+
3+
Privileges control what users can do. You use them to give specific permissions to different users. This ability helps you keep your data secure by only allowing authorized users to access and change information in the database.
4+
5+
## Privileges
6+
7+
To create routines, you must have the global dynamic `CREATE_JS_ROUTINE` privilege in addtion to the standard `CREATE ROUTINE` privilege.
8+
9+
```{.bash data-prompt="mysql>"}
10+
mysql> GRANT CREATE_JS_ROUTINE ON *.* TO user1@localhost;
11+
```
12+
13+
If a user can create routines and has the `CREATE_JS_ROUTINE` privilege, they can now create stored functions and procedures using JS.
14+
15+
However, you can't currently create JS triggers or events.

‎docs/js-lang-procedures.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# JS stored function or procedure
2+
3+
After component is installed it becomes possible to create stored function or stored procedure in JS language using the following syntax:
4+
5+
```{.text .no-copy}
6+
CREATE
7+
[DEFINER = user]
8+
FUNCTION [IF NOT EXISTS] sp_name ([func_parameter[,...]])
9+
RETURNS type
10+
LANGUAGE JS [other-func-characteristic ...] AS js_routine_body
11+
12+
CREATE
13+
[DEFINER = user]
14+
PROCEDURE [IF NOT EXISTS] sp_name ([proc_parameter[,...]])
15+
LANGUAGE JS [other-proc-characteristic ...] AS js_routine_body
16+
17+
routine_body:
18+
text_string_literal | dollar_quoted_string
19+
```
20+
21+
Use the `LANGUAGE JS` clause when creating a routine.
22+
23+
```{.bash data-prompt="mysql>"}
24+
mysql> CREATE FUNCTION f1(n INT) RETURNS INT LANGUAGE JS AS $$
25+
return n*42;
26+
$$
27+
28+
mysql> CREATE PROCEDURE p1(a INT, b INT, OUT r INT) LANGUAGE JS AS $$
29+
r = a * b;
30+
$$
31+
```
32+
33+
You can modify or delete stored programs in JS using the standard `ALTER PROCEDURE/FUNCTION` and `DROP PROCEDURE/FUNCTION` statements. These statements do not require the additional `CREATE_JS_ROUTINE` privilege.
34+

‎docs/js-lang-troubleshoot.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Troubleshoot JS lang procedures
2+
3+
The component includes a set of User-Defined Functions (UDFs) that retrieve and clear information about the last JS error that occurred in the current connection for the current user. This information updates each time a JS error occurs for the current connection and user. Successful execution of JS code does not change this state.
4+
5+
The following UDFs are helpful for debugging JS code.
6+
7+
* `JS_GET_LAST_ERROR()`: Returns the error message for the last JS error that occurred in the current connection for the current user.
8+
9+
* `JS_GET_LAST_ERROR_INFO()`: Provides extended information about the last JS error that occurred in the current connection for the current user. In addition to the error message, it includes the exact line and column where the problem occurred and the stack trace if available.
10+
11+
* `JS_CLEAR_LAST_ERROR()`: Resets the information about the last JS error for the current connection and user, as if no error had occurred.

‎docs/uninstall-js-lang.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Uninstall the js_lang component
2+
3+
The uninstall works only when no connections are using JavaScript stored programs. If there are connections, the procedure fails with an error.
4+
5+
To remove the component, run the following:
6+
7+
```{.bash data-prompt="mysql>"}
8+
mysql> UNINSTALL COMPONENT 'file://component_js_lang';
9+
```

‎mkdocs-base.yml

+7
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,13 @@ nav:
212212
- extended-select-into-outfile.md
213213
- fips.md
214214
- innodb-expanded-fast-index-creation.md
215+
- JS language support:
216+
- js-lang-overview.md
217+
- install-js-lang.md
218+
- js-lang-privileges.md
219+
- js-lang-procedures.md
220+
- js-lang-troubleshoot.md
221+
- uninstall-js-lang.md
215222
- kill-idle-trx.md
216223
- percona-sequence-table.md
217224
- procfs-plugin.md

0 commit comments

Comments
 (0)