Co-locating Data and Application Code for a 4.5x Performance Gain

Modern web application architectures typically run each layer in its own process, like a NodeJS server and database both running in their own processes. They communicate via a network connection or localhost socket. This separation introduces protocol overheads, TCP stack latency, and data serialization/deserialization costs on every single query.

Planck is designed around the concept of Zero-Distance Architecture that co-locates data and application code. It combines the database engine and a WebAssembly application runtime into a single, unified process. By running your application code directly inside the database process, database calls become direct in-memory function calls rather than network round-trips.

This article provides a practical guide to getting started with Planck. We will look at the core toolchain, walk through setting up a self-contained local benchmark, compare its performance against a NodeJS, ExpressJS, MongoDB stack, and look at how to build more complex features.

The Toolchain: Planck, planctl, and Workbench

Running and managing a zero-distance app requires three main components.

Planck itself is the core binary. It functions as both the storage engine (a WiscKey-style, LSM-tree-based engine) and the WebAssembly host. Instead of running a database in one process and your application server in another, you run a single Planck process. It loads your compiled WebAssembly application directly into its memory, running it in the same process space as the database.

To manage this runtime, you use planctl. This is the command-line tool for developers. It handles the compilation of your code, packages it, and deploys it to the Planck host. It also allows you to perform database operations, like creating stores and defining indexes, export/import, backup/restore directly from your terminal.

Finally, there is the Workbench. This is a web console that comes built into the platform. It provides a visual dashboard to monitor your applications, view database metrics via dashboard, manage schemas, query data and schedule tasks such as backup, import/export, Wal Truncate, Garbage Collect etc.

Installing and Starting Planck Locally

Before deploying applications, you need to install the Planck binaries, initialize the environment, and configure your local CLI profile.

1. Download and Extract the Binaries

Download the archive matching your machine from the .

profiles:

  - name: dev

    nodes:

      - server: http://127.0.0.1:2369

        uid: admin

        key: UGxhbmNrX0RlZmF1bHRfQWRtaW5fS2V5XzAwMTA=

Developer Experience: Node.js vs. Zig on Planck

A common concern with co-locating application code inside the database process using WebAssembly is that it might make the code complex or low-level. In practice, writing handlers in Zig using the Schnell framework is highly comparable to writing standard Express routes.

Here is a side-by-side comparison of a simple route that fetches categories and returns them as HTML:

Node.js and Express

app.get('/categories', async (req, res) => {

  const categories = await db.collection('categories').find().toArray();

  res.send(renderCategories(categories));

});

Zig and Schnell

pub fn handle(ctx: ?*anyopaque, allocator: Allocator, req: *const Request, res: *Response) !void {

    const categories = try db.listCategories(allocator);

    const html_fragment = try renderCategories(allocator, categories);

    try res.html(html_fragment);

}

The Schnell framework handles routing, request parsing, and response delivery. The build tool planctl automates the compilation of this code into WebAssembly, meaning you do not have to write manual WASM bindings or build configurations.

The Benchmark: Planck-Pizzahub

For a quick demonstration, we will use the planck-pizzahub performance benchmark located in the perf-compare directory. This project is ideal for getting started because it is completely self-contained. It requires no external integrations, which means you do not have to set up Google OAuth or Stripe keys to see it run.

You can clone the repository from . This project acts as a reference implementation for a complete monolith, showcasing features such as:

1. Server-Sent Events (SSE): It leverages Planck's built-in SSE hub to push live order status updates directly to kitchen and delivery dashboards.


2. Third-Party Authentication: It implements Google OAuth for user sign-in.


3. Payments: It integrates Stripe checkout flows and handles Stripe webhook events.

You can deploy and run this sample application using the same planctl workflow. It serves as a blueprint for building modern hypermedia apps using Datastar and Planck.