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

enable_wasm

Specifies if a user can create or call Wasm UDFs.

ON

wasm_max_compiled_module_size

Specifies the maximum size (in bytes) that a compiled Wasm module can use.

26214400 (25MB)

wasm_max_linear_memory_size

Specifies the maximum linear memory (in bytes) that an individual Wasm module can use. This will further constrain UDF-specific GROW TO values.

16777216 (16MB or 256 Wasm pages)

wasm_max_raw_module_size

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 CREATE FUNCTION statement.

26214400 (25MB)

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 and GEOGRAPHYPOINT 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 or utf8mb4 collations).

In this section: