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

> Discover how the GeoLibre SQL Workspace powers Apache Sedona and CereusDB using its dual-engine architecture. Explore automatic engine selection for optimal performance.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: deep-dive
- Published: 2026-08-01

---

**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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts) |
| PGlite (PostGIS) | Browser only | PGlite‑WASM | [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts), [`apps/geolibre-desktop/src/lib/sedona-workspace.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/sedona-workspace.ts), [`backend/geolibre_server/geolibre_server/app/sql.py`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/cereus-loader.ts):

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/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:

```typescript
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`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts).

### Direct Side-Car Access from Python

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

```python
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`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/sql.py).

## Core Implementation Files

| File | Responsibility |
|------|----------------|
| [`packages/processing/src/sidecar-client.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/sidecar-client.ts) | Type definitions, `runSedonaSql` helper, backend selection logic |
| [`apps/geolibre-desktop/src/lib/sedona-workspace.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/sedona-workspace.ts) | UI orchestration, side‑car probing, result mapping |
| [`apps/geolibre-desktop/src/lib/cereus-loader.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/lib/cereus-loader.ts) | Dynamic WASM module loading for CereusDB |
| [`backend/geolibre_server/geolibre_server/app/sql.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/app/sql.py) | FastAPI routes exposing native SedonaDB |
| [`backend/geolibre_server/geolibre_server/sedona_ops.py`](https://github.com/opengeos/GeoLibre/blob/main/backend/geolibre_server/geolibre_server/sedona_ops.py) | Python wrapper for `apache-sedona[db]` library |
| [`docs/user-guide/sql-workspace.md`](https://github.com/opengeos/GeoLibre/blob/main/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`](https://github.com/opengeos/GeoLibre/blob/main/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.