How the GeoLibre SQL Workspace Supports Apache Sedona and CereusDB: A Technical Deep Dive

The GeoLibre SQL Workspace supports Apache Sedona through a dual-engine architecture that automatically chooses between a native Rust side‑car (SedonaDB) and an in‑browser WASM fallback called CereusDB.

The SQL Workspace is a dockable panel in the open‑source GeoLibre geospatial application that enables users to execute spatial SQL queries against loaded vector layers. According to the opengeos/GeoLibre source code, the workspace implements three distinct SQL engines, with Apache Sedona receiving specialized treatment through its unique browser‑and‑desktop deployment model.

Three SQL Engines in the Workspace

The workspace offers three interchangeable engines for running spatial SQL:

Engine	Runtime Environment	Core Technology	Source File
DuckDB Spatial	Browser only	DuckDB‑WASM	packages/processing/src/sidecar-client.ts
PGlite (PostGIS)	Browser only	PGlite‑WASM	packages/processing/src/sidecar-client.ts
Apache Sedona	Browser or Desktop	CereusDB (WASM) in browser, SedonaDB side‑car (Rust/DataFusion) on desktop	packages/processing/src/sidecar-client.ts, apps/geolibre-desktop/src/lib/sedona-workspace.ts, backend/geolibre_server/geolibre_server/app/sql.py

The Apache Sedona implementation stands apart because it operates across both deployment targets through two distinct backends managed by automatic failover logic.

The Two-Backend Sedona Architecture

CereusDB: In-Browser Sedona via WebAssembly

When users select Apache Sedona in a browser environment, GeoLibre lazily loads the CereusDB WebAssembly module. CereusDB is a compiled build of SedonaDB—the single‑node Rust engine built on Apache DataFusion and Apache Arrow—packaged for browser execution.

Key characteristics of the CereusDB implementation:

• Lazy loading: The ≈ 40 MB WASM blob is fetched only upon first Sedona query execution, preserving initial application bundle size
• SQL parity: Exposes identical dialect to native SedonaDB, supporting statements like SELECT ST_Area(geometry) FROM my_layer
• Offline capability: Runs completely client‑side without server dependencies

The loader implementation resides in apps/geolibre-desktop/src/lib/cereus-loader.ts:

import { loadCereusDb } from "@geolibre/processing";

(async () => {
  const cereus = await loadCereusDb();          // fetches the ~40 MB WASM blob
  const rows = await cereus.sql(`
    SELECT ST_Buffer(geometry, 0.5) AS buf FROM my_layer
  `);
  console.log(rows);
})();

SedonaDB Side-Car: Native Rust Engine for Desktop

On desktop installations, GeoLibre can leverage an optional SedonaDB side‑car providing superior performance for large datasets. This backend is implemented through:

• FastAPI endpoints (/sql/status, /sql/run) defined in backend/geolibre_server/geolibre_server/app/sql.py
• Native Rust execution via the apache-sedona[db] optional extra
• Automatic view registration where each loaded vector layer becomes a named SQL view

The side‑car avoids the 40 MB WASM download and handles substantially larger datasets through native DataFusion execution.

Automatic Backend Selection

The workspace implements transparent failover between backends without user intervention. The selection logic in apps/geolibre-desktop/src/lib/sedona-workspace.ts follows this priority:

1. Probe side‑car availability via fetchSqlStatus in @geolibre/processing
2. Use SedonaDB side‑car if reachable (preferred for performance)
3. Fall back to CereusDB automatically if side‑car is unavailable

This ensures consistent functionality whether running in a browser, a desktop build without optional dependencies, or a fully provisioned desktop environment.

Data Flow for Sedona Queries

User → SQL Workspace UI
    → @geolibre/processing.runSedonaSql()
        → (if side‑car reachable) POST /sql/run  ← SedonaDB side‑car
        → (else) CereusDB WASM execution
    ← JSON result (rows + GeoJSON geometry)
→ UI displays results / offers "Add as layer" or "Export CSV"

The request and response types are defined in packages/processing/src/sidecar-client.ts, which exports SedonaSqlRequest and SedonaSqlResult interfaces.

Practical Usage Examples

Running Sedona SQL from Application Code

The runSedonaSql helper handles backend selection automatically:

import { runSedonaSql } from "@geolibre/processing";

const statement = `
  SELECT id, ST_Area(geometry) AS area
  FROM my_layer
  WHERE ST_Intersects(geometry, ST_GeomFromText('POLYGON((...))'))
`;

const payloadLayers = [{ name: "my_layer", type: "geojson" }];

runSedonaSql({ sql: statement, layers: payloadLayers })
  .then((result) => {
    console.table(result.rows);
    // result.geojson contains the geometry column as GeoJSON features
  })
  .catch((err) => console.error("Sedona query failed:", err));

The function internally branches between side‑car and WASM execution at lines 1070–1072 of packages/processing/src/sidecar-client.ts.

Direct Side-Car Access from Python

For custom tooling or debugging, query the side‑car directly:

import httpx

resp = httpx.post(
    "http://127.0.0.1:8765/sql/run",
    json={"sql": "SELECT COUNT(*) FROM my_layer", "layers": []},
)
print(resp.json())

The FastAPI route implementation spans lines 57–85 in backend/geolibre_server/geolibre_server/app/sql.py.

Core Implementation Files

File	Responsibility
packages/processing/src/sidecar-client.ts	Type definitions, runSedonaSql helper, backend selection logic
apps/geolibre-desktop/src/lib/sedona-workspace.ts	UI orchestration, side‑car probing, result mapping
apps/geolibre-desktop/src/lib/cereus-loader.ts	Dynamic WASM module loading for CereusDB
backend/geolibre_server/geolibre_server/app/sql.py	FastAPI routes exposing native SedonaDB
backend/geolibre_server/geolibre_server/sedona_ops.py	Python wrapper for apache-sedona[db] library
docs/user-guide/sql-workspace.md	User documentation for Sedona features and requirements

Summary

• Dual-engine design: Apache Sedona support combines a high‑performance Rust side‑car (SedonaDB) with a portable WebAssembly fallback (CereusDB)
• Zero-config failover: The workspace automatically selects the optimal backend based on availability
• SQL compatibility: Both engines expose identical SedonaSQL dialect for consistent query behavior
• Performance scaling: Side‑car handles large datasets; CereusDB enables browser‑only deployments
• Modular architecture: Clean separation between processing logic (@geolibre/processing), desktop integration, and server components

Frequently Asked Questions

What is CereusDB and how does it relate to Apache Sedona?

CereusDB is a WebAssembly compilation of SedonaDB, the single‑node Rust engine from the Apache Sedona project. It brings full SedonaSQL capabilities to browser environments without requiring server infrastructure. CereusDB maintains dialect parity with native SedonaDB, ensuring queries execute identically across both backends.

Can I use Apache Sedona in GeoLibre without installing the desktop side‑car?

Yes. The CereusDB WASM fallback loads automatically when the side‑car is unavailable. The first query triggers a ≈ 40 MB download, after which SedonaSQL executes entirely client‑side. This enables Sedona functionality in browser deployments and desktop installations without the optional apache-sedona[db] dependency.

How does the workspace decide between CereusDB and the SedonaDB side‑car?

The selection occurs in apps/geolibre-desktop/src/lib/sedona-workspace.ts. On query initiation, the workspace probes /sql/status on the side‑car. A successful response routes execution to the native Rust engine; failure triggers automatic fallback to CereusDB. This process is transparent to users and requires no manual configuration.

What are the performance implications of each Sedona backend?

The SedonaDB side‑car offers superior performance for large datasets through native Rust execution and avoids the 40 MB WASM payload. CereusDB incurs an initial download cost and runs within browser memory constraints, but eliminates server setup and works completely offline. The workspace's automatic preference for the side‑car optimizes for performance when both are available.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}