#wasmcloud #wasm #database #webassembly #capability


Interface for wasmCloud actors to connect to a relational database using the capability wasmcloud:sqldb

11 releases (7 breaking)

0.8.1 Nov 23, 2022
0.7.1 Oct 4, 2022
0.6.1 Jul 18, 2022
0.5.0 Mar 1, 2022
0.2.0 Oct 24, 2021

#288 in WebAssembly

Download history 21/week @ 2022-11-30 4/week @ 2022-12-07 18/week @ 2022-12-14 6/week @ 2022-12-21 5/week @ 2022-12-28 4/week @ 2023-01-04 11/week @ 2023-01-11 14/week @ 2023-01-18 26/week @ 2023-01-25 16/week @ 2023-02-01 80/week @ 2023-02-08 69/week @ 2023-02-15 16/week @ 2023-02-22 101/week @ 2023-03-01 5/week @ 2023-03-08 13/week @ 2023-03-15

173 downloads per month

Apache-2.0 and maybe LGPL-3.0-or-later

838 lines

crates.io  TinyGo Version

wasmCloud SQL Database Interface

This interface defines a basic SQL Database provider with the capability contract wasmcloud:sqldb.

The initial version of this interface (0.1) supports executing sql queries (inserts, update, create table, etc.) and fetching data (select).

The api is intended to be independent of any specific relational database implementation (postgres, mysql, mariadb, sqlite, etc.).

For efficiency, query results are encoded in Compact Binary Object Representation CBOR, a language-neutral format. CBOR is designed to be an extensible, language-neutral, about 50-70% denser than JSON, and suitable for constrained environments (low cpu and memory requirements). Parsers are simple to write, and libraries are available in several languages.

This interface is pre-release and subject to change. The following features are currently unsupported:

  • nullable fields
  • transactions
  • prepared statements
  • streaming results

Capability Provider Implementations

The following is a list of implementations of the wasmcloud:sqldb contract. Feel free to submit a PR adding your implementation if you have a community/open source version.

Name Vendor Description
sqldb-postgres wasmCloud Implementation of the sqldb contract to interface with Postgres-compatible databases (also works for Azure CosmosDB with a Postgres backend, for example)

Example Usage (🦀 Rust)

The following examples were pulled from the Todo-sql example actor. Create a table to store DbTodo objects for a TODO list:

use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_sqldb::{minicbor, SqlDb, SqlDbError, SqlDbSender};
use minicbor::{decode, Decode, Encode};
#[derive(Encode, Decode)]
struct DbTodo {
    url: String,
    title: String,
    completed: bool,
    priority: i32,
/// create an empty table with the proper schema
async fn create_table(ctx: &Context) -> Result<(), SqlDbError> {
    let db = SqlDbSender::new();
    let sql = format!(
        r#"create table if not exists {} (
            id varchar(36) not null,
            url varchar(42) not null,
            title varchar(100) not null,
            priority int4 not null default 0,
            completed bool not null default false
    let _resp = db.execute(ctx, sql.into()).await?;

Fetching a DbTodo from a database

use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_sqldb::{minicbor, SqlDb, SqlDbError, SqlDbSender};
use wasmcloud_interface_logging::info;
use minicbor::{decode, Decode, Encode};
async fn get_db_todo(ctx: &Context, url: &str) -> Result<DbTodo, SqlDbError> {
    info!("Getting a todo...");
    let db = SqlDbSender::new();
    check_safety("url", url)?;
    let resp = db
                "select url, title, completed, priority from {} where url='{}'",
                TABLE_NAME, url
    if resp.num_rows == 0 {
        return Err(SqlDbError::new("notFound", "url not found".to_string()));
    let mut rows: Vec<DbTodo> = decode(&resp.rows)?;
    let db_todo = rows.remove(0);


~413K SLoC