wasmerio/wasmer-postgres

Wasmer Postgres

It's an original way to extend your favorite database capabilities

A complete and mature WebAssembly runtime for Postgres based on Wasmer. .

Features:

  • Easy to use: The wasmer API mimics the standard WebAssembly API,
  • Fast: wasmer executes the WebAssembly modules as fast as possible, close to native speed,
  • Safe: All calls to WebAssembly will be fast, but more importantly, completely safe and sandboxed.

Note: The project is still in heavy development. This is a 0.1.0 version. Some API are missing and are under implementation. But it's fun to play with it.

Installation

The project comes in two parts:

  1. A shared library, and
  2. A PL/pgSQL extension.

To compile the former, run just build (Postgres server headers are required, see pg_config --includedir-server). To install the latter, run just install. After that, run CREATE EXTENSION wasm in a Postgres shell. A new function will appear: wasm_init; it must be called with the absolute path to the shared library. It looks like this:

$ # Build the shared library.
$ just build

$ # Install the extension in the Postgres tree.
$ just install

$ # Activate and initialize the extension.
$ just host=$host database=$database activate

And you are ready to go!

Note: On macOS, the shared library extension is .dylib, on Windows, it is .dll, and on other distributions, it is .so.

Note 2: Yes, you need just.

Supported Postgres versions

So far, the extension works on Postgres 10 only. It doesn't work with Postgres 11 yet (follow this issue if you want to learn more). Any help is welcomed!

Usage & documentation

Consider the examples/simple.rs program:

#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
    x + y
}

Once compiled to WebAssembly, one obtains a similar WebAssembly binary to examples/simple.wasm (download it). To use the sum exported function, first, create a new instance of the WebAssembly module, and second, call the sum function.

To instantiate a WebAssembly module, the wasm_new_instance function must be used. It has two arguments:

  1. The absolute path to the WebAssembly module, and
  2. A namespace used to prefix exported functions in SQL.

For instance, calling wasm_new_instance('/path/to/simple.wasm', 'ns') will create the ns_sum function that is a direct call to the sum exported function of the WebAssembly instance. Thus:

-- New instance of the `simple.wasm` WebAssembly module.
SELECT wasm_new_instance('/absolute/path/to/simple.wasm', 'ns');

-- Call a WebAssembly exported function!
SELECT ns_sum(1, 2);

--  ns_sum
-- --------
--       3
-- (1 row)

Isn't it awesome? Calling Rust from Postgres through WebAssembly!

Let's inspect a little bit further the ns_sum function:

\x
\df+ ns_sum
Schema              | public
Name                | ns_sum
Result data type    | integer
Argument data types | integer, integer
Type                | normal
Volatility          | volatile
Parallel            | unsafe
Owner               | …
Security            | invoker
Access privileges   |
Language            | plpgsql
Source code         | …
Description         |

The Postgres ns_sum signature is (integer, integer) -> integer, which maps the Rust sum signature (i32, i32) -> i32.

So far, only the WebAssembly types i32, i64 and v128 are supported; they respectively map to integer, bigint and decimal in Postgres. Floats are partly implemented for the moment.

Inspect a WebAssembly instance

The extension provides two foreign data wrappers, gathered together in the wasm foreign schema:

  • wasm.instances is a table with the id and wasm_file columns, respectively for the instance ID, and the path of the WebAssembly module,
  • wasm.exported_functions is a table with the instance_id, name, inputs and output columns, respectively for the instance ID of the exported function, its name, its input types (already formatted for Postgres), and its output types (already formatted for Postgres).

Let's see:

-- Select all WebAssembly instances.
SELECT * FROM wasm.instances;

--                   id                  |          wasm_file
-- --------------------------------------+-------------------------------
--  426e17af-c32f-5027-ad73-239e5450dd91 | /absolute/path/to/simple.wasm
-- (1 row)

-- Select all exported functions for a specific instance.
SELECT
    name,
    inputs,
    outputs
FROM
    wasm.exported_functions
WHERE
    instance_id = '426e17af-c32f-5027-ad73-239e5450dd91';

--   name  |     inputs      | outputs
-- --------+-----------------+---------
--  ns_sum | integer,integer | integer
-- (1 row)

Benchmarks

Benchmarks are useless most of the time, but it shows that WebAssembly can be a credible alternative to procedural languages such as PL/pgSQL. Please, don't take those numbers for granted, it can change at any time, but it shows promising results:

Benchmark Runtime Time (ms) Ratio
Fibonacci (n = 50) postgres-ext-wasm 0.206
PL/pgSQL 0.431
Fibonacci (n = 500) postgres-ext-wasm 0.217
PL/pgSQL 2.189 10×
Fibonacci (n = 5000) postgres-ext-wasm 0.257
PL/pgSQL 18.643 73×

Test

Once the library is built, run the following commands:

$ just pg-start
$ just test

License

The entire project is under the MIT License. Please read the LICENSE file.

Issues

Collection of the latest Issues

tracker1

tracker1

❓ question
Comment Icon4

It looks like there hasn't been any real progress on any of the branches in this repository in about a year and a half, is this still being worked on... would be nice to see progress on this, as I'd love to see something more approachable as a language for stored procedures as well as functions in Postgres. Since plv8 was shot down because of build time/complexity, this is likely a much better and more approachable option.

tvenhola

tvenhola

🎉 enhancement
Comment Icon1

Benchmark (as published on medium.com) has several issues:

  • int32 overflows: 48th fibonacci number is larger than 2^31
  • plpgsql version uses decimal, which is a different datatype (infinite length and precision numeric) and does not overflow, i.e. benchmark is comparing apples to oranges
  • Apparently no correctness checks were performed for the returned value, allowing the function to be quick by returning incorrect values and not catching errors

Instead of the current plpgsql implementation like this could (should) be used with recursive r(a, b, c) as ( select 0::int, 1::int, 1::int union all select b, a + b, c+1::int from r where c < 46 ) select a from r where c = 45;

Versions

Find the latest versions by id

Information - Updated Jul 30, 2022

Stars: 324
Forks: 17
Issues: 3

Generates PDF files directly in the browser with JavaScript and WASM (WebAssembly)

Idea here is to push all the work involved in creating a PDF to the browser side, instead of using precious server resources

Generates PDF files directly in the browser with JavaScript and WASM (WebAssembly)

This is a minimal example of the gcode-rs crate with web assembly

1) Install Rust, wasm-pack, and &quot;rollup&quot;

This is a minimal example of the gcode-rs crate with web assembly

The Wasm-Enabled, Elfin Allocator

The Rust and WebAssembly Working Group

The Wasm-Enabled, Elfin Allocator

AssemblyLift is a framework for building serverless applications powered by WebAssembly (WASM)

We're open to ideas and PRs! Please start a forking workflow to open a new Pull Request

AssemblyLift is a framework for building serverless applications powered by WebAssembly (WASM)

The wasm-to-rust tool allows compilation from WebAssembly to Rust source code

This is still very much a work in progress so not every WebAssembly binary successfully compiles to valid Rust source code

The wasm-to-rust tool allows compilation from WebAssembly to Rust source code

Collection of externs to interact with ethereum-like network

Parity Wasm Tutorial - a full fledged tutorial on how to write contracts in Webassembly for Kovan and other Wasm-enabled networks

Collection of externs to interact with ethereum-like network

Markdown editor built using Rust WebAssembly

Run wasm-pack build --target web to compile rust into wasm

Markdown editor built using Rust WebAssembly

rust-wasm-mandelbrot

WebAssembly でマンデルブロ集合を描きます

rust-wasm-mandelbrot
Facebook Instagram Twitter GitHub Dribbble
Privacy