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

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, where the DuckDB-WASM instance is configured with spatial capabilities enabled.

-- 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, which handles the PGlite initialization and PostGIS extension loading.

-- 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, which detects the environment and initializes the appropriate backend.

-- 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 – Official documentation of engine behavior
• apps/geolibre-desktop/src/components/processing/SQLWorkspaceDialog.tsx – UI component rendering the engine selector
• packages/processing/src/engines/duckdb.ts – DuckDB-WASM setup with spatial extension
• packages/processing/src/engines/pglite.ts – PGlite/PostGIS boot sequence
• 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.

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