# What Spatial SQL Engines Are Supported in GeoLibre's SQL Workspace?

> Explore spatial SQL engines in GeoLibre's SQL Workspace including DuckDB, PGlite/PostGIS, and Apache Sedona with automatic spatial extension loading for ST_* functions.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: api-reference
- Published: 2026-08-04

---

**GeoLibre's SQL Workspace supports three spatial SQL engines: DuckDB (default), PostGIS via PGlite, and Apache Sedona, all with automatic spatial extension loading for full ST_* function compatibility.**

The **SQL Workspace** in GeoLibre enables direct execution of spatial SQL without leaving the application. Whether you need lightweight in-browser processing, full PostGIS compatibility, or distributed spatial analytics, you can switch between engines instantly from the **Engine** menu. This guide explains each engine's capabilities, setup requirements, and when to choose one over the others.

## DuckDB Spatial (Default Engine)

**DuckDB** is the default engine and runs entirely in the browser via **DuckDB-WASM**, making it the fastest option to start using.

### Key Capabilities

- Queries loaded layers, local files, and remote URLs
- Supports public cloud buckets: `s3://`, `gs://`, `az://`
- Works offline after initial WASM download
- Automatically loads the DuckDB Spatial extension

The engine initialization happens in [`packages/processing/src/engines/duckdb.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/engines/duckdb.ts), where the DuckDB-WASM instance is configured with spatial capabilities enabled.

```sql
-- Query loaded layers or remote Parquet
SELECT name, pop_est, geometry
FROM read_parquet('s3://open-data/cities.parquet')
WHERE ST_Area(geometry) > 1000;

```

## PostGIS via PGlite

**PGlite** brings full **PostGIS** functionality to the browser by bundling a lightweight PostgreSQL runtime with the PostGIS extension.

### Setup and Performance

- First launch downloads a **~19 MB engine**
- Executes complete PostGIS SQL syntax
- Ideal when you need PostGIS-specific functions or compatibility with existing PostGIS workflows

The engine boots in [`packages/processing/src/engines/pglite.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/engines/pglite.ts), which handles the PGlite initialization and PostGIS extension loading.

```sql
-- Full PostGIS syntax support
SELECT name, ST_Centroid(geom) AS center
FROM cities
WHERE ST_Intersects(geom, ST_GeomFromText('POLYGON(...)', 4326));

```

## Apache Sedona (CereusDB / SedonaDB)

**Apache Sedona** provides distributed spatial SQL capabilities with two runtime modes depending on your environment.

### Browser: CereusDB

- Runs on **CereusDB**, a WebAssembly build of Apache SedonaDB
- Lazily downloaded on first use
- Suitable for moderate dataset sizes

### Desktop: SedonaDB Sidecar

- Available in the desktop app when the optional `sedona` extra is installed
- Better performance for **large layers**
- Runs as a sidecar process alongside the main application

The engine selection logic resides in [`packages/processing/src/engines/sedona.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/engines/sedona.ts), which detects the environment and initializes the appropriate backend.

```sql
-- Sedona spatial SQL works identically
SELECT name, ST_Buffer(geometry, 0.01) AS buffered
FROM cities
WHERE ST_Contains(ST_GeomFromWKT('POLYGON(...)'), geometry);

```

## How to Switch Between Engines

The **Engine** menu in the top-right corner of the SQL Workspace controls which engine processes your queries. Follow these steps:

1. Open **Processing → SQL Workspace**
2. Click the **Engine** menu (top-right)
3. Select **DuckDB**, **PostGIS**, or **Apache Sedona**
4. Run your query—the selected engine executes it immediately

All three engines automatically load their spatial extension, so functions like `ST_Centroid`, `ST_Area`, `ST_Buffer`, `ST_Intersects`, and `ST_Contains` work consistently regardless of your choice.

## Engine Comparison

| Engine | Best For | Initial Download | Offline Use |
|--------|----------|------------------|-------------|
| **DuckDB** | Fast startup, remote data, general queries | Minimal (~3 MB WASM) | Yes |
| **PostGIS** | PostGIS compatibility, complex spatial operations | ~19 MB | Yes |
| **Apache Sedona** | Large-scale analytics, distributed processing | Deferred (CereusDB) or none (desktop sidecar) | Limited (CereusDB requires download) |

## Key Implementation Files

According to the GeoLibre source code, these files define the spatial SQL engine architecture:

- [`docs/user-guide/sql-workspace.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/user-guide/sql-workspace.md) – Official documentation of engine behavior
- [`apps/geolibre-desktop/src/components/processing/SQLWorkspaceDialog.tsx`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/components/processing/SQLWorkspaceDialog.tsx) – UI component rendering the engine selector
- [`packages/processing/src/engines/duckdb.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/engines/duckdb.ts) – DuckDB-WASM setup with spatial extension
- [`packages/processing/src/engines/pglite.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/engines/pglite.ts) – PGlite/PostGIS boot sequence
- [`packages/processing/src/engines/sedona.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/processing/src/engines/sedona.ts) – CereusDB and SedonaDB sidecar initialization

## Summary

- **Three spatial SQL engines** are supported: DuckDB, PostGIS (PGlite), and Apache Sedona
- **DuckDB** is the default, fastest to load, and handles remote data sources
- **PostGIS** provides full PostgreSQL/PostGIS compatibility with a larger initial download
- **Apache Sedona** scales to large datasets via CereusDB in-browser or SedonaDB sidecar on desktop
- All engines **auto-load spatial extensions**—no manual configuration needed
- Switch instantly via the **Engine** menu in the SQL Workspace UI

## Frequently Asked Questions

### How do I know which spatial SQL engine to use?

Choose **DuckDB** for quick queries and remote data access, **PostGIS** when you need specific PostGIS functions or PostgreSQL compatibility, and **Apache Sedona** when processing large datasets that exceed browser memory limits. All engines support the same core `ST_*` functions, so your queries remain portable.

### Does GeoLibre require installation to run spatial SQL?

No. The **DuckDB** and **PostGIS** engines run entirely in the browser via WebAssembly. Only **Apache Sedona** offers an optional desktop sidecar for better performance with large layers—otherwise, it too runs in-browser via CereusDB.

### Can I use spatial SQL offline in GeoLibre?

Yes. **DuckDB** and **PostGIS** engines work offline after their initial download. The **CereusDB** variant of Apache Sedona requires a one-time download but then functions offline. The desktop **SedonaDB sidecar** requires the desktop application to be running but has no additional download requirements once installed.

### Are PostGIS-specific functions available in DuckDB or Sedona?

No. While all engines support standard OGC spatial functions (`ST_Centroid`, `ST_Buffer`, etc.), PostGIS-specific extensions and proprietary functions only work when the **PostGIS** engine is selected. For maximum portability, stick to standard spatial SQL syntax.