WASM Procedures: API Reference (Planned Design)

Planned design: not yet available in the server

The current heliosdb-full server does not run WASM procedures. SQL that would create or call one fails with SQLSTATE 0A000. This page describes the planned design for this upcoming feature. Only the Go SDK is published. Rust, JavaScript and Python examples are illustrations: no SDK package exists for those languages. See the Quick Start for what works today.

The SQL on this page, including CREATE SECURITY PROFILE, the SECURITY PROFILE clause, syscall filters and ALTER PROCEDURE options, is the planned syntax; the current server does not accept it.

Documentation Home > User Guides > Features > API Reference

---

Overview

Planned API reference for the upcoming HeliosDB WASM Procedures feature, including SQL statements, host functions, and error codes. The SQL statements below are the planned syntax and are not accepted by the current server.

Related Sections:

• Host Functions - Detailed host function documentation
• Procedure Management - Managing procedures
• Language SDKs - SDK-specific APIs

---

API Reference

SQL Statements

CREATE PROCEDURE

-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
CREATE [OR REPLACE] PROCEDURE name (params)
[RETURNS type]
LANGUAGE wasm
[SECURITY PROFILE 'profile']
[WITH (options)]
AS source;

Options:

• precompile: boolean - Precompile module
• compilation_tier: ‘interpreter’ | ‘baseline’ | ‘optimizing’
• fuel_metering: boolean - Enable fuel metering
• fuel_limit: integer - Fuel limit
• profiling: boolean - Enable profiling
• debug_mode: boolean - Enable debug mode

ALTER PROCEDURE

-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
ALTER PROCEDURE name
  SET SOURCE '/path/to/new.wasm'
  | SET SECURITY PROFILE 'profile'
  | SET log_level = 'level'
  | SET option = value;

DROP PROCEDURE

DROP PROCEDURE [IF EXISTS] name [CASCADE];

CALL

CALL procedure_name(args);
SELECT procedure_name(args);

Host Function Reference

The WASM host links its functions in the env import module: heliosdb_execute, heliosdb_begin_tx, heliosdb_commit_tx, heliosdb_rollback_tx, heliosdb_storage_write, heliosdb_log, heliosdb_query, heliosdb_storage_read, heliosdb_fetch_rows and heliosdb_emit_event. There are no HTTP, metrics or capability-request host functions. Signatures, return codes and the matching Go SDK calls are in Host Functions.

Error Codes

Code	Name	Description
01000	WASM_COMPILATION_ERROR	Failed to compile WASM module
01001	WASM_INSTANTIATION_ERROR	Failed to instantiate module
01002	WASM_EXECUTION_ERROR	Procedure execution failed
01003	WASM_TIMEOUT	Execution exceeded time limit
01004	WASM_MEMORY_EXCEEDED	Memory limit exceeded
01005	WASM_FUEL_EXHAUSTED	Fuel limit exhausted
01006	WASM_SECURITY_VIOLATION	Security capability violation
01007	WASM_PERMISSION_DENIED	Permission denied
01008	WASM_INVALID_PARAMETER	Invalid parameter
01009	WASM_MODULE_NOT_FOUND	Procedure not found

---

System Catalogs

heliosdb_procedures

Information about all procedures:

SELECT * FROM heliosdb_procedures;

Columns:

• name: Procedure name
• language: ‘wasm’
• security_profile: Security profile name
• size_bytes: WASM module size
• created_at: Creation timestamp
• last_modified: Last modification timestamp
• version: Current version

heliosdb_procedure_metrics

Performance metrics:

SELECT * FROM heliosdb_procedure_metrics;

Columns:

• procedure_name: Procedure name
• total_calls: Total number of calls
• successful_calls: Successful executions
• failed_calls: Failed executions
• success_rate: Success rate percentage
• avg_execution_time_ms: Average execution time
• min_execution_time_ms: Minimum execution time
• max_execution_time_ms: Maximum execution time
• p50_execution_time_ms: 50th percentile
• p95_execution_time_ms: 95th percentile
• p99_execution_time_ms: 99th percentile

heliosdb_procedure_errors

Error tracking:

SELECT * FROM heliosdb_procedure_errors;

Columns:

• procedure_name: Procedure name
• error_message: Error message
• error_count: Number of occurrences
• last_occurrence: Last occurrence timestamp
• stack_trace: Stack trace (if available)
• source_location: Source code location

heliosdb_procedure_logs

Procedure logs:

SELECT * FROM heliosdb_procedure_logs;

Columns:

• timestamp: Log timestamp
• procedure_name: Procedure name
• log_level: Log level (trace, debug, info, warn, error)
• message: Log message
• execution_id: Execution identifier

heliosdb_wasm_cache_stats

Module cache statistics:

SELECT * FROM heliosdb_wasm_cache_stats;

Columns:

• cached_modules: Number of cached modules
• cache_hits: Cache hits
• cache_misses: Cache misses
• hit_rate: Hit rate percentage
• evictions: Number of evictions

heliosdb_wasm_pool_stats

Instance pool statistics:

SELECT * FROM heliosdb_wasm_pool_stats;

Columns:

• procedure_name: Procedure name
• pool_size: Configured pool size
• available_instances: Available instances
• in_use_instances: Instances in use
• total_acquisitions: Total acquisitions
• avg_acquisition_time_ms: Average acquisition time

---

Configuration Parameters

Global Settings

-- Cache configuration
SET heliosdb.wasm_module_cache_size = 1000;
SET heliosdb.wasm_module_cache_ttl = 3600;
SET heliosdb.wasm_module_cache_enabled = true;

-- Pool configuration
SET heliosdb.wasm_instance_pool_size = 10;
SET heliosdb.wasm_instance_max_age_seconds = 300;
SET heliosdb.wasm_instance_max_executions = 1000;

-- Memory configuration
SET heliosdb.wasm_memory_pool_size_mb = 1024;
SET heliosdb.wasm_memory_pooling_enabled = true;

-- Logging configuration
SET heliosdb.procedure_log_level = 'info';
SET heliosdb.procedure_log_retention_days = 30;

-- Execution limits
SET heliosdb.wasm_default_fuel_limit = 1000000000;
SET heliosdb.wasm_default_memory_limit_mb = 512;
SET heliosdb.wasm_default_timeout_ms = 30000;

Procedure-Specific Settings

-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
ALTER PROCEDURE my_procedure
  SET fuel_limit = 10000000000
  SET fuel_metering = false
  SET compilation_tier = 'optimizing'
  SET profiling = true
  SET debug_mode = false
  SET log_level = 'info';

---

Key Takeaways

1. Complete SQL API: Full DDL support for procedure management
2. Rich Host Functions: 40+ host functions across 8 categories
3. System Catalogs: Comprehensive metadata and metrics
4. Error Codes: Standardized error codes for diagnostics
5. Configuration: Flexible global and per-procedure settings

Quick Reference

Create Procedure:

-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
CREATE PROCEDURE name(params) RETURNS type LANGUAGE wasm AS source;

Call Procedure:

SELECT procedure_name(args);

View Metrics:

SELECT * FROM heliosdb_procedure_metrics WHERE procedure_name = 'name';

View Errors:

SELECT * FROM heliosdb_procedure_errors WHERE procedure_name = 'name';

Next Steps

• Host Functions - Detailed host function documentation
• Language SDKs - SDK-specific APIs
• Conclusion - Summary and resources

---

Navigation: ← Migration Guide | Index | Conclusion →