Code Engine - Powered by Wasm
The Code Engine feature in SingleStoreDB supports creating functions (UDFs are fully supported, and TVFs are currently supported in Preview mode for non-production use only) using code compiled to WebAssembly (Wasm). This feature supports any language that can compile to the Wasm core specification, which allows you to create UDFs in a language of your choice using existing code libraries and run them in a sandboxed environment for enhanced security.
SingleStoreDB supports both the Basic and Canonical Wasm Application Binary Interfaces (ABIs). The Wasm UDF should not require runtime capabilities that the database does not provide. For example, a UDF can not make system calls, open files, open sockets, send network messages, create processes, or create threads. SingleStoreDB does not support these operations to protect the security and integrity of its service process. See Select the Wasm ABI for more information.
Using the Basic ABI, SingleStoreDB supports any language that can compile to Wasm code, if the UDF accepts and returns only numeric data types.
Using the Canonical ABI, you can pass and return complex data types from UDF. SingleStoreDB currently supports the following languages only for Canonical ABI:
C/C++
Rust
Once a Wasm function is added to SingleStoreDB, it becomes a part of the database. Hence, it is also included in the database backup and restore operations.
See Create Wasm UDFs for information on creating a Wasm UDF.
See Create Wasm TVFs for information on creating a Wasm TVF (for non-production use only).
Select the Wasm ABI
When a Wasm function is created, you can specify one of the following Application Binary Interfaces (ABIs): Basic or Canonical. The default ABI type is Canonical, unless specified explicitly.
Basic: This is the bare-bones Wasm ABI. It supports only 32-bit and 64-bit integers and floating point numbers.
Canonical: This ABI type is defined by the Canonical ABI specification (a part of the Interface Types proposal). It is a superset of Basic ABI, and it allows usage of structured and complex interface types.
Note
The user must ensure that the specified ABI type matches the Wasm module implementation. A mismatch may lead to unexpected results at runtime.
Canonical ABI
The canonical ABI is a proposed part of WASI. To use the canonical ABI, you must specify additional metadata in the form of a WIT IDL string.
The wit-bindgen
tool, which generates bindings for the Canonical ABI, declares function and structure names as hyphenated strings. Using hyphenated names for UDFs requires them to be enclosed in backticks (`
), Hence, all function, parameter, and record field names loaded from the Wasm modules are renamed to use underscores instead of hyphens. For example, consider the the following Wasm UDF specified by the WIT definition:
user-function-name: func() -> string;
To call this Wasm UDF, we use the following syntax:
SELECT user_function_name();
Configure Wasm
Use the following global variables to configure the Code Engine for Wasm extensibility:
Variable Name | Description | Default Value |
---|---|---|
| Specifies if a user can create or call Wasm UDFs. |
|
| Specifies the maximum size (in bytes) that a compiled Wasm module can use. |
|
| Specifies the maximum linear memory (in bytes) that an individual Wasm module can use. This will further constrain UDF-specific |
|
| Specifies the maximum size (in bytes) of Wasm modules that may be loaded. The size is defined as the size of raw, uncompiled data passed in the |
|
Wasm Data Type Coercions
The following table describes how database types are coerced to and from Wasm ABI types when using explicitly-typed UDFs. Empty cells indicate that automatic coercion is not available currently, and you must cast that SingleStoreDB database type to another data type for which data type conversion is available:
SingleStoreDB Data Type | Wasm Basic ABI Type | Wasm Canonical ABI Type |
---|---|---|
ARRAY | list<...> | |
BIGINT | i64 | i64 |
BINARY | u32 | u32 |
BINARY(...) | list<u8> | |
BIT | ||
BLOB | list<u8> | |
BOOL | i32 | u8 |
CHAR | i32 | char |
CHAR(...) | string | |
DATE | ||
DATETIME | ||
DATETIME(6) | ||
DECIMAL | ||
DOUBLE | f64 | float64 |
ENUM | ||
FLOAT | f32 | float32 |
GEOGRAPHY | string (WKT format) | |
GEOGRAPHYPOINT | string (WKT format) | |
INT | i32 | i32 |
JSON | string | |
LONGBLOB | list<u8> | |
LONGTEXT | string | |
MEDIUMBLOB | list<u8> | |
MEDIUMINT | i32 | i32 |
MEDIUMTEXT | string | |
RECORD | record | |
SET | ||
SMALLINT | i32 | i16 |
TEXT | string | |
TIME | ||
TIME(6) | ||
TIMESTAMP | i64 | i64 |
TIMESTAMP(6) | i64 | i64 |
TINYBLOB | list<u8> | |
TINYINT | i32 | i8 |
TINYTEXT | string | |
VARBINARY | list<u8> | |
VARCHAR | string | |
YEAR | i32 | i32 |
Remarks
Wasm does not support Base-10 numeric or date-time data types. You must specify/cast these data types to ABI-supported data types.
The
GEOGRAPHY
andGEOGRAPHYPOINT
data types are converted to strings using the WKT representation.SingleStoreDB recommends casting the
ENUM
data type to strings.Coercions to/from canonical ABI string types require that the data be encoded using multi-byte UTF-8 (
utf8mb3
orutf8mb4
collations).