vados-cosmonic/wit-wasmcloud-postgres

WIT interface for wasmcloud:postgres

🐘 wasmcloud:postgres WIT interface

This repository contains WIT definitions for wasmcloud:postgres, an interface for interacting with the Postgres database system from WebAssembly.

👟 Using this WIT interface

While wasmcloud:postgres is best used from the [wasmCloud][wasmcloud] ecosystem (i.e. with the wasmCloud sqldb-postgres provider), this WIT contract can be used by any ecosystem project that supports WIT interfaces and fulfilling WIT contracts (whether locally, or in a distriuted fashion as wasmCloud does).

🏗️ Building WebAssembly components

These definitions are meant to be used while creating WebAssembly components, with whatever language toolchain is available to you.

Language	Toolchain
Javascript	jco
Rust	cargo-component
Rust	wit-bindgen
Python	componentize-py
Golang	wit-bindgen

Depending on which language and toolchain you use, the specifics differ, but you should end up with a project that contains a wit folder.

⬇️ Downloading this WIT

While ecosystem tooling for pulling and using WIT-manifest-only components develops, the easiest way to get started is to use wit-deps, a dependency manager for WIT files.

In your project, include the following wit/deps.toml:

postgres = "https://github.com/vados-cosmonic/wit-wasmcloud-postgres/archive/v0.1.0-draft.tar.gz"

From your project root (the folder above wit/), you should be able to run wit-deps:

wit-deps

This will populate a wit/deps folder and create wit/deps.lock.

🚀 Using the WIT interfaces

Using the WIT interfaces from your language of choice depends primarily on your language, toolchain, and the WebAssembly runtime you're using -- here are some examples for reference.

Guest: Rust

If using the Rust ecosystem with wit-bindgen, you might have a WIT world that looks like the following:

package wasmcloud:examples;

/// Invoke a component and receive string output. Similar to wasi:cli/command.run, without args
///
/// This enables the component to be used with `wash call`
interface invoke {
    /// Invoke a component
    call: func() -> string;
}

world component {
  import wasmcloud:postgres/managed-query@0.1.0-draft;
  export invoke;
}

To build a WebAssembly component that satisfies that world, you might write code that looks like this:

wit_bindgen::generate!();

// NOTE: the imports below is generated by wit_bindgen::generate, due to the
// WIT definition(s) specified in `wit`
use wasmcloud::postgres::managed_query::{self, PgValue};

// NOTE: Imagine that the `exec` interface is an exported interface with one
// function with the signature `call: func() -> string`
use exports::webassembly::examples::call::Guest;

// Implementation of the `exec` interface we're exporting goes here
struct QueryRunner;

impl Guest for QueryRunner {
    fn call() -> String {
        // Perform a managed query
        match managed_query::query(
            "SELECT * FROM users WHERE email = $1",
            &[PgValue::Text(format!("some-text-input!"))],
        ) {
            // query completed successfully
            Ok(rows) => ...,
            // query failed
            Err(e) => ...,
        }
    }
}

export!(QueryRunner);