Skip to content

PS-10058 [DOCS] - Update rules for conversion in JS 8.4 #532

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: 8.4
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 20 additions & 17 deletions docs/js-lang-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,20 +53,23 @@ When the data converts to a JS string, it automatically changes from the SQL par

## Convert JS data types to SQL

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.

JS `null` and `undefined` values always convert to SQL `NULL` values for the target SQL type.

| Target SQL data type | Rules for converting JS value | Example |
|----------------------|----------------------------|---------|
| Integer Numbers (BOOLEAN, TINYINT, SHORTINT, MEDIUMINT, INT, BIGINT) | JS Integers/Numbers: integers stored as-is, BIGINTs attempted as integers, others as strings. | 42 → 42 <br> 3.14 → "3.14" <br> true → "true"|
| DECIMAL | Converted to strings | 123.45 → "123.45" |
| FLOAT, DOUBLE | Stored as doubles for Numbers, converted to strings for other values | 3.14 → 3.14, "3.14" → "3.14" |
| BIT | Converted to SQL BIT type | 1 → BIT(1) |
| BigInt | For BigInt values: stored as integers. For other values: converted to Number then stored. Invalid Number conversions cause errors | 9007n → 9007, "123" → 123 |
| TIME, DATE, TIMESTAMP, DATETIME | Converted to strings | Date() → "2024-01-30" |
| CHAR, VARCHAR, TINYTEXT, TEXT, MEDIUMTEXT, ENUM | Converted to strings with charset conversion if needed | "hello" → "hello" |
| BINARY, VARBINARY, TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB | ArrayBuffer/ArrayBufferView: stored directly. Other values: converted to strings | buffer → binary data |
| SET | Numbers: stored as integers or doubles. BigInt: stored as integers. Others: converted to strings with charset conversion if needed | 1 → 1, "value" → "value" |
| GEOMETRY | ArrayBuffer/ArrayBufferView: stored as binary if valid GEOMETRY. Other values: error | valid buffer → GEOMETRY |
| JSON | Converted to JSON string using JSON.stringify() | {key: "value"} → "{"key":"value"}" |
The system uses the target SQL data type to determine how to convert each value. It typically converts a JS value into a basic type—such as a string, integer, or double—based on the specified SQL type. Once converted, the system stores the result in the corresponding SQL parameter or return value.

If a value exceeds allowed limits or uses an unsupported format, the conversion fails and triggers an error. During this process, the system automatically converts JS strings from the utf8mb4 encoding to the character set defined by the SQL parameter.

The system always maps JS null and undefined values to SQL NULL, regardless of the target SQL type.

### JS to SQL type conversion rules

| Target SQL Data Type | Conversion Rules | Explanation | Example |
|--------------------------|----------------------|------------------|-------------|
| `BOOLEAN`, `TINYINT`, `SHORTINT`, `MEDIUMINT`, `INT`, `BIGINT` | (Version 8.4.5) - Numbers: stored as integers<br>- Booleans: `true` → `1`, `false` → `0`<br>- BigInts: stored as integers when possible<br>- Other types: converted to strings first<br>(Version 8.4.4) - JS Integers/Numbers: integers stored as-is, BigInts attempted as integers, others as strings.) | Preserves native numeric forms where possible; other values default to string representation | `42` → `42`<br>`3.14` → `"3.14"`<br>`true` → `"1"` |
| `DECIMAL` | - All values converted to strings<br>- Booleans: converted to `0`/`1`, then stored as doubles | Supports precision formatting; special handling ensures Booleans fit numeric context | `123.45` → `"123.45"`<br>`true` → `1.0` |
| `FLOAT`, `DOUBLE` | - Numbers: stored as doubles<br>- (Version 8.4.5) - Booleans: converted to `0`/`1`, then stored as doubles<br>- Others: converted to strings | Treats numeric and Boolean inputs consistently using floating-point representation | `3.14` → `3.14`<br>`true` → `1.0`<br>`"3.14"` → `"3.14"` |
| `BIT` | Converted to SQL BIT type | Only binary-compatible values allowed | `1` → `BIT(1)` |
| `TIME`, `DATE`, `TIMESTAMP`, `DATETIME` | All values converted to strings | Usually expects ISO date formats or equivalents | `Date()` → `"2024-01-30"` |
| `CHAR`, `VARCHAR`, `TEXT`, etc. | All values converted to strings<br>Charset conversion from `utf8mb4` if needed | Supports text types with encoding fallback | `"hello"` → `"hello"` |
| `BINARY`, `VARBINARY`, `BLOB`, etc. | - `ArrayBuffer`/`View`: stored directly<br>- Others: converted to strings | Binary data must be explicitly wrapped; others fallback to string | `buffer` → binary |
| `SET` | - Numbers: stored as integers/doubles<br>- BigInts: stored as integers<br>- Others: converted to strings with charset conversion if needed | Tries native storage before falling back to strings | `1` → `1`<br>`"value"` → `"value"` |
| `GEOMETRY` | - Valid `ArrayBuffer`/`View`: stored as binary<br>- Others: cause an error | Enforces format rules to maintain spatial integrity | valid buffer → `GEOMETRY` |
| `JSON` | Converted using `JSON.stringify()` | Converts objects or arrays to serialized strings | `{key: "value"}` → `"{"key":"value"}"` |