WASM Procedures: Quick Start

Part of: WASM Procedures User Guide

Not yet available in the server

The current heliosdb-full server does not run WASM procedures. “WASM functions” are on its list of subsystems that are not wired, so SQL that would create or call a WASM procedure fails with SQLSTATE 0A000. You can already write, build and unit-test Go procedures with the SDK below, and they target the WASM host included in the HeliosDB Full source. Steps 4 and 5 show how procedures will be deployed once the server enables that host.

---

Time required: 15 minutes

Language support

Language	Published SDK	Status
Go (TinyGo)	github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm	Available. Builds modules for Full’s WASM host ABI, and includes a fake host for go test.
Rust	None	No SDK crate is published. The heliosdb-sdk crate named in older pages does not exist.
JavaScript / AssemblyScript	None	No npm package is published. @heliosdb/wasm-sdk does not exist.
Python	None	No PyPI package is published. heliosdb-wasm-sdk does not exist.

Any language that compiles to a core WebAssembly module could import the same host functions directly. See Host Functions.

Step 1: Install the tools

• Go 1.21 or newer: https://go.dev/dl/
• TinyGo 0.34 or newer: https://tinygo.org/getting-started/install/

Step 2: Create a module

mkdir my-procedure && cd my-procedure
go mod init example.com/my-procedure
go get github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm@latest

Step 3: Write and test a procedure

main.go:

package main

import "github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdb"

// Procedures take and return WASM scalars, so the tier is passed as a
// number here: 1 = gold, 2 = silver, 3 = bronze.
//
//export calculate_discount
func calculateDiscount(orderTotal float64, customerTier int32) float64 {
    rate := 0.0
    switch customerTier {
    case 1:
        rate = 0.15
    case 2:
        rate = 0.10
    case 3:
        rate = 0.05
    }
    heliosdb.LogInfo("calculate_discount: tier rate applied")
    return orderTotal * rate
}

// Required by the Go toolchain; the host calls the exported function directly.
func main() {}

main_test.go:

package main

import (
    "testing"

    "github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdbtest"
)

func TestCalculateDiscount(t *testing.T) {
    fake := heliosdbtest.Install(t)
    if got := calculateDiscount(1000, 1); got != 150 {
        t.Fatalf("got %v", got)
    }
    if len(fake.Logs) != 1 {
        t.Fatalf("logs = %v", fake.Logs)
    }
}

go test ./...

Step 4: Build the WASM module

tinygo build -target=wasm-unknown -gc=conservative -opt=z -no-debug -o procedure.wasm .

• Use -target=wasm-unknown. The host links only its own env functions and no WASI, so a -target=wasip1 module fails to instantiate.
• Export procedures with //export. The host calls exported functions directly and never runs _start or _initialize, which modules built with the standard Go toolchain need.

The SDK README has the full API, a tested example, and an ABI conformance suite that checks the module against Full’s host.

Step 5: Deploy (once the server enables WASM procedures)

The SQL surface for registering a module is shown below for reference. With the current server, these statements fail with SQLSTATE 0A000.

-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
CREATE PROCEDURE calculate_discount(order_total DOUBLE PRECISION, customer_tier INTEGER)
RETURNS DOUBLE PRECISION
LANGUAGE wasm
AS '/path/to/procedure.wasm';

SELECT calculate_discount(1000.0, 1);  -- 150

---

Navigation:

• Previous: Introduction
• Next: Language SDKs
• Index: WASM Procedures User Guide