Database: support loading PGlite extensions (e.g. PostGIS) in local development

[nakamori1024]

Which area does this feature relate to?

Building Blocks (existing), Local development / mocking

Describe the feature you'd like to request

Support loading PGlite extensions (e.g. PostGIS) in the Database Block's local implementation.

Locally the Database Block runs on PGlite, and there is currently no way to load Postgres extensions into it — CREATE EXTENSION postgis fails in local dev, while the same code works on Aurora PostgreSQL once deployed.

PGlite v0.4 added PostGIS support via the @electric-sql/pglite-postgis package, so the main work on the Block side is exposing PGlite's existing extensions constructor option (plus a PGlite version bump — see Proposed solution).

Use case

We build GIS applications, and PostGIS is a hard requirement for our backends (spatial queries, geometry columns, spatial indexes).

Because the local PGlite instance can't load PostGIS, any code path involving spatial SQL cannot be developed or tested locally — breaking the local/production parity that Blocks is built around. Today we have to deploy to a sandbox for every spatial-query iteration.

A generic extension option would also benefit users of other PGlite extensions such as pgvector.

Proposed solution

I considered three possible approaches. Each has trade-offs, so rather than pushing one, I'd like to present the comparison and leave the design decision to the maintainers, who know best how it fits the framework's philosophy.

Option A: Bundle all supported extensions by default

CREATE EXTENSION postgis would just work locally with zero configuration.

• Pros: Zero configuration.
• Cons: @electric-sql/pglite-postgis alone is ~20 MB unpacked (comparable to PGlite itself at ~25 MB, per npm registry metadata). Every project would pay that install and dependency cost even when it doesn't use spatial data, and bb-data's own dependency footprint would grow significantly.

Option B: Declare extensions by name

const db = new Database(scope, "main", {
  extensions: ["postgis"],
});

The local PGlite implementation maps known names to extension packages and resolves them via dynamic import ("postgis" → @electric-sql/pglite-postgis). The package would be an optional peer dependency, installed only by users who need it; if it's missing, the dev server fails at startup with an error that includes the exact install command. On AWS the declaration is a no-op, since Aurora PostgreSQL supports PostGIS natively.

• Pros: PGlite, as a local implementation detail, never leaks into application code. DatabaseOptions also already has a precedent for a declarative option that only one side interprets: postgresVersion (added in fix(bb-data): bump Aurora PostgreSQL engine version 16.4→16.13 (retired) + make configurable #220) is read only by the Aurora deployment path and ignored locally. extensions would be its mirror image — read only by the local implementation, ignored on Aurora.
• Cons: bb-data has to maintain the name-to-package mapping, so the range of usable extensions is gated on bb-data updates.

Option C: Pass PGlite's extensions option through

import { postgis } from "@electric-sql/pglite-postgis";

const db = new Database(scope, "main", {
  localExtensions: { postgis },
});

• Pros: Everything PGlite supports works immediately, with no mapping to maintain in bb-data. The dependency is explicit — the import statement itself documents it.
• Cons: Users import modules and types from @electric-sql/pglite directly, breaking the abstraction where Blocks hides the local implementation behind a single line of code.

Prerequisite (common to all options)

bb-data currently depends on @electric-sql/pglite@^0.2.0, while PostGIS requires PGlite ≥ 0.4 (latest is 0.5.x). So any of the above needs a PGlite version bump first. That likely warrants separate consideration of whether existing local databases stored under .bb-data/ remain readable across the upgrade, and how to handle bb-distributed-data, which also depends on PGlite ^0.2.0.

Note

@electric-sql/pglite-postgis is currently experimental upstream. Since Options B and C are both opt-in installs, that risk stays with the user rather than with Blocks (extension-specific bugs get reported upstream). PGlite's extensions mechanism itself is a standard part of PGlite, and extensions such as pgvector are distributed through the same mechanism (pgvector ships bundled with the PGlite package).

Alternatives considered

No response

Additional context

No response

Is this something you'd be interested in working on?

• I may be able to implement this feature request
• This feature might incur a breaking change

[adrianjoshua-strutt]

Hello @nakamori1024
Thank you for this feature request. We will discuss this internally and will get back to you once we have an update.

[nakamori1024]

Hello @adrianjoshua-strutt
Thank you! Looking forward to hearing the team's thoughts.