WASM Procedures: Quick Start

Time Required: 20 minutes

Prerequisites

# Install Rust (for Rust SDK)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-wasi

# Install Node.js (for JavaScript SDK)
# Download from: https://nodejs.org/

# Install Python 3.9+ (for Python SDK)
# Download from: https://python.org/

# Install Go and TinyGo (for Go SDK)
# Download from: https://golang.org/ and https://tinygo.org/

Step 1: Choose Your Language

Pick your preferred language and follow the corresponding guide:

Rust SDK - Best for: High-performance, type-safe procedures
JavaScript/TypeScript SDK - Best for: JSON processing, async operations
Python SDK - Best for: Data science, ML integration
Go SDK - Best for: Concurrent processing, systems programming

Step 2: Install SDK

Rust

cargo new --lib my_procedure
cd my_procedure

Add to Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
heliosdb-sdk = "1.0.0"

JavaScript

npm init -y
npm install --save-dev assemblyscript @heliosdb/wasm-sdk
npx asinit .

Python

pip install heliosdb-wasm-sdk wasmtime

Go

go mod init my-procedure
go get github.com/heliosdb/heliosdb-go-sdk

Step 3: Write Your First Procedure

Rust Example

src/lib.rs:

use heliosdb_sdk::*;

#[procedure]
pub fn calculate_discount(order_total: f64, customer_tier: &str) -> Result<f64, String> {
    let discount_rate = match customer_tier {
        "gold" => 0.15,
        "silver" => 0.10,
        "bronze" => 0.05,
        _ => 0.0,
    };

    let discount = order_total * discount_rate;
    log_info(&format!("Calculated {}% discount: ${:.2}", discount_rate * 100.0, discount));

    Ok(discount)
}

JavaScript Example

assembly/index.ts:

import { execSql, log } from "@heliosdb/wasm-sdk";

export function calculateDiscount(orderTotal: f64, customerTier: string): f64 {
    let discountRate: f64 = 0;

    if (customerTier == "gold") discountRate = 0.15;
    else if (customerTier == "silver") discountRate = 0.10;
    else if (customerTier == "bronze") discountRate = 0.05;

    const discount = orderTotal * discountRate;
    log("info", `Calculated discount: $${discount.toString()}`);

    return discount;
}

Python Example

procedure.py:

import heliosdb

def calculate_discount(order_total: float, customer_tier: str) -> float:
    discount_rates = {
        "gold": 0.15,
        "silver": 0.10,
        "bronze": 0.05,
    }

    discount_rate = discount_rates.get(customer_tier, 0.0)
    discount = order_total * discount_rate

    heliosdb.log_info(f"Calculated {discount_rate*100}% discount: ${discount:.2f}")

    return discount

Go Example

main.go:

package main

import (
    "fmt"
    "heliosdb"
)

//export calculateDiscount
func calculateDiscount(orderTotal float64, customerTier string) float64 {
    discountRates := map[string]float64{
        "gold":   0.15,
        "silver": 0.10,
        "bronze": 0.05,
    }

    discountRate := discountRates[customerTier]
    discount := orderTotal * discountRate

    heliosdb.LogInfo(fmt.Sprintf("Calculated %.0f%% discount: $%.2f",
        discountRate*100, discount))

    return discount
}

func main() {}

Step 4: Build WASM Module

Rust

cargo build --target wasm32-wasi --release

JavaScript

npm run asbuild

Python

py2wasm procedure.py -o procedure.wasm
# or use Pyodide

Go

tinygo build -o procedure.wasm -target wasi main.go
# Optimize
tinygo build -o procedure.wasm -target wasi -opt=z -no-debug main.go

Step 5: Deploy to Database

-- Create the procedure
CREATE PROCEDURE calculate_discount(
    order_total DECIMAL(10,2),
    customer_tier VARCHAR(20)
)
RETURNS DECIMAL(10,2)
LANGUAGE wasm
SECURITY PROFILE 'standard'
AS '/path/to/procedure.wasm';

-- Alternative: Inline WASM binary
CREATE PROCEDURE calculate_discount(
    order_total DECIMAL(10,2),
    customer_tier VARCHAR(20)
)
RETURNS DECIMAL(10,2)
LANGUAGE wasm
AS BYTEA '0x0061736d01000000...'; -- WASM binary

Step 6: Call the Procedure

-- Simple call
SELECT calculate_discount(1000.00, 'gold');
-- Returns: 150.00

-- Use in query
SELECT
    order_id,
    total,
    calculate_discount(total, customer_tier) AS discount,
    total - calculate_discount(total, customer_tier) AS final_total
FROM orders
WHERE status = 'pending';

-- Call from application
CALL calculate_discount(1000.00, 'gold');

Step 7: View Results

-- Check execution stats
SELECT * FROM heliosdb_procedure_stats
WHERE procedure_name = 'calculate_discount';

-- View logs
SELECT * FROM heliosdb_procedure_logs
WHERE procedure_name = 'calculate_discount'
ORDER BY timestamp DESC
LIMIT 10;

-- Performance metrics
SELECT
    procedure_name,
    avg_execution_time_ms,
    total_calls,
    success_rate
FROM heliosdb_procedure_metrics;

Congratulations! You’ve created and deployed your first WASM procedure.

Navigation:

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